Room adapter
How to play fox9 on a room speaker: roomctl, now vulpine-room (the Rust binary ~/.local/state/foxline/bin/vulpine-room, crates/vulpine_room; just install-vulpine-room; roomctl is a link to it for one release) on the mini, e.g. vulpine-room speak --room <room> --text "...", the one room-target interface behind the brain tool pi_room_speak and the gateway's room route (glyphctl speak --room); rooms live in ~/.config/foxline/rooms.json.
Living doc, checked against the code 2026-11-14
room_speaker — roomctl, the one room-target interface
roomctl makes a room say or play something. It is one Rust binary (crates/vulpine_room) with the file name
vulpine-room. A roomctl link to it still works and prints one deprecation line on stderr.
Two consumers call it: the brain tool pi_room_speak and the gateway’s room-speaker route (speak with a room,
armed by [room_speakers] enabled). vulpine-glyphctl speak --room <room> "..." reaches that route through the
gateway. [room_speakers] roomctl defaults to the binary. A path ending in .py runs under
[room_speakers] python.
The binary lives at ~/.local/state/foxline/bin/vulpine-room on the gateway host, beside the loopback-only
tts-server. just install-vulpine-room <ssh host> builds it on this machine and ships it over ssh, so the gateway
host needs no cargo. The old binary stays as vulpine-room.previous. just install-vulpine-room with no host
installs on this machine. To play on a room speaker by hand, run it on the gateway host:
ssh <gateway-host> ~/.local/state/foxline/bin/vulpine-room list
ssh <gateway-host> ~/.local/state/foxline/bin/vulpine-room speak --room <room> --text "Dinner is ready."
--format json --full-output, anywhere on the command line, prints the outcome as one typed envelope (v2):
{"ok": true, "data": {…the receipt…}, "meta": {"command", "duration"}}, or
{"ok": false, "error": {"code", "message", "retryable"}, "data"?, "meta"} with code one of UNKNOWN_ROOM,
ROOM_REFUSED, UNKNOWN_DRIVER, ROOMS_FILE_MISSING, BAD_ARGUMENTS, NOT_SUPPORTED, RENDER_FAILED,
DRIVER_FAILED, NO_ACK, INTERNAL. Under v2 the refusals that v1 prints on stderr come on stdout too. The exit
codes are v1’s. The gateway and pi_room_speak read either shape; v1 is the default.
Rooms live in ~/.config/vulpine/rooms.json on the gateway host ($VULPINE_ROOMS_FILE names another).
roomctl init writes a default file. Each target names a
driver:
sonos_clip— a Sonos audio clip over the player’s local websocket. The ack is measured fromaudioClipStatus DONE.upnp— UPnP AVTransport for any DLNA renderer. It sets and restores the volume; the ack comes from the transport state. A renderer that is PLAYING gets a Stop before the new URI (stopped_first,pre_state,post_stop_statein the receipt). An unacked play that the renderer never fetched endsok: falsewithreason: "renderer_did_not_fetch": no 2xx GET from its address within the audible estimate + 5 s, or the settle if longer. Three such plays in a row makevulpine-voice-gateway doctorprint a WRONGroom:<target>row.ha— Home Assistantplay_media, modeannounceorreplace. The token is in~/.config/vulpine/room-speaker.env(0600), or$HA_LONG_LIVED_TOKEN.cli— any executable with{url} {room} {text} {wav} {audible_ms} {volume}.alexa— an Amazon Echo through Home Assistant’s Alexa Media Player. An Echo does not reliably play a LAN clip URL, so roomctl sends the text tonotify.alexa_media_<name>(modetts, orannouncefor a chime first). The Echo says it in Alexa’s voice, not Fox Nine’s, and every receipt carriesvoice: "alexa". It takesspeakonly (play --wavis refused), and the ack is alwaysestimated. It uses the same HA token.
roomctl pause --room <room> and roomctl resume --room <room> pause and resume the room’s player for a request.
Home Assistant rooms use media_player.media_pause / media_play. UPnP rooms use AVTransport Pause, or Stop
when the renderer has no Pause (paused_as: "pause" | "stop"). A pause happens only when the player is playing, and
a resume only when it is paused, so nothing starts music nobody had on. A Stop-shaped pause is never resumed. The
gateway calls them only with [media] pause_for_request = true.
Echo rooms
Add one row per Echo to the rooms file. JSON has no comments; these are examples.
entity is the Echo’s media_player.*. The notify service is derived from it
(media_player.kitchen_echo → notify.alexa_media_kitchen_echo); set notify when the names differ.
"kitchen-echo": {"driver": "alexa", "entity": "media_player.kitchen_echo", "mode": "tts",
"label": "Kitchen Echo (Alexa's voice)"},
"office-echo": {"driver": "alexa", "entity": "media_player.office_echo", "mode": "announce",
"label": "Office Echo (Alexa's voice, chime first)"}
roomctl discover --alexa lists the Echo candidates Home Assistant knows, with groups under groups. roomctl
refuses a group: "group": true, or any room, entity, notify or label containing everywhere. It also refuses
any name on its built-in exclusion list (EXCLUDED_NAMES, a bridged switch that is not a speaker), whatever the row
says. Refusals name the room, never an entity id, since the Brain may read them aloud.
Every receipt’s ack.source is the ADR 0034 vocabulary, measured or
estimated; ack.detail names how the driver measured it (clip_status,
state_transition, cli_receipt, …). The gateway and the Brain read only
source.
Ambience
roomctl ambience plays a calming sound in a room for a while, with a timer and a fade-out (“rain in the bedroom
for forty minutes”). The gateway runs it for the brain tool pi_room_ambience
(crates/voice_gateway/src/room_ambience_line.rs). The brain never runs it itself: under the reach helper its
roomctl cannot reach the LAN.
roomctl ambience start --room <room> --sound rain --minutes 40 [--fade-s 30] [--volume 20]
roomctl ambience stop [--room R] [--sound S] # every play that matches; all when neither is given
roomctl ambience status [--room R] [--sound S] # what plays where, how long is left, and the recent plays
roomctl ambience sounds # the sound set, each with its source and license
- Sounds.
rain,waves,brown-noise,pink-noise,white-noise(aliases: ocean, sea, brown, pink, fan, white). roomctl synthesizes every one (crates/vulpine_room/src/ambience/sound.rs): noise shaped by one-pole filters and envelopes, about -18 dBFS. There is no recording and no sound file; the license is MIT.roomctl ambience soundsprints each with its source and license. - Players.
haandupnprows play as they are (play_mediawith the stream;SetAVTransportURI+Play). Asonos_cliprow plays ambience through the same Sonos over UPnP on port 1400 (or the row’supnp_port), since a clip is an overlay for a sentence. A row’sambienceobject, when present, names the target ambience drives instead. An Echo (alexa) and aclirow are refused. Optional row keys:ambience_volume(elsevolume, else 20),wav_rate(else the rooms file’stts.wav_rate, else 48000),ambience_lead_s(how far ahead of real time the stream is fed, default 6).url_server.ambience_portpicks the listener’s port (default 0: any free one) onurl_server.bind, advertised asurl_server.advertise. - The timer.
startwrites the play’s record (~/.local/state/vulpine/room-speaker/ambience/<id>.json). It then startsroomctl ambience serve --id <id>detached, in its own process group, so a gateway restart does not reach it. That process reads the player’s volume, sets the ambience volume and points the player at one WAV stream of exactly the play’s length, fed in real time: the stream is the timer. The last--fade-sseconds fade to silence inside the samples (quadratic), the stream ends and the player stops. The process then stops the player and puts its volume back, but only while the player is still on this stream; other music is left alone (handed_over). A pause on the player pauses the stream, andends_at_msmoves with it. - Stop.
stopdrops a<id>.stopflag. The process fades the player’s volume to nothing over 3 s, stops it and restores the volume. A newstartin a room replaces what plays there (stop_reason: replaced). - Lost. If the process dies, the stream dies with it, so nothing plays past a lost timer.
statusreads the play aslostwhen its pid is gone or its heartbeat is 30 s stale. A player that stops fetching for 90 s before the end readsinterrupted; one that never fetches within 15 s readsfailed. - Receipts. Each command prints one JSON receipt with a
spokenline. It holds room and sound names and durations only, never an id, an entity or an address: “Rain in the bedroom for 40 minutes, fading out over the last 30 seconds.”, “Rain in the bedroom: 23 minutes left.”, “Stopped the rain in the bedroom.”, “Nothing is playing. The rain in the bedroom stopped early: its timer was lost.”startandstopalso append to receipts.jsonl. Exit codes: 0 done; 1 the player was told but has not fetched yet; 2 usage, an unknown room or sound, or a room that cannot play a stream; 3 the player failed.--format json --full-outputwraps it in the v2 envelope. - The Admin. The gateway runs
roomctl ambience statusevery 15 s (local files only, no device call). The Room speakers section’s Ambience table shows room, sound, state, until, time left, fade, volume, driver, then how the recent plays ended.
Adding a transport is one Driver variant in crates/vulpine_room/src/main.rs with probe() and play(ctx).
Receipts append to ~/.local/state/vulpine/room-speaker/receipts.jsonl.