speech schema

Canonical generated docsThis section is generated from caco config schema --json. The table below preserves the runtime field path, type, required/default markers, and canonical description for every value in this slice.

Speech provider defaults — TTS, STT, audio I/O routing.

Field path	Type	Required	Default	Canonical description
`speech`	`section`	optional		Speech provider defaults — TTS, STT, audio I/O routing.
└ `speech.enabled`	`bool`	optional	true	Whether speech (TTS/STT) is enabled. Set false on headless nodes.
└ `speech.mute`	`true\|false\|local\|tts-daemon-running`	optional	local	Startup mute policy. true=start muted, false=start unmuted, local=restore last TUI toggle, tts-daemon-running=muted (TTS daemon handles speech).
└ `speech.tts`	`map`	optional		Text-to-speech defaults.
└ `speech.tts.n`	`u32`	optional	1	Maximum simultaneous agent speech slots. Default/effective 1; values <=1 play sequentially, values >1 allow that many concurrent TTS daemon playback slots.
└ `speech.tts.overlap_secs`	`u64`	optional		Optional cap on concurrent TTS daemon playback overlap. Omitted allows full-slot overlap; 0 disables intentional overlap; positive values cap overlap to that many seconds.
└ `speech.tts.chime`	`map`	optional		Deterministic per-agent chime prepended before TTS playback (generalized note count/length/gap config). Omit to disable; present defaults to a 3-note C minor chime with no transposition.
└ `speech.tts.chime.enabled`	`bool`	optional	true	Enable or disable this chime object.
└ `speech.tts.chime.root_note`	`string`	optional	C	Scale root note such as C, C#, Db, F sharp, or Bb.
└ `speech.tts.chime.scale`	`string`	optional	minor	Scale type for note slots: major or minor.
└ `speech.tts.chime.transpose_semitones`	`i32`	optional	0	Semitone transposition applied after root/scale resolution. Aliases: transpose, transposition.
└ `speech.tts.chime.num_notes`	`u32`	optional	3	Number of notes derived from the agent id (1..=16). Defaults to 3, the historical fixed chime.
└ `speech.tts.chime.note_length_ms`	`u32 or list`	optional	130	Per-note duration in ms: a single uniform value or a per-note list (short lists pad with the 130ms default).
└ `speech.tts.chime.gap_length_ms`	`u32 or list`	optional	35	Gap between notes in ms: a single uniform value or a per-gap list of length num_notes-1 (short lists pad with the 35ms default).
└ `speech.tts.model`	`string`	optional		TTS model identifier (provider-dependent).
└ `speech.tts.command_template`	`string`	optional		Shell command template for ad-hoc TTS adapters. Uses env vars such as $BODY and optional $OUTPUT_FILE.
└ `speech.tts.voice`	`string`	optional		Default voice name.
└ `speech.tts.voices`	`list[string]`	optional		Additional voice names merged into the capabilities voice list.
└ `speech.tts.voice_rotation`	`bool`	optional	true	Auto-assign distinct voices per agent sender.
└ `speech.tts.speed`	`f32`	optional		Playback speed multiplier (0.25–4.0). 1.0 = normal.
└ `speech.tts.speed_queue_modifier`	`f32`	optional	0.0	Queue-length-aware speed modifier. Effective speed = min(base + speed_queue_modifier * shared_pending_queue_depth, max_speed). 0.0 (default) preserves base speed.
└ `speech.tts.max_speed`	`f32`	optional	3.0	Upper bound for queue-aware effective playback speed. Default 3.0.
└ `speech.tts.agent_dms`	`map`	optional		Optional direct agent-message readout overlay. Inherits normal TTS settings unless fields here override them.
└ `speech.tts.agent_dms.read_aloud`	`bool`	optional	false	Read direct agent-message feed events aloud. Default false.
└ `speech.tts.agent_dms.speed`	`f32`	optional		Optional speed override for direct-message readout.
└ `speech.tts.agent_dms.speed_queue_modifier`	`f32`	optional	0.0	Queue-aware speed modifier for agent-DM readout (see speech.tts.speed_queue_modifier). 0.0 default preserves base.
└ `speech.tts.agent_dms.max_speed`	`f32`	optional	3.0	Upper bound for queue-aware agent-DM speed. Default 3.0.
└ `speech.tts.lang`	`list[string]`	optional		Ordered preferred TTS language codes. First non-blank entry is the default synthesis language; later entries are alternates/fallbacks. Empty or omitted resolves to en-US. The resolved default persists in TTS daemon runtime state across restarts.
└ `speech.tts.voice_filter`	`map`	optional		Sox-based voice filter applied post-TTS. Preset, custom sox chain, or rotation pool.
└ `speech.tts.voice_filter.preset`	`string`	optional		Named filter preset: telephone, hall, lofi, underwater, radio, whisper, cave, megaphone, robot, vintage.
└ `speech.tts.voice_filter.custom`	`string`	optional		Raw sox effect chain string (e.g. "reverb 50 highpass 300").
└ `speech.tts.voice_filter.rotation`	`map`	optional		Rotation pool for per-agent filter assignment.
└ `speech.tts.voice_filter.rotation.presets`	`list[string]`	optional		Pool of preset names to rotate through.
└ `speech.tts.voice_filter.rotation.combine_with_voice`	`bool`	optional	true	Combine filter rotation with voice rotation for unique agent identities.
└ `speech.tts.disable_voice_filters`	`bool`	optional	false	Disable voice filters even if configured. Debugging kill switch.
└ `speech.tts.daemon_sync`	`bool`	optional		Proxy TUI speech controls to TTS daemon instead of local playback.
└ `speech.tts.profiles`	`map`	optional		Named runtime-selectable TTS profile/effect bundles keyed by logical profile name. Each value uses the speech.tts shape; command-template profiles advertise their model label as profile.model or the map key.
└ `speech.tts.profiles.<profile>.model`	`string`	optional		Runtime model label for this profile; defaults to the profile key when command_template is set.
└ `speech.tts.profiles.<profile>.command_template`	`string`	optional		Shell command/effect wrapper for this profile.
└ `speech.tts.profiles.<profile>.voice`	`string`	optional		Default voice for this profile.
└ `speech.tts.profiles.<profile>.voices`	`list[string]`	optional		Additional voices exposed while this profile registry is configured.
└ `speech.tts.profiles.<profile>.speed`	`f32`	optional		Default playback speed for this profile.
└ `speech.tts.personas`	`map`	optional		Declarative TTS persona/category mappings keyed by persona name. Each persona may provide profile/model/voice/speed/filter/director-note defaults while explicit per-event overrides still win.
└ `speech.tts.personas.<persona>.profile`	`string`	optional		Named TTS profile/effect bundle for this persona.
└ `speech.tts.personas.<persona>.model`	`string`	optional		TTS model override for this persona.
└ `speech.tts.personas.<persona>.voice`	`string`	optional		TTS voice override for this persona.
└ `speech.tts.personas.<persona>.speed`	`f32`	optional		Playback speed override for this persona.
└ `speech.tts.personas.<persona>.director_note`	`string`	optional		Optional director note for downstream TTS resolvers.
└ `speech.tts.hrtf`	`map`	optional		Optional disabled-by-default HRTF processing seam for decoded TTS audio. Requires operator-provided dataset path and license/provenance metadata before processing is considered available.
└ `speech.tts.hrtf.enabled`	`bool`	optional	false	Enable HRTF processing. Default false/no-op.
└ `speech.tts.hrtf.dataset_path`	`string`	optional		Path or documented built-in token for impulse-response data.
└ `speech.tts.hrtf.dataset_license`	`string`	optional		License/provenance note for the selected dataset.
└ `speech.tts.hrtf.backend`	`string`	optional		Processing backend identifier such as identity_stereo for deterministic tests.
└ `speech.stt`	`map`	optional		Speech-to-text defaults.
└ `speech.stt.model`	`string`	optional		STT model identifier.
└ `speech.stt.language`	`string`	optional		Default STT language hint (ISO 639-1, e.g. en).
└ `speech.stt.command_template`	`string`	optional		Shell command template for ad-hoc STT adapters. Uses env vars such as $AUDIO_FILE and optional $TRANSCRIPT_FILE.
└ `speech.stt.input`	`string`	optional		Named input source for STT capture (references speech.io.inputs key).
└ `speech.stt.vad`	`map`	optional		Top-level VAD config for generic STT chunking. Applied before any STT backend.
└ `speech.stt.vad.enabled`	`bool`	optional	true	Whether VAD pre-processing is enabled.
└ `speech.stt.vad.engine`	`string`	optional	silero	VAD engine identifier (silero, webrtc, etc.).
└ `speech.stt.vad.threshold`	`f32`	optional	0.5	Speech probability threshold (0.0–1.0).
└ `speech.stt.vad.min_speech_duration_ms`	`u32`	optional	250	Minimum speech duration in ms; shorter segments are discarded.
└ `speech.stt.vad.min_silence_duration_ms`	`u32`	optional	300	Minimum silence duration in ms before a segment ends.
└ `speech.stt.vad.speech_pad_ms`	`u32`	optional	100	Padding in ms added before/after each speech segment.
└ `speech.stt.vad.model`	`string`	optional	silero-v6.2.0	VAD model name (e.g. silero-v6.2.0).
└ `speech.stt.dictation`	`map`	optional		Rolling-capture window config for scratchpad dictation.
└ `speech.stt.dictation.chunk_secs`	`u32`	optional	10	Rolling capture window in seconds.
└ `speech.stt.dictation.overlap_secs`	`u32`	optional	1	Overlap between consecutive chunks in seconds.
└ `speech.stt.smart_append`	`map`	optional		Per-chunk smart-append cleanup config.
└ `speech.stt.smart_append.enabled`	`bool`	optional	true	Whether smart-append is enabled.
└ `speech.stt.smart_append.model`	`string`	optional	fast	Text model to use for incremental cleanup.
└ `speech.stt.rewrite`	`map`	optional		Final whole-note rewrite config.
└ `speech.stt.rewrite.enabled`	`bool`	optional	true	Whether final rewrite is enabled.
└ `speech.stt.rewrite.model`	`string`	optional	fast	Text model to use for the final cleanup pass.
└ `speech.stt.rewrite.mode`	`string`	optional	full	Rewrite mode: full or append.
└ `speech.stt.scribble`	`map`	optional		Local scribble-based Whisper transcription config.
└ `speech.stt.scribble.model`	`string`	optional	large-v3-turbo-q8_0	Whisper model name.
└ `speech.stt.scribble.acceleration`	`string`	optional	default	GPU acceleration backend: default, metal, vulkan, cuda, coreml, or cpu.
└ `speech.stt.scribble.language`	`string`	optional		Optional language hint.
└ `speech.stt.scribble.vad`	`map`	optional		Voice activity detection config for scribble.
└ `speech.stt.scribble.vad.enabled`	`bool`	optional	true	Whether VAD is enabled.
└ `speech.stt.scribble.vad.model`	`string`	optional	silero-v6.2.0	Silero VAD model name.
└ `speech.stt.agent`	`map`	optional		Per-target STT config for agent panes.
└ `speech.stt.agent.rewriting`	`bool`	optional	false	Whether smart rewriting is enabled for this target.
└ `speech.stt.agent.smart_append`	`bool`	optional	false	Whether smart append (per-chunk cleanup) is enabled.
└ `speech.stt.agent.enter_after_completed`	`bool`	optional	false	Send Enter keypress after transcription completes.
└ `speech.stt.terminal`	`map`	optional		Per-target STT config for terminal/shell panes.
└ `speech.stt.terminal.rewriting`	`bool`	optional	false	Whether smart rewriting is enabled for this target.
└ `speech.stt.terminal.smart_append`	`bool`	optional	false	Whether smart append (per-chunk cleanup) is enabled.
└ `speech.stt.terminal.enter_after_completed`	`bool`	optional	false	Send Enter keypress after transcription completes.
└ `speech.stt.scratchpad`	`map`	optional		Per-target STT config for scratchpad notes.
└ `speech.stt.scratchpad.rewriting`	`bool`	optional	false	Whether smart rewriting is enabled for this target.
└ `speech.stt.scratchpad.smart_append`	`bool`	optional	false	Whether smart append (per-chunk cleanup) is enabled.
└ `speech.stt.scratchpad.enter_after_completed`	`bool`	optional	false	Send Enter keypress after transcription completes.
└ `speech.stt.text_field`	`map`	optional		Per-target STT config for text fields / chat compose.
└ `speech.stt.text_field.rewriting`	`bool`	optional	false	Whether smart rewriting is enabled for this target.
└ `speech.stt.text_field.smart_append`	`bool`	optional	false	Whether smart append (per-chunk cleanup) is enabled.
└ `speech.stt.text_field.enter_after_completed`	`bool`	optional	false	Send Enter keypress after transcription completes.
└ `speech.stt.bead`	`map`	optional		Per-target STT config for bead create form fields.
└ `speech.stt.bead.rewriting`	`bool`	optional	false	Whether smart rewriting is enabled for this target.
└ `speech.stt.bead.smart_append`	`bool`	optional	false	Whether smart append (per-chunk cleanup) is enabled.
└ `speech.stt.bead.enter_after_completed`	`bool`	optional	false	Send Enter keypress after transcription completes.
└ `speech.io`	`map`	optional		Audio I/O routing.
└ `speech.io.output`	`map`	optional		Output audio routing.
└ `speech.io.output.mode`	`string`	optional		Routing mode: local-default, local-device, pulse-default, or a named pulse output.
└ `speech.io.output.device`	`string`	optional		Explicit device identifier (only for local-device mode).
└ `speech.io.input`	`map`	optional		Input audio routing.
└ `speech.io.input.mode`	`string`	optional		Routing mode: local-default, local-device, pulse-default, or a named pulse output.
└ `speech.io.input.device`	`string`	optional		Explicit device identifier (only for local-device mode).
└ `speech.io.outputs`	`list[map]`	optional		Named PulseAudio output endpoints for TUI cycle rotation.
└ `speech.io.outputs.server`	`string`	required		PulseAudio server address (host:port).
└ `speech.io.outputs.name`	`string`	required		Human-readable name used in TUI cycle and io.output.mode.
└ `speech.io.outputs.device`	`string`	optional		Optional PulseAudio sink name; uses the server default when omitted.
└ `speech.io.inputs`	`map[string, map]`	optional		Named audio input sources.
└ `speech.io.inputs.type`	`string`	required		Input source type: alsa, pulse, ssh_pulse, or device_mic.
└ `speech.io.inputs.device`	`string`	optional	default	Audio input device/source name.
└ `speech.io.inputs.server`	`string`	optional		PulseAudio server address for pulse inputs.
└ `speech.io.inputs.node`	`string`	optional		Target node name for ssh_pulse inputs.
└ `speech.io.inputs.scheme`	`string`	optional		Device URI scheme for device_mic inputs: android, iphone, or watchos.
└ `speech.io.inputs.host`	`string`	optional		Device host/IP reachable from the daemon for device_mic inputs.
└ `speech.io.inputs.port`	`u16`	optional		Device in-app HTTP server port serving /mic for device_mic inputs.
└ `speech.io.inputs.token`	`string`	optional		Bearer token for the device_mic /mic endpoint. May be supplied here or resolved from a daemon-known device token at capture time.
└ `speech.read_messages_aloud`	`bool`	optional	false	Auto read-aloud incoming messages on startup.
└ `speech.agent_audio`	`map[agent_id, agent_audio_override]`	optional		Per-agent audio overrides (mute, voice, voice_filter, speed). Independent from daemon-side mute. See.
└ `speech.audio`	`map`	optional		Cluster-wide and dimension-scoped audio mute policy: global_mute, default_agent_mute, and by_project/by_node/by_surface/by_profile/by_agent_role/by_agent_name. See and.