Skip to content

Clarify use of stream/start, stream/end and stream/clear messages #83

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
OnFreund wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Clarify use of stream/start, stream/end and stream/clear messages #83

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ca1ed20
Enhance description for `stream/end` message
OnFreund May 2, 2026
8669796
Clarify stream lifecycle: when to use stream/end vs stream/clear
OnFreund May 19, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 13 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -231,6 +231,10 @@ sequenceDiagram
Server->>Client: stream/clear (roles: [player, visualizer])
end

alt Track jump (skip to different track)
Server->>Client: stream/clear (roles: [player, visualizer])
end

alt Controller role
Client->>Server: client/command (controller: play/pause/volume/switch/etc)
end
Expand Down Expand Up @@ -377,7 +381,7 @@ Server sends commands to the client. Contains role-specific command objects.

### Server → Client: `stream/start`

Starts a stream for one or more roles. If sent for a role that already has an active stream, updates the stream configuration without clearing buffers.
Starts a stream for one or more roles. If sent for a role that already has an active stream, updates the stream configuration without clearing buffers. If a parameter change requires rebuffering (e.g., a sample rate change), the receiver handles this internally — the default behavior is to not clear unless the implementation requires it. Implementations may document their specific behavior.

- `player?`: object - only sent to clients with the `player` role ([see player object details](#server--client-streamstart-player-object))
- `artwork?`: object - only sent to clients with the `artwork` role ([see artwork object details](#server--client-streamstart-artwork-object))
Expand All @@ -387,7 +391,7 @@ Starts a stream for one or more roles. If sent for a role that already has an ac

### Server → Client: `stream/clear`

Instructs clients to clear buffers without ending the stream. Used for seek operations.
Instructs clients to clear buffers without ending the stream. Used for seek operations and track jumps (switching to a different track without stopping the stream).

- `roles?`: string[] - which roles to clear: '[player](#server--client-streamclear-player)', '[visualizer](#server--client-streamclear-visualizer)', or both. If omitted, clears both roles

Expand All @@ -408,7 +412,13 @@ Response: [`stream/start`](#server--client-streamstart) for the requested role(s

### Server → Client: `stream/end`

Ends the stream for one or more roles. When received, clients should stop output and clear buffers for the specified roles.
Ends the stream for one or more roles. When received, clients should stop output and clear buffers for the specified roles. This message is expected to be sent when playback is over and the queue is empty. Specifically:

- **Track transitions** (a track ends and the next begins naturally): no stream commands should be sent. The stream continues uninterrupted to support gapless playback and server-inserted crossfade.
- **Seeks** (jumping to a position within the current track): send `stream/clear` instead.
- **Track jumps** (skipping to a different track): treat identically to a seek — send `stream/clear` instead of `stream/end`. Conceptually, the entire queue is a single continuous stream.

Sending `stream/end` in these cases is explicitly prohibited because it signals actual playback termination, causing clients to stop output entirely rather than continue playing.

- `roles?`: string[] - roles to end streams for ('player', 'artwork', 'visualizer'). If omitted, ends all active streams

Expand Down