Add announcement role (announcement@v1) skeleton#101
Draft
marcelveldt wants to merge 3 commits into
Draft
Conversation
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 implementation skeleton for the
announcement@v1role proposed in Sendspin/spec#126 — short per-client audio clips (TTS, chimes, alerts) decoded on a second concurrent pipeline next to the media stream, with the ducking policy delivered to the embedder. Opening this alongside the spec PR so the discussion has a concrete client-side shape to poke at; expect it to track whatever the spec discussion decides (including the role id, if we stage it asannouncement@_draft_r1first).What's here
announcement@v1role id,AnnouncementSupportObject(formats + ownbuffer_capacity) inclient/hello,stream/start.announcementparsing (codec params +media_duck_db0–50 /duck_ramp_ms0–2000 / optionalvolume, out-of-range values dropped to defaults),client/state.announcement(state,required_lead_time_ms), binary type 24 (SENDSPIN_ROLE_ANNOUNCEMENT = 6, routed through the existingget_binary_role()helper unchanged).AnnouncementRolefollowing the documented add-a-role pattern (public header + pimpl + inbox slot + shared event ring), with anAnnouncementRoleListenerthe embedder implements:on_announcement_write()(PCM, task thread) pluson_announcement_start/end/clear()(main loop).on_announcement_start()carries the duck parameters — that's where e.g. ESPHome callsmixer_speaker.apply_ducking();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 +SendspinDecoderinstance, one extra thread, default priority below the media sync task). Deliberately no Kalman/sync machinery: announcements are per-client, so the task starts output at the first chunk's timestamp via the time filter (or immediately without sync) — honoring that timestamp is also what aligns a coordinated multi-speaker announcement — never drops late chunks, is paced by the sink's blocking writes, and ends a stalled stream locally after 5 s.SendspinClient:stream/endwith omitted roles ends announcements too;stream/clearwith omitted roles (a media seek) explicitly does not touch the announcement stream — only an explicitroles: ["announcement"]does.SENDSPIN_ENABLE_ANNOUNCEMENT(Kconfig default n while the spec is draft;depends on SENDSPIN_ENABLE_PLAYERsince it reuses the ring buffer + decoder sources).-Wall -Wextra -Wpedantic), full suite passes.Deliberately not here (yet)
SendspinAnnouncementSourcefeeding thespeaker_sourceannouncement pipeline + duck-parameter plumbing) lives in the esphome repo and needs a released sendspin-cpp first.volumeare applied by the embedder at the sink/mixer (where media volume already lives) — the library only transports the parameters.stream/clear) boundary is approximate in the task (buffered chunks racing the drain may go with the old clip); fine for silence-padded replacement clips, noted inline.Marked draft until the spec PR settles.