From 6c87aa3c449c5e6e86130ec22ff5f8adc9b7f69f Mon Sep 17 00:00:00 2001 From: Maxim Raznatovski Date: Wed, 7 Oct 2026 20:15:52 +0200 Subject: [PATCH 1/2] docs: allow a gap at player format changes --- README.md | 2 +- roles/player/v1.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 86db52e..29d0859 100644 --- a/README.md +++ b/README.md @@ -1300,7 +1300,7 @@ The `player` object in [`stream/start`](#server--client-streamstart) has this st The format MUST be one the client listed in its [`supported_formats`](#client--server-clienthello-playerv1-support-object). -When the `player` object changes the format of an active stream, chunks sent before this message are in the previous format and chunks sent after it are in the new format. Servers MUST timestamp the first chunk in the new format to follow the last chunk in the previous format on the existing timeline, and MUST NOT resend audio already sent. +When the `player` object changes the format of an active stream, chunks sent before this message are in the previous format and chunks sent after it are in the new format. Servers SHOULD timestamp the first chunk in the new format to start where the last chunk in the previous format ends on the existing timeline, MUST NOT timestamp it to start earlier, and MUST NOT resend audio already sent. Clients MUST keep buffered chunks and decode each chunk in the format that was in effect when it was received. A player that cannot switch its output between the formats it lists without a gap SHOULD list a single `sample_rate` and `channels` in [`supported_formats`](#client--server-clienthello-playerv1-support-object), in which case the server resamples for it. diff --git a/roles/player/v1.md b/roles/player/v1.md index e98c053..5042f72 100644 --- a/roles/player/v1.md +++ b/roles/player/v1.md @@ -93,7 +93,7 @@ The `player` object in [`stream/start`](../../messaging.md#server--client-stream The format MUST be one the client listed in its [`supported_formats`](#client--server-clienthello-playerv1-support-object). -When the `player` object changes the format of an active stream, chunks sent before this message are in the previous format and chunks sent after it are in the new format. Servers MUST timestamp the first chunk in the new format to follow the last chunk in the previous format on the existing timeline, and MUST NOT resend audio already sent. +When the `player` object changes the format of an active stream, chunks sent before this message are in the previous format and chunks sent after it are in the new format. Servers SHOULD timestamp the first chunk in the new format to start where the last chunk in the previous format ends on the existing timeline, MUST NOT timestamp it to start earlier, and MUST NOT resend audio already sent. Clients MUST keep buffered chunks and decode each chunk in the format that was in effect when it was received. A player that cannot switch its output between the formats it lists without a gap SHOULD list a single `sample_rate` and `channels` in [`supported_formats`](#client--server-clienthello-playerv1-support-object), in which case the server resamples for it. From b9d4bf6110b54e44ec8b523de22c1ca5372afda5 Mon Sep 17 00:00:00 2001 From: Maxim Raznatovski Date: Wed, 7 Oct 2026 20:15:58 +0200 Subject: [PATCH 2/2] docs: make players responsible for gapless format switches --- README.md | 2 +- roles/player/v1.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 29d0859..e0f4786 100644 --- a/README.md +++ b/README.md @@ -1302,7 +1302,7 @@ The format MUST be one the client listed in its [`supported_formats`](#client--s When the `player` object changes the format of an active stream, chunks sent before this message are in the previous format and chunks sent after it are in the new format. Servers SHOULD timestamp the first chunk in the new format to start where the last chunk in the previous format ends on the existing timeline, MUST NOT timestamp it to start earlier, and MUST NOT resend audio already sent. -Clients MUST keep buffered chunks and decode each chunk in the format that was in effect when it was received. A player that cannot switch its output between the formats it lists without a gap SHOULD list a single `sample_rate` and `channels` in [`supported_formats`](#client--server-clienthello-playerv1-support-object), in which case the server resamples for it. +Clients MUST keep buffered chunks and decode each chunk in the format that was in effect when it was received, and SHOULD switch their output between formats without adding a gap. A player that cannot switch its output between the formats it lists without a gap SHOULD list a single `sample_rate` and `channels` in [`supported_formats`](#client--server-clienthello-playerv1-support-object), in which case the server resamples for it. ### Server → Client: `stream/clear` player diff --git a/roles/player/v1.md b/roles/player/v1.md index 5042f72..0acd2a5 100644 --- a/roles/player/v1.md +++ b/roles/player/v1.md @@ -95,7 +95,7 @@ The format MUST be one the client listed in its [`supported_formats`](#client--s When the `player` object changes the format of an active stream, chunks sent before this message are in the previous format and chunks sent after it are in the new format. Servers SHOULD timestamp the first chunk in the new format to start where the last chunk in the previous format ends on the existing timeline, MUST NOT timestamp it to start earlier, and MUST NOT resend audio already sent. -Clients MUST keep buffered chunks and decode each chunk in the format that was in effect when it was received. A player that cannot switch its output between the formats it lists without a gap SHOULD list a single `sample_rate` and `channels` in [`supported_formats`](#client--server-clienthello-playerv1-support-object), in which case the server resamples for it. +Clients MUST keep buffered chunks and decode each chunk in the format that was in effect when it was received, and SHOULD switch their output between formats without adding a gap. A player that cannot switch its output between the formats it lists without a gap SHOULD list a single `sample_rate` and `channels` in [`supported_formats`](#client--server-clienthello-playerv1-support-object), in which case the server resamples for it. ### Server → Client: `stream/clear` player