Add player timing capabilities#69
Open
maximmaxim345 wants to merge 6 commits into
Open
Conversation
kahrendt
reviewed
Mar 4, 2026
kahrendt
reviewed
Mar 4, 2026
maximmaxim345
force-pushed
the
player-time-capabilities
branch
from
e9f9964 to
f5d7e32
Compare
kahrendt
reviewed
May 11, 2026
| - `muted?`: boolean - mute state, must be included if 'mute' is in `supported_commands` from [`player@v1_support`](#client--server-clienthello-playerv1-support-object) | ||
| - `static_delay_ms`: integer - static delay in milliseconds (0-5000), always required for players | ||
| - `required_lead_time_ms`: integer - minimum startup lead time in milliseconds (e.g., codec init, decode warmup, audio backend buffering, DAC latency), always required for players. Measured from server transmit time of the start/restart trigger ([`stream/start`](#server--client-streamstart) or [`stream/clear`](#server--client-streamclear)) to the timestamp of the first subsequent audio chunk. | ||
| - `min_buffer_ms`: integer - requested minimum ongoing buffer duration in milliseconds during playback (primarily for live streams), used to absorb network jitter and ongoing decode/playback timing variance. Always required for players. |
Contributor
There was a problem hiding this comment.
I wonder if there is a way we can give guidance on how to calculate this (required_lead_time_ms gives very specific instructions). This is a harder one to do reliably I guess, but if we could describe a way to approach this then that would be good.
I believe we had previously discussed something like looking at the distribution of time message latencies and taking like the 95th percentile or something along those lines. I think we'll have to do some experiments to really see what is actually usable in practice.
The previous split implicitly required the buffer to grow after stream/start, which is impossible for live sources. A single floor of max(required_lead_time_ms, min_buffer_ms) + static_delay_ms satisfies both startup lead and ongoing jitter buffering honestly. Also drop the 'players must size buffer_capacity to fit min_buffer' obligation (unknowable client-side for VBR codecs) and replace 'must keep buffer' with 'must schedule timestamps', matching the server's actual lever.
Live sources cannot grow the queue after playback begins, so the max(required_lead, min_buffer) + static floor must be honored upfront. Buffered sources (file playback, prefetched streams) race ahead and fill the queue past min_buffer naturally, so paying that wait at startup is pure latency without jitter benefit. Make the relaxation explicit so impls can use required_lead + static for buffered without appearing non-compliant.
marcelveldt
approved these changes
May 28, 2026
maximmaxim345
added a commit
to Sendspin/aiosendspin
that referenced
this pull request
May 29, 2026
…ms`) (#253) Adds player-reported `required_lead_time_ms` and `min_buffer_ms` in `client/state` so the server can size send-ahead per the player's startup warmup and ongoing jitter needs, dynamic across `client/state` updates and grouped via the max across members. `PushStream` uses `max(required_lead, min_buffer) + static_delay` for live sources and `required_lead + static_delay` for buffered (`PushStream.set_live_source(...)`, default buffered) since a buffered queue grows past `min_buffer` naturally after playback begins. Implements: - Sendspin/spec#69.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
There were 2 major gaps in the
player@v1role this PR aims to solve:Both issues are resolved by adding
required_lead_time_msandmin_buffer_msto theclient/stateplayer object. The server is then responsible for ensuring that both constraints are respected.Network latency can now also be factored into
required_lead_time_msandmin_buffer_msin real time, also allowing for high-latency clients (like a player on a mobile network) under changing network conditions.