SmartestHome/mic-follow

mic-follow — the microphone follows the person

A voice call that survives walking out of the room. The person leaves their desk, the locator says which room they are in now, and their machine's live microphone switches to one that can hear them there — then back to the good desk mic when they sit down.

Built for the specific case of a smoke break on the Loggia during a game, and written per client so a second person with a second desktop is one more entry in CoreSystemConfig.json and nothing else.

1. The one rule

Off means the desk mic.

The Follow-me switch being off is not "ignore me", it is an active guarantee that the machine is on its own microphone. Being live on the wrong mic is the failure you notice in front of five other people, so the safe state is reachable by one tap on the dock, one button on a watch, or one MQTT message — and it does not depend on presence being right, on the remote machine being up, or on the agent having seen a recent update. The agent also returns to the desk mic when it shuts down.

2. Who decides what

   locator (BLE via identity; RuView/Frigate corroborate — see §3)
        │  presence_entity's state is an area_id
        ▼
   Home Assistant ── generated automation ──> select.mic_follow_<node>_input
        │                (only while switch.mic_follow_<node>_armed is on)
        ▼   MQTT
   desktop_agent.py ──> pactl: set the default source, and MOVE the running
                        capture streams of the configured applications

Home Assistant decides where the person is and therefore which mic should be live. The agent knows how to change the input on this machine and nothing about presence, people or rooms beyond the names in its own config. Same rule as every other agent in this repo: the inbound control surface is MQTT discovery entities and nothing else.

Moving the streams matters as much as setting the default. Changing the default source only affects applications that asked for "default", and anyone who owns a studio mic has picked it explicitly in Discord. move_streams names the applications whose already-running capture stream gets moved too.

3. What the locator can and cannot tell you

presence_entity must be an entity whose state is an HA area_id (docs/rooms-and-endpoints.md). Getting one is the part of this that is not built here:

Source	Gives	Usable to drive this?
BLE / Bermuda, surfaced by identity's /presence	a person, resolved to a room	Yes — the only identity-bearing room-level source in this household
RuView (CSI radar)	a room is occupied, by somebody	No on its own — it cannot say who. Good for corroboration
Frigate	a recognised face at the door	No — it is a peephole camera, not per-room

So this rides on BLE, with everything else as confirmation. That matters because room-level presence has never been measured in this flat — the repo says so elsewhere and it is still true. Before trusting it with your microphone, watch the entity in Developer Tools while you walk to the Loggia and back. If it lags by a minute or reports a friendly room name instead of an area_id, the automation will never fire and the mic will never move.

dwell_seconds (default 20) is the guard against a twitchy locator: a walk past a door should not move your microphone. return_dwell_seconds (default 5) is deliberately shorter — sitting down should give you the good mic back before you say anything into it.

4. Three ways to flip it, one place to read it

Every surface shows the same entity: sensor.mic_follow_<node>_status, whose state is the name of the microphone that is live right now — Desk, Loggia. That sensor exists so no surface has to reimplement the same three-way template, and so the answer to "what am I being heard through" is one string anything can print.

• Stream Dock key — displays that sensor and calls switch.toggle. The Home Assistant plugin subscribes to HA's websocket, so the key updates when the state changes rather than on a timer: nothing polls, and the key is right within a moment of the mic actually moving, including when it was the watch or the automation that moved it. Bindings are generated into generated/dock-bindings.md; leave the key's title empty and let the state be the whole label, because Loggia in large type is readable across a room and Follow-me mic over a small Loggia is not.
• Pebble watchapp — long-press Select on the plan screen. The screen shows the live microphone in large type, FOLLOWING or DESK ONLY as a coloured pill, and Select flips it. Up/Down cycles clients if there is more than one.
• Home Assistant — the switch and the select, like anything else.

The watch goes through identity's /toggles, not straight at Home Assistant: identity already holds an HA token and the phone already holds identity's, so one button on a wrist does not put an HA admin token in a watchapp's settings. It is an allowlist, not a proxy — only switch.* entities that are named in TOGGLE_ALLOWLIST_JSON, only on/off/toggle, and an id that is not listed is a 404. Paste the line from generated/identity-toggles.env into identity.env or the watch sees nothing.

5. Setting it up

1. Fill in mic_follow in CoreSystemConfig.json. Get the desk_source and each source string by running mic-follow/desktop_agent.py --list-sources on the machine in question — any part of a name or description matches.
2. tools/validate-config.py.
3. On each client machine: mic-follow/setup-client.sh <node_id>.
4. Put generated/ha-package/mic_follow.yaml in HA's packages/ (the same directory stream-dock uses) and reload YAML.
5. Paste generated/identity-toggles.env into identity.env, restart identity.
6. Bind the dock key from generated/dock-bindings.md.

6. A remote microphone that is not plugged into this machine

start_command / stop_command on a source are the hook for that — bringing up a network mic stream, for instance, when the switch moves to that room.

The stop hook is the important one. A room microphone that keeps streaming after the switch has left it is a hot mic in somebody's flat. The agent runs the stop hook on every transition away and again on shutdown, and the validator warns about a start_command with no matching stop_command.

7. What is tested, and what is not

Tested here, and it runs anywhere:

• test_selection.py — 17 cases over the audio layer's parsing and selection: monitor sources can never be selected (picking one transmits what the desktop is playing, the worst outcome available), exact names beat substrings, an ambiguous pattern resolves the same way after a reboot instead of coin-flipping, and only the configured applications' streams get moved.
• pebble-presence/test/run-tests.sh — the toggles line is packed by the real JS and parsed by the real C, so those two implementations of one format cannot drift.
• The generated HA package parses as YAML, for one client and for several.

Not tested, because it needs the actual machines: every command that changes state (pactl set-default-source, move-source-output), the pactl JSON shapes the fixtures imitate, the MQTT discovery payloads against a real Home Assistant, and — the one most likely to bite — whether the presence entity reports rooms quickly and accurately enough to be worth wiring to a microphone at all (§3).