How to use struct sp_audio_buffer_stats

Question

Overview

To play audio with libspotify, you first register a music_delivery callback and a get_audio_buffer_stats callback. You establish a logged in session, call sp_session_player_load to load a track, wait for it to be ready, then call sp_session_player_play to start playback.

At this point, libspotify will start calling your music_delivery to deliver audio data at regular intervals. Normally you will write this data into a local buffer, and use some other library to play the audio from that buffer. Most probably, that library will also issue you regular callbacks requesting data from your buffer. If libspotify fails to deliver audio data fast enough, eventually your library will ask you for audio data and you will have none to provide, at which point the sound will stutter or drop out.

To try to avoid this, libspotify also calls get_audio_buffer_stats to find out if you have suffered drop outs recently and how much audio is left in your buffer, and adjusts the rate at which it pulls down audio from the server to compensate.

How do you go about using sp_audio_buffer_stats?

You use it to tell libspotify the current status of your audio buffer and the number of dropouts you've had since it last queried.

How do I fill in the stutter and samples variables?

Stutter should be the number of times you run out of audio data and failed to deliver it on time to whatever is playing the audio, causing the sound to stutter or drop out.

I assume, but am not 100% sure, that samples should be the number of samples that you currently have buffered - i.e. that you've received from libspotify and stored, but not yet played. I would guess this is measured in frames, i.e. samples per channel, since you can't usefully subdivide frames.

Where do I declare it?

I don't really understand this part of the question. Do you mean where to define the get_audio_buffer_stats callback function? It probably makes most sense to define it in the same place as you define the music_delivery callback. Do you mean where to store the sp_audio_buffer_stats struct? You don't - your callback receives a pointer to one that exists already and you fill it in.

Does it come from the buffer part of the code?

Again, I'm not certain I understand here. Your code that puts data into your buffer and takes it out again is the part that has the information to report stutters and buffer state. In the jukebox example, audio packets are buffered in a data structure called audio_fifo_t. I don't believe it has any bookkeeping to track the number of samples in the buffer or the number of stutters, but you could conceivably add it in audio.c, audio.h and possibly in the platform-specific audio code.

Would that be the music_delivery method?

I don't understand. The music_delivery method does put audio into the buffer, so in that sense it directly or indirectly increases the number of samples in the buffer. It has no effect on the number of stutters - those happen when trying to take audio out of the buffer.

I am not affiliated with Spotify. I have used the music playing API to write experimental code to send audio to a networked music player, so while I have experience of implementing music_delivery and get_audio_buffer_stats, I haven't had much experience of passing it on to a traditional audio API.

See also here: spotify session callback get_audio_buffer_stats