Mix_HaltMusic doesn't call music finished hook

[SDLBugzilla]

This bug report was migrated from our old Bugzilla tracker.

These attachments are available in the static archive:

• ~~Patch to add this behaviour. (SDL_mixer-halt-music-callback-RYAN1.diff, text/plain, 2009-10-08 02:27:57 +0000, 312 bytes)~~
• Patch to call music callback anytime music is stopped (music_halt_callback.diff, text/plain, 2009-10-11 00:41:34 +0000, 724 bytes)

Reported in version: 1.2.8 Reported for operating system, platform: Linux, x86

Comments on the original bug report:

On 2008-02-13 06:34:47 +0000, Alex wrote:

I don't know if this is a bug or feature, but IMO it would be much more sensible for it to call the hook function. Mix_HaltChannel does call callback functions, so there's confusing difference in behavior.

On 2008-02-18 03:11:45 +0000, Alex wrote:

*** Bug 550 has been marked as a duplicate of this bug. ***

On 2008-02-18 03:13:33 +0000, Alex wrote:

*** Bug 551 has been marked as a duplicate of this bug. ***

On 2008-02-18 03:13:50 +0000, Alex wrote:

*** Bug 552 has been marked as a duplicate of this bug. ***

On 2009-10-03 02:57:11 +0000, Sam Lantinga wrote:

Ryan, can you evaluate this? Thanks!

On 2009-10-08 02:26:57 +0000, Ryan C. Gordon wrote:

The docs for Mix_HookMusicFinished() say: "This callback is only called if the music finishes naturally."

So, it might break existing programs if we change it to run the callback during Mix_HaltMusic().

Tossing bug to Sam to decide if that's okay.

--ryan.

On 2009-10-08 02:27:57 +0000, Ryan C. Gordon wrote:

Created attachment 401 Patch to add this behaviour.

This patch will add the behaviour requested here, if you think it's safe to do so.

--ryan.

On 2009-10-09 21:43:44 +0000, Ryan C. Gordon wrote:

Honestly, I'm sort of thinking we should do this and see what breaks.

--ryan.

On 2009-10-09 22:03:39 +0000, Sam Lantinga wrote:

Okay, I remember we added this for Heroes 3, so we should probably check to see if that breaks. ;)

On 2009-10-11 00:38:16 +0000, Sam Lantinga wrote:

I looked into this more closely, and this is a sensible but dangerous change to make.

The right thing to do here is to have both the channel and music callbacks always called when a channel or music stops for any reason, but it should be passed a reason why the sound stopped.

The typical use of the music stopped callback is to pick another song to play. The assumption is that if you're explicitly halting the music that you have some other action that you are in control of that you want to take place.

If we change this behavior, then suddenly applications will be getting a finished callback when they don't expect it, and this could cause anything from application bugs to crashes.

So, I'm punting this until we do an SDL_mixer API revamp.

On 2009-10-11 00:41:34 +0000, Sam Lantinga wrote:

Created attachment 409 Patch to call music callback anytime music is stopped

This is a more comprehensive patch that calls the finished hook anytime music stops playing. If this were applied, we'd also want to change the hook function to take a reason as a parameter, and update the channel finished hook to do the same thing.

On 2012-05-25 03:08:25 +0000, Aki Koskinen wrote:

Waking up a hibernating bug here...

If the behaviour of the lib is not changed as discussed in this bug (i.e. the attached patch won't be applied) would it be appropriate to fix the documentation to reflect the reality? It currently claims that the music finished callback would be called when Mix_HaltMusic() is called but that doesn't happen.

I just spent quite an amount of time believing the documentation and wondering why my callback doesn't get called. I might not be the only one wasting time this way...

On 2012-05-29 21:38:07 +0000, Ryan C. Gordon wrote:

(In reply to comment # 11)

If the behaviour of the lib is not changed as discussed in this bug (i.e. the attached patch won't be applied) would it be appropriate to fix the documentation to reflect the reality? It currently claims that the music finished callback would be called when Mix_HaltMusic() is called but that doesn't happen.

Where does it say this?

--ryan.

On 2012-05-31 02:33:01 +0000, Aki Koskinen wrote:

(In reply to comment # 12)

(In reply to comment # 11)

If the behaviour of the lib is not changed as discussed in this bug (i.e. the attached patch won't be applied) would it be appropriate to fix the documentation to reflect the reality? It currently claims that the music finished callback would be called when Mix_HaltMusic() is called but that doesn't happen.

Where does it say this?

In http://www.libsdl.org/projects/SDL_mixer/docs/SDL_mixer.html#SEC67

[--] Any callback set by Mix_HookMusicFinished will be called when the music stops. [--]

And in http://www.libsdl.org/projects/SDL_mixer/docs/SDL_mixer.html#SEC69

[--] This sets up a function to be called when music playback is halted. Any time music stops, the music_finished function will be called. [--]

On 2012-06-01 03:29:54 +0000, Ryan C. Gordon wrote:

Sam, can we update those docs?

--ryan.