Skip to content
Vulpine
Esc
↑↓navigate↵open⌘Jpreview
On this page

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 from audioClipStatus 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_state in the receipt). An unacked play that the renderer never fetched ends ok: false with reason: "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 make vulpine-voice-gateway doctor print a WRONG room:<target> row.
  • ha — Home Assistant play_media, mode announce or replace. 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 to notify.alexa_media_<name> (mode tts, or announce for a chime first). The Echo says it in Alexa’s voice, not Fox Nine’s, and every receipt carries voice: "alexa". It takes speak only (play --wav is refused), and the ack is always estimated. 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 sounds prints each with its source and license.
  • Players. ha and upnp rows play as they are (play_media with the stream; SetAVTransportURI + Play). A sonos_clip row plays ambience through the same Sonos over UPnP on port 1400 (or the row’s upnp_port), since a clip is an overlay for a sentence. A row’s ambience object, when present, names the target ambience drives instead. An Echo (alexa) and a cli row are refused. Optional row keys: ambience_volume (else volume, else 20), wav_rate (else the rooms file’s tts.wav_rate, else 48000), ambience_lead_s (how far ahead of real time the stream is fed, default 6). url_server.ambience_port picks the listener’s port (default 0: any free one) on url_server.bind, advertised as url_server.advertise.
  • The timer. start writes the play’s record (~/.local/state/vulpine/room-speaker/ambience/<id>.json). It then starts roomctl 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-s seconds 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, and ends_at_ms moves with it.
  • Stop. stop drops a <id>.stop flag. The process fades the player’s volume to nothing over 3 s, stops it and restores the volume. A new start in 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. status reads the play as lost when its pid is gone or its heartbeat is 30 s stale. A player that stops fetching for 90 s before the end reads interrupted; one that never fetches within 15 s reads failed.
  • Receipts. Each command prints one JSON receipt with a spoken line. 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.” start and stop also 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-output wraps it in the v2 envelope.
  • The Admin. The gateway runs roomctl ambience status every 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.

Was this page helpful?