Voice audio cues

Document: SPEC-020. Revision: 1.0. Date: 2026-10-21. Lifecycle: D-097/R-103 confirmed; implementation details complete the approved four switches and shared volume. Supersedes SPEC-005's initial exclusion of notifications only for these local audio cues. Message notifications and ringing remain outside this change.

Contract

Provide short audible cues for other accounts joining and leaving the currently connected voice scope, including channel, thread, direct and temporary calls. Compare authoritative live account identities, not device IDs or saved channel membership. An initial roster is a silent baseline; transport reconnection or an observation gap longer than ten seconds resets that baseline without replay. Unchanged polls, key renewal, mute changes, other channels and self attendance produce no attendance sound. Coalesce each observed batch to at most one join and one departure cue; do not queue stale cues.

Local PTT on/off cues follow transitions of the actual transmit gate. A refused press, recording an input binding, a held duplicate press and another person's PTT produce no cue. Release, duration expiry, moderation, authority loss and local shutdown close the gate and may produce the off cue once. Sounds are playback-only and are never connected to the capture/worklet or sent as media. Acoustic pickup from speakers remains possible, as with all local playback.

Profile settings expose four independent switches, a shared volume slider and a preview action for each cue. Save explicitly with the current profile revision. Synchronize settings through the home account; an already active call uses its own account's preferences even while another account/server is browsed. Preserve unsaved edits on conflict/failure and require review before retrying a changed profile revision. Suppress delayed playback when audio is suspended/unavailable; visual voice/PTT feedback remains unchanged. Do not request microphone permission for previews or bypass browser autoplay rules.

The home server advertises profile-sounds/1. Extend account.profile with optional sounds; at least one of nickname, picture or sounds is required. Omission preserves settings; null/unknown keys/partial malformed settings reject. A successful mutation increments the shared profile revision. Return settings only in authenticated own-profile responses, not public identity projections, directories, friends, message authors or visitor attestations. Existing accounts use defaults without migration. Approved devices and password-plus-key recovery retrieve settings from the home account. Profile sound writes do not alter permissions, media leases, encryption keys or room revisions.

Configuration

sounds is a home-account user preference written only by that account's approved device using existing ticket/revision authorization. Its complete object is {join: boolean, leave: boolean, pttOn: boolean, pttOff: boolean, volume: integer}. All four booleans default true as approved. volume is percent from 0 through 100 inclusive, engineering initial value 50; zero is silence. There is no server/channel inheritance. Save applies immediately to this account's active call and on the next home-profile refresh to other clients. The device vault may cache this nonsecret preference with its account, while the server remains authoritative. Older clients omit the field and preserve it.

Fixed synthesis parameters are short sine tones with a smooth five-millisecond attack/release: join 520 then 660 Hz, leave 660 then 520 Hz, 70 ms each with a 20 ms gap, peak gain 0.06 at 100% volume. PTT on is 880 Hz and off 660 Hz, each 35 ms, peak gain 0.018 at 100%. These quieter PTT cues are deliberately brief. Volume scales these gains linearly. At most eight oscillators may be active; expired or excessive cues are dropped. The ten-second attendance baseline gap is a fixed freshness limit, not a configurable delay. No external sound assets or network requests are needed.

Testing

Unit tests cover settings defaults, exact keys/types/ranges, independent switches, silence, own-profile-only projection, authorized revision-checked persistence, omission preservation and restart. Attendance tests cover first observation, repeated roster, other-account additions/removals, self exclusion, device changes, disconnected observations, stale gaps and batch coalescing. Media tests check cues at actual gate transitions, including denied/duplicate presses and forced stops. Synthesis tests check frequencies, gain, durations, local output-only wiring, limits and suspended-context silence. Browser tests cover profile save/reload, switches, volume, previews and conflict/failure preservation. Actual audible quality remains a human listening check.

Acceptance criteria

• All four cues start enabled, can be independently disabled, and obey the shared 0–100% volume slider in profile settings across linked clients.
• Only changes of other accounts in the active voice roster produce attendance cues; initial/reconnected/stale rosters remain silent.
• Local PTT start/stop cues follow actual gate transitions once and remain quieter/shorter than attendance cues; other speakers and refused input produce none.
• Cues play through a local output path and never enter the application's capture or outgoing media graph.
• Stale writes preserve drafts; successful saves survive restart and stay private to the account.
• Suspended/unavailable audio produces no queued sounds and does not disrupt voice or visual state.