Voice
Every channel carries a live voice call: an N-to-M mixer where anyone connected may speak at any moment, tuned for low latency since turn-taking punishes delay. Real-time audio wants UDP — a single lost packet shouldn't stall everything behind it — so voice runs on a small UDP media plane alongside the ordinary filesystem, with no client library and no codec.
The voice/dial ticket handshake
Opening voice/dial runs the ordinary ACL check (gated on canSend, since
a dial session always registers as a talker), then mints a fresh session and
returns a one-shot JSON ticket, then EOFs:
{"port":61000,"session":1234567890,"key":"base64-encoded-32-byte-key"}
That's the whole key exchange: the ticket only ever travels inside a channel (SSH, then the FUSE mount) the system has already authenticated, so there's no separate token layer to invent.
The dial handle does not park. Unlike a design where the open stays
blocked for the call's duration, voice/dial's read returns immediately
after the ticket. This matters because ssh host cat .../voice/dial (how the
tbase-voice client fetches the ticket) allocates no pty — if the client
process dies, sshd never signals the orphaned remote cat, so a design that
tied the session to the open handle would leak it forever. Instead:
- The session is the live UDP media flow, not the open handle.
- A session starts pending: minted, but not yet registered with the mixer.
- Its first authenticated packet promotes it to active — that's what
registers it with the mixer and posts the
voice_joinevent. - Idle reaping: a session that goes 5 seconds without a fresh
authenticated packet is torn down — its key forgotten,
voice_leaveposted. A client streams a frame every 20ms even through silence (arecord's continuous output doubles as a keepalive), so several seconds of nothing really does mean the call ended. - A clean exit sends one authenticated, empty-payload "bye" datagram instead of waiting for the idle reaper — audio frames are always a fixed size, so an empty payload is an unambiguous "hang up now" sentinel.
Wire format
One UDP port serves every session on the server (61000 by default,
configurable with -voice-port), demultiplexed by a per-session id — one
firewall rule, ever.
- 16-byte cleartext header: session id (8 bytes) + sequence number (8 bytes), both big-endian.
- Payload: NaCl
secretbox-encrypted with the session's key. The nonce is built from a direction byte (client→server vs. server→client) plus the sequence number, so the two directions never reuse a nonce under one key (the same construction mosh uses). - Replay protection: a 1024-bit sliding window per session/direction (≈20 seconds of reordering tolerance at 50 frames/sec). Authentication is checked before the replay check, so an unauthenticated packet can never perturb the window.
- Roaming: the server always replies to the source address of the freshest authenticated inbound packet — so a client that switches networks mid-call just keeps working, no re-dial needed.
- Audio format: raw S16LE mono PCM at 16kHz, no codec, one 20ms frame (640 bytes) per datagram.
Any malformed, unknown-session, unauthenticated, or replayed packet is silently dropped — a lost UDP packet and a stalled reader degrade identically, by design.
Mixing
Every connected listener hears every other talker summed together, minus their own voice (echo self-exclusion, keyed on identity — computed fresh every 20ms tick) — so a lone caller hears silence until someone else dials in, and nobody ever hears themselves. A silence frame is delivered every tick even with nobody talking, so playback never underruns.
The mixer coordinator only runs its 20ms tick while at least one listener is connected — an idle channel costs nothing but a parked goroutine.
Per-listener gain (voice/members/<name>)
Each connected participant can turn any other single talker up or down for themselves only — this is a per-(listener, talker) weight, applied only inside that listener's own mix, never a shared setting:
- Reading
voice/members/<name>returns your current gain for that participant (default1, meaning unmodified). - Writing a number sets it.
0is a personal mute; the accepted range is0–4. An out-of-range, non-numeric,NaN, or infinite value is silently ignored, mirroringctl/retention's "malformed value is ignored" rule. voice/membersis a directory, not a flat file — unlikestatsor channelmembers— because each entry needs distinct per-entry read and write semantics.- Your own name is never listed and can't be looked up — you cannot gain-control yourself.
- A gain override can be set before the target participant ever joins the call, and it persists across their brief reconnects — it's keyed by username on the channel's mixer, not by dial session. It does not survive a full server restart (it's in-memory only, like the mixer itself).
voice/stats
A finite snapshot of every currently-talking participant's ingest health:
tomo underruns 0 resyncs 0 gaps 0 late 0
wren underruns 0 resyncs 0 gaps 3 late 1
These four counters describe the uplink into the server (gaps, late
frames, resyncs, buffer underruns on that talker's incoming reorder buffer)
— the one vantage point that can see a specific person's send leg, since
every listener only ever sees the already-mixed result. A talker whose
gaps climb while their own client reports a clean downlink (via
tbase-voice -v) has a problem on their send path specifically, invisible
to anyone else.
The tbase-voice client
arecord -f S16_LE -r 16000 -c1 | tbase-voice host everyone | aplay -f S16_LE -r 16000 -c1
It fetches the ticket over ssh host cat .../voice/dial (that cat exits
immediately after printing it — the call is not tied to the SSH process),
then pumps mic input in and the mixed-down stream out as encrypted UDP
datagrams. See cli-reference.md for its exact flags, and
scripts.md for the voice.sh/voice.ps1 wrapper scripts that
auto-detect a capture/playback stack for you.