Add announcement role (announcement@v1) skeleton - #101
Draft
marcelveldt wants to merge 2 commits into
Draft
marcelveldt wants to merge 2 commits into
marcelveldt wants to merge 2 commits into
Conversation
4 tasks
marcelveldt
force-pushed
the
announcement-role
branch
from
September 16, 2026 08:00
585114c to
dbbd93e
Compare
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
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.
Draft client-side reference implementation for the
announcement@v1role proposed in Sendspin/spec#126: short per-client audio clips (TTS, chimes, alerts) decoded on a second pipeline next to the media stream, with the ducking policy handed to the embedder. Opened alongside the spec PR so the discussion has a concrete client shape to poke at; it tracks the spec.What's here
announcement@v1role id,AnnouncementSupportObject(formats + ownbuffer_capacity) inclient/hello,stream/start.announcementparsing (codec params, a single requiredstart_timestamp,media_duck_db0-50 /duck_ramp_ms0-2000 / optionalvolume/ optionaloverride_mute, out-of-range values dropped to defaults),client/state.announcement, and binary type 24 (SENDSPIN_ROLE_ANNOUNCEMENT = 6, routed throughget_binary_role()unchanged). Chunks are untimed: the stream's single start time rides the codec header.AnnouncementRolefollowing the add-a-role pattern, with anAnnouncementRoleListenerthe embedder implements:on_announcement_write()(PCM, task thread) pluson_announcement_start/end()(main loop).on_announcement_start()carries the duck params,start_timestampandoverride_mute(that's where e.g. ESPHome callsapply_ducking()); it also re-fires when the server re-sendsstream/startto update config in place.on_announcement_end()fires on server end, local completion, abort, and transport loss alike, so media can never stay stuck ducked.AnnouncementTask: a dedicated lightweight decode task (own ring buffer + decoder, one extra thread). No sync machinery: output begins at the singlestart_timestampvia the time filter (or as soon as possible), which is also what aligns a coordinated multi-speaker start; chunks are never dropped for lateness and a stalled stream ends locally after 5 s.stream/endwith omitted roles ends announcements too;stream/clearis media-scoped and never touches the announcement stream (replacing a clip is astream/endthen a newstream/start).SENDSPIN_ENABLE_ANNOUNCEMENT(Kconfig default n while the spec settles; depends onSENDSPIN_ENABLE_PLAYER, which supplies the ring buffer and decoder).start_timestampandoverride_mute, client/state, binary allocation) plus a config-update-in-place test. Host build is clean under-Wall -Wextra -Wpedantic; the full suite passes.Not here yet
SendspinAnnouncementSourcefeeding thespeaker_sourcepipeline plus duck-parameter plumbing) lives in the esphome repo and needs a released sendspin-cpp first.volume, andoverride_muteare applied by the embedder at the sink/mixer; the library only transports the parameters.Marked draft until the spec PR settles.