---
title: "Room adapter"
description: "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."
type: "living"
source: "runtime/room_speaker/README.md"
verified: "2026-11-14"
group: "Adapters and integrations"
---

> **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.

```json
"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`.

