DocsSource

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_join event.
  • Idle reaping: a session that goes 5 seconds without a fresh authenticated packet is torn down — its key forgotten, voice_leave posted. 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 (default 1, meaning unmodified).
  • Writing a number sets it. 0 is a personal mute; the accepted range is 0–4. An out-of-range, non-numeric, NaN, or infinite value is silently ignored, mirroring ctl/retention's "malformed value is ignored" rule.
  • voice/members is a directory, not a flat file — unlike stats or channel members — 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.