Broadcast: radio, tv, and cam
Voice is built for talk: anyone connected may speak at any moment, and turn-taking punishes delay. Sharing music, a stream, or a screen is the opposite shape — one source, nobody else contending for the floor, nothing interactive to protect with low latency. Radio and tv are that shape: single-writer, read-only for everyone else, running on the same UDP media plane as voice but with the mixing math cut out entirely and a much deeper buffer — trading roughly half a second of lag nobody notices for far more resilience to jitter and loss.
Cam inverts that tradeoff. It's still single-writer, but it rides alongside a voice call rather than standing alone, so it inherits voice's own turn-taking budget instead of radio/tv's robustness budget — a shallow buffer that favors low latency over jitter resilience. A video call doesn't need server-side mixing: each participant's camera is just their own single-writer broadcast, and any listener can dial as many of them as they like and do whatever they want with the decoded output (tile it, pipe each into its own player, etc.) — that composition is the client's call, not the server's.
Radio, tv, and cam are three profiles of the exact same coordinator — nothing in the single-writer logic, the ACL split, the ticket handshake, or the listing rules differs between them. The only things that differ are data: frame size, tick cadence, buffer depth, and what to send when nothing is due.
Single-writer enforcement
Every <kind>/<owner>/ slot allows at most one talker (the owner) and any
number of listeners:
- Owner (
caller == owner): gated oncanSend, plus the identity match itself — the one place in the codebase that checks the caller against a specific named user rather than just channel membership. Typing the wrong owner name just getsEACCES, never impersonation. - Listener (anyone else): gated on
canSee, notcanSend— tuning in never injects media, so it doesn't need send rights, only visibility.
A second concurrent owner dial is rejected two ways:
- Optimistically, at
Open(): if a talker already appears registered, the second dial fails fast withEACCESbefore a ticket is even minted — the common case. - Authoritatively, at first-packet activation: since a ticket's
Open()and its first UDP packet are separated in time, two dials can both pass the optimistic check in a race. Only one of their sessions actually registers; the loser is torn down silently. There's a known rough edge here — a client that loses this race gets no explicit "denied" signal (the media plane has no error datagram, only silence), so it keeps sending into a dead session until the user notices.
Profiles
| Radio | TV | Cam | |
|---|---|---|---|
| Format | Raw S16LE mono PCM, no codec | MPEG-TS, no fragmentation handling | Same as tv |
| Sample rate / frame | 32kHz, 640 samples (20ms) | — | — |
| Datagram payload | 1280 bytes | 1316 bytes (seven 188-byte TS packets) | 1316 bytes (same as tv) |
| Tick | 20ms | 10ms | 10ms |
| Bitrate | ~512 kbit/s | ~1.05 Mbit/s | ~1.05 Mbit/s (same ceiling as tv) |
| Idle frame (nothing due) | Zero-filled silence | An MPEG-TS null-packet datagram (PID 0x1FFF) |
Same as tv |
| Ingest reorder hold | 25 frames (~500ms) | 25 frames (~250ms, governed more by keyframe interval than frame count) | 3 frames (~30ms, voice's own turn-taking depth in frames, half its wall-clock budget) |
| Listener buffer | 25 frames | 25 frames | 8 frames (~80ms, voice's own depth in frames, half its wall-clock budget) |
Cam's shallow buffer is a reasoned starting point, not yet empirically tuned
against real jitter/loss — the same honesty standard tv's own 25-frame
depth is held to above. scripts/cast-netem.sh is the tool that checks both
against a real impaired path, the way scripts/voice-netem.sh checks
voice's.
Radio doubles voice's sample rate (32kHz vs. 16kHz) — music benefits from more bandwidth than speech needs — while staying under the same no-fragmentation datagram-size ceiling that governs both profiles: a naive jump to 48kHz would exceed a conservative MTU budget and risk fragmenting on reduced-MTU tunnels (WireGuard, PPPoE); 32kHz keeps the same 20ms cadence comfortably under it.
TV's idle frame matters specifically because zero bytes are not a quiet moment in an MPEG-TS stream — they're a stream with no sync byte, which a decoder can't resynchronize against. The null packet is what every demuxer is specified to discard, so it's the correct "nothing" for this format the way zeros are for PCM.
The self alias
radio/self/dial, tv/self/dial, and cam/self/dial always resolve to
the caller's own slot — see access-control.md for the
full mechanism (per-request resolution, the 1-nanosecond cache lifetime, and
how a chat user literally named self still gets their own correctly-gated
slot).
ffmpeg recipes
Radio (raw PCM in, so the source rate/format just has to match the profile):
# wren broadcasts a track to the everyone channel
ffmpeg -i song.mp3 -re -f s16le -ar 32000 -ac 1 - | tbase-cast radio send host everyone
# anyone else on the channel tunes in
tbase-cast radio listen host everyone wren | aplay -f S16_LE -r 32000 -c1
TV — the one thing the broadcaster's encoder has to get exactly
right is the mux rate. The wire is a fixed-size datagram on a fixed 10ms
tick, so the source must produce bytes at exactly that rate: too fast backs
the pipe up into growing latency, too slow starves the pacer. -muxrate 1052800 pins the two together and stuffs null packets when the encoder
undershoots:
# wren broadcasts her screen to the everyone channel
ffmpeg -f x11grab -i :0 -c:v libx264 -preset veryfast -tune zerolatency \
-b:v 760k -maxrate 760k -bufsize 380k -g 50 \
-f mpegts -muxrate 1052800 - | tbase-cast tv send host everyone
# anyone else on the channel tunes in
tbase-cast tv listen host everyone wren | ffplay -fflags nobuffer -
tbase-cast prints the exact required -muxrate value at startup in tv
and cam send mode, so it isn't something the operator has to derive by
hand.
Cam — the same recipe as tv (same wire format, same -muxrate), but
with a shorter GOP than tv's -g 50: cam's buffer is far shallower
than tv's, so a shorter keyframe interval bounds how long a lost or
reordered frame costs before the next keyframe recovers it. -g 15 (~0.5s
at 30fps) is a reasonable starting point — this is document-only guidance,
the server doesn't enforce a GOP length:
# wren broadcasts her camera to the everyone channel, alongside a voice call
ffmpeg -f v4l2 -i /dev/video0 -c:v libx264 -preset veryfast -tune zerolatency \
-b:v 760k -maxrate 760k -bufsize 380k -g 15 \
-f mpegts -muxrate 1052800 - | tbase-cast cam send host everyone
# anyone else on the channel watches
tbase-cast cam listen host everyone wren | ffplay -fflags nobuffer -
At the former 526 kbit/s ceiling, 720p30 measured perceptually transparent against a lossless encode for screen content (a terminal, an editor — what tbase is actually for; SSIM within 0.001 of a lossless encode of the same source, and the encoder didn't even spend the full budget) — so the budget having since doubled to ~1.05 Mbit/s is headroom on top of an already-transparent result, not a needed correction. Dense-motion content (a camera feed) needs a lower resolution or frame rate to look as good at the same rate — downscaling to 480p in particular costs about 25× more quality than just accepting the codec's cost at 720p for text content specifically, so that's the wrong lever to reach for on this content class.
Low-latency tuning (screen share / webcam over cam)
The recipes above default to quality and robustness — tv's deep buffer
is the point of that profile. For something closer to a live call, three
things matter more than the codec:
- Use
cam, nottv, even for a screen share, if latency matters more than jitter/loss resilience.tv's ingest and listener buffers are 25 frames each (~250ms server-side, ~250ms client-side) — deliberately deep, since a plain broadcast has no turn-taking to protect.cam's buffers are voice-depth in frames and, at cam's own 10ms tick, genuinely tens of ms in wall-clock time too (~30ms/~80ms). Routing a screen share throughcaminstead oftvis the single largest latency lever available without touching the server, at the cost oftv's robustness against network hiccups. - Capture the region you're sharing at its native size — never scale it
down.
x11grab's-video_sizesets the capture region, not an output size; it crops rather than resamples. Add a-vf scale=...filter on top and you blur text before the encoder ever sees it, which costs far more quality than just paying the codec's cost at native resolution (see the 480p note above) — the fix for "too much screen" is to grab a smaller region (e.g. viaxwininfo), not to shrink a bigger one. - Bound the encoder's own lookahead, not just its bitrate. Both x264 and
x265 buffer several frames internally for rate-control lookahead and (on
x265) frame-parallel threading — neither shows up in
-b:vor-bufsize, but both add real, hidden latency on top of them.
Screen share, cropped to the shared window, mic muxed in, over cam:
xwininfo # click the window; note Width/Height and Absolute upper-left X/Y
ffmpeg -f x11grab -video_size <W>x<H> -i :0.0+<X>,<Y> -framerate 15 \
-f pulse -i default \
-c:v libx265 -preset fast -tune zerolatency \
-x265-params "bframes=0:rc-lookahead=5:frame-threads=1" \
-b:v 800k -maxrate 800k -bufsize 300k -g 15 \
-c:a aac -b:a 64k -ac 1 -ar 48000 \
-f mpegts -muxrate 1052800 - | tbase-cast cam send host everyone
tbase-cast cam listen host everyone wren | \
ffplay -fflags nobuffer -flags low_delay -framedrop -probesize 32 -analyzeduration 0 -
Webcam, same idea, pinned to a modest capture format so the driver doesn't silently negotiate something the encoder can't hold in real time:
v4l2-ctl --list-formats-ext -d /dev/video0 # confirm the fps a given format/size actually supports
ffmpeg -f v4l2 -input_format mjpeg -video_size 640x480 -framerate 15 -i /dev/video0 \
-f pulse -i default \
-c:v libx265 -preset ultrafast -tune zerolatency \
-x265-params "bframes=0:rc-lookahead=5:frame-threads=1" \
-b:v 800k -maxrate 800k -bufsize 300k -g 15 \
-c:a aac -b:a 64k -ac 1 -ar 48000 \
-f mpegts -muxrate 1052800 - | tbase-cast cam send host everyone
Watch ffmpeg's own speed= in stderr while testing a new source or
resolution — below 1.0x means the encoder is falling behind real time,
which backs the pipe up into growing latency rather than starving it (the
two failure directions -muxrate is meant to guard against, above).
-preset ultrafast on the webcam recipe isn't a typo: camera motion costs
the encoder far more per frame than mostly-static screen content does, so a
preset that held real time for x11grab may not for /dev/video0.
Hardware encoders
Software x264/x265 is what forces the preset-vs-quality trade above — a GPU
encoder has much lower per-frame latency and enough throughput headroom that
ultrafast stops being necessary. Check what's available first:
ffmpeg -encoders 2>/dev/null | grep -E 'nvenc|vaapi|qsv'
NVIDIA (NVENC) — drop-in for the -c:v line above, no pixel-format
juggling required:
ffmpeg -f v4l2 -input_format mjpeg -video_size 640x480 -framerate 15 -i /dev/video0 \
-f pulse -i default \
-c:v h264_nvenc -preset p1 -tune ull -rc cbr -zerolatency 1 -bf 0 -rc-lookahead 0 \
-b:v 800k -maxrate 800k -bufsize 300k -g 15 \
-c:a aac -b:a 64k -ac 1 -ar 48000 \
-f mpegts -muxrate 1052800 - | tbase-cast cam send host everyone
-preset p1 -tune ull is NVENC's ultra-low-latency pair (the same idea as
x265's ultrafast+zerolatency); -zerolatency 1 and -rc-lookahead 0
strip the encoder's internal lookahead the same way frame-threads=1 and
rc-lookahead=5 did for x265, above; -bf 0 disables B-frames.
Intel/AMD (VAAPI) — needs the frame explicitly handed to the GPU, so there's a device and a format filter to add:
ffmpeg -vaapi_device /dev/dri/renderD128 \
-f v4l2 -input_format mjpeg -video_size 640x480 -framerate 15 -i /dev/video0 \
-f pulse -i default \
-vf 'format=nv12,hwupload' \
-c:v h264_vaapi -bf 0 \
-b:v 800k -maxrate 800k -bufsize 300k -g 15 \
-c:a aac -b:a 64k -ac 1 -ar 48000 \
-f mpegts -muxrate 1052800 - | tbase-cast cam send host everyone
VAAPI doesn't expose a lookahead knob the way NVENC/x265 do — -bf 0 is the
main lever, and its pipeline is shallow by default. Either way, check
speed= again after switching: it should hold well above 1.0x now, and if
end-to-end delay drops noticeably, the software encoder was the remaining
bottleneck rather than the webcam or the player.
See cli-reference.md for tbase-cast's exact
positional-argument grammar.