When two tracks are played in sequence without interruption, on_playback_stop is not called between two on_playback_new_track calls. Is this intended? I was expecting to get a on_playback_stop call with play_control::stop_reason_eof parameter when the first track finishes playing.

Yes, that is intended.
stop_reason_eof signals rather "end of playlist", or more correctly "end of current playback order".

Got it. It's slightly misleading b/c eof usually means end of file. As you pointed, "end of playlist", or more correctly "end of current playback order" makes it intuitively understandable. It can be clarified using extra comments in the next release of SDK.

On a second thought, it's not consistent with on_playback_stop callbacks with play_control::stop_reason_starting_another as its parameter. In this case, though the playback is still going on, a stop callback is made. This inconsistency somehow better be cleaned up in the next release, either getting stop callbacks whenever a track finishes playing (which I believe is the original intention by looking the name ...eof), or not getting any stop callback as long as a track is playing.

Getting a stop callback for a track gives a good chance of identifying the playing playlist the track belongs to. Currently, since only on_playback_new_track callback is made, the name/index of the playing playlist which was correct at the beginning of play might have changed during playback. Tracking those changes during playback require subscribing to on_playlists_removed and on_playlists_reorder and extra processing. All this complication might have been made easy if a single callback is made when a track finishes playing.

(emphasis mine) That is not true. Playback is stopped, then started elsewhere.Breaking compatibility with all existing 0.9 components is seldom a good idea.Which is exactly how it is working now.

You are looking at things the wrong way round. Just because a reason EOF exists, it doesn't mean you will/should get it on every EOF. It means when you receive that reason, it was because of the EOF being reached. With a bit of thinking you can deduce when you will actually receive it.

As far as tracking playlist (and playlist item) positions, you probably should see the playlist_position_reference_tracker helper class.

Let me apply your reasoning to other scenario word by word. Just because a reason on_playback_new_track exists, it doesn't mean you will/should get it on every new track play. It means when you receive that reason, it was because of the a new track being played. Does this make sense to you?

Anyhow, as you suggested, I found playlist_position_reference_tracker. This might be what I'll use.

I'm curious. Why do you want to know the playlist and index of the playing track when playback is stopped? What does your component do with that information?

So your point is it should be understood by a complete stop and a new start of a sequence of play? But even when the new track is in the same playlist, stop_reason_starting_another is sent...

There are four reasons why a stop callback is made. My point is it's not easy relate these reasons under the same cause.
1. Is the stop initiated by user? stop_reason_eof is not so.
2. Is the stopped track played incompletely? stop_reason_eof is not so.
3. Is there no track playing after the stop? stop_reason_starting_another is not so.

I'm not suggesting to fix/change something by breaking compatibility. However, if these subtlety can be documented somewhere and made available, it will be beneficial to newbie developers. Well, this thread may already be serving as a piece of documentation. So we are somehow productive here, I hope.

No... on_playback_new_track() would literally mean it is called on new tracks (being played). I broke down stop_reason_eof in a similar way: the reason playback stopped was the end of file being reached. Besides on_playback_new_track is a callback function, not a reason: they don't compare. If it was on_playback_eof() I would agree with you - but it's not.

(And no you shouldn't expect on_playback_new_track to be called unless you explicitly request it by registering your callback and specifying you want that callback function. If you explicitly request something I would expect to receive it!)

(Edit: And BTW part of the thinking "the other way around" was when you would actually receive on_playback_stop generally and what it actually means, as that would be a prerequisite for receiving any reason in the first place. Not that you may not receive it for no particular reason which seems to be your interpretation from your post.)

I'm trying to implement a feature that removes a completely played tracks from the playlist it belongs to. When a track starts to play, I get a callback, and I can obtain playing playlist index. Since this index may change during playback, it is necessary to listen to the playlist events to update the playing playlist index.

If it's possible to get a stop callback before getting a new_track callback, get_playing_playlist can be called to obtain the index of playing playlist no matter how many playlists are removed/reordered during playback.

Let's assume "playback session" to be a period which begins when an output device is opened and DSP chain is initialized, on the other hand ends when DSPs and output are flushed and closed.

on_playback_starting is then sent at the beginning of a "playback session", with information about how that was made (double-clicking a track, pressing the Next button, etc.).

Because the output device stays open when tracks play just one after another, no on_playback_starting or on_playback_stop notifications are sent. Only on_playback_new_track informs everybody which track is currently being played.

When there are no more files to play, user presses the stop button, the application shuts down, etc., on_playback_stop event is fired, again with the reason why. A "playback session" ends and the output device is closed - that's common for all stop reasons:
* stop_reason_user - User pressed stop button, playback session ends.
* stop_reason_eof - Playback reached end of playlist, playback session ends.
* stop_reason_starting_another - User started playback elsewhere, current playback session ends and a new one begins.
* stop_reason_shutting_down - Application is shutting down, playback session ends.

You were - this was certainly about changing the behavior, not documentation:

I hope you realise you are not meant to modify playlists, playback etc. within these callbacks. Only read information. You would need to use a main_thread_callback, and by the time you receive that the playlist contents could in fact have changed (for example.. the callback called before yours may be doing something similar!) So you will need to track the playlist position regardless unless you like obscure bugs.

I didn't suggest it by breaking the compatibility. If it's possible to do so without breaking the compatibility, like introducing another subclass of playback_callback class (there are many classes named with suffix _v2, _v3, ...), it would be a good news to me. If not, more documentation will serve the purpose.

The concept of "playback session" concurs with the four reasons of stop. Still I think that's the internal details of SDK implementation, which better be kept transparent to the users of SDK. In case of stop_reason_starting_another, it would have been implemented to keep the existing playback session. Or, it would have been implemented that every new track starts a new playback session. These might be affected by the choice of SDK developers, OS limitations, other historic reasons, or related features (possibly crossfade?). The less exposed details, the more independence between components and SDK core.


Yes, you are right. I actually meant human users may manipulate playlists (create, reorder, remove, ...).

Hmm, now I came to think it would be good to have some unique identifier to playlists instead of names (can be duplicated and change any time) or index (can change anytime). Well it may deserve another thread of discussion. Let's not get into that.

You could just ignore on_playback_stop notifications with reasons you are not interested in and get on with your life. Like everyone else.

Please don't discourage newbie developers like that. There are a lot to figure out for component development, and it's natural to be curious and questioning, given the circumstances foobar SDK is not fully documented. People might be just ignoring parts they don't understand or are not interested. But some might be willing to investigate and ask why, and it might carry some value. For example, it's the first time "playback session" is explained in detail in this forum.

For the sake of other newbie developers like me, let me conclude what I understood in this thread:
1. on_playback_stop is dual to on_playback_starting, not to on_playback_new_track.
2. on_playback_starting signals the beginning of a "playback session", and on_playback_stop signals the end of it. Look at Yirkha's comment above to understand what the "playback session" is.
3. During a playback session, on_playback_new_track is called whenever a track starts to play.
4. If play_control::stop_reason_eof is given as the parameter of on_playback_stop, this actually indicates the end of a session not initiated by the user (like the end of a playlist) at lease in the current SDK.
5. To get notified when a track finishes playing, both on_playback_stop (reason should be stop_reason_eof) and on_playback_new_track has to be implemented. Just implementing the latter is insufficient because there is a situation where there is no next track to play when it's finished playing a track.

Let me explain in more words what I meant with my last post, since apparently you did not understand my intention:
In your on_playback_stop() implementation, check the value of the reason parameter and if it isn't one of the values you are interested in, then skip any further processing of the notification.
This is a proven technique that everyone has been using for years.

Just to make this absolutely clear: There is no notification for end-of-track. The above is a workaround.