docs: WebRTC is the default transport, and a FAQ that says so - #281
Merged
Merged
Conversation
Coverage71.62% lines on this branch, against a floor of 70%. Per-file |
pierre-rouanet
force-pushed
the
webrtc-first-and-a-faq
branch
from
September 14, 2026 11:23
22cbea7 to
dfe4958
Compare
Three things this repository could not tell somebody who wanted to run a model too heavy for the board. There was no page about it at all. `spaces/` appears nowhere under `docs/` — not in the index, not linked, nothing. The only writing was a Space card published to Hugging Face and a lot of source comments. What writing existed argued the wrong way. `media.stream` was built when the relay endpoint was dead and WebRTC genuinely could not connect from a data centre, so `stream.rs` made its case at length and, once the dead-endpoint premise was removed, read as though outbound frames were the preferred design. They are not. WebRTC carries encrypted media, a control channel on the same session and a return path; `media.stream` has none of those and exists for a program consuming frames only on a long-running stream, where a relay's metered bandwidth is the cost that matters. And nothing recorded the rule for whoever changes this next, which is how it would have been re-derived backwards from the volume of prose in `stream.rs`. So: `docs/faq.md`, task-shaped rather than linear, because somebody arrives at this with a situation and not a curiosity. `AGENTS.md` with `CLAUDE.md` symlinked to it, carrying the transport rule and three others. `stream.rs` demoted to the fallback it is, with what it gives up stated rather than implied. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
pierre-rouanet
force-pushed
the
webrtc-first-and-a-faq
branch
from
September 14, 2026 11:24
dfe4958 to
2dd630a
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Problem
Somebody who wants to run a model too heavy for the board has nowhere to read what to do.
There is no page.
spaces/appears nowhere underdocs/— not in the index, not linked, noentry anywhere. The only writing on the approach is
spaces/vision-demo/README.md, which is aSpace card published to Hugging Face, plus source comments.
And what writing exists argues the wrong way round.
media.streamwas built when the relayendpoint was dead and WebRTC genuinely could not connect from a data centre. Once #258 removed
that premise,
stream.rsread as though outbound frames were the preferred design on theirmerits:
That overshot, and it was mine — written earlier the same day while removing the dead-endpoint
claim.
What this adds
docs/faq.md, task-shaped rather than linear, because people arrive at this with a situation:I want to run a heavier model, does it work from a data centre, my stream runs all day, is
there something cheaper, what stops somebody else reaching my robot, can I test without one.
Linked from the docs index as the second front door — for building against a duck rather than
changing it.
AGENTS.md, withCLAUDE.mdsymlinked to it so both conventions resolve to one file. Itcarries the transport rule and three others that are easy to get backwards. It says explicitly
that the repository reads the other way if you only follow the code, so the next person does not
re-derive the wrong default from the volume of prose in
stream.rs.stream.rsdemoted to the fallback it is, with the cost stated instead of implied: no returnpath, no control channel, and encryption that terminates at the receiver's server rather than at
the peer.
The rule
A consumer uses WebRTC — encrypted end to end, control channel on the same session, a return
path, and it reaches a data centre because the robot offers a relay candidate.
media.streamis the fallback for a consumer that is all three of: a program, frames-only,and long-running enough that a relay's metered bandwidth (10 GB/month per HF account) is the cost
that matters.
Not in here
spaces/vision-demo/still has no WebRTC stack —aiortcandavwere deliberately removedwhen it was rebuilt around outbound frames, and
requirements.txtsays so in as many words. Soswitching it to WebRTC is reinstating those and rebuilding the transport, not a flag flip. That is
the next change.
And it is unverified that an
aiortcconsumer connects from a Space now. The relay came backthis morning; the demo exists because it did not work before, and that premise has not been
re-tested.
spaces/policy-shop/kept its WebRTC path and is the cheap probe. Worth doing beforethe demo is rewritten rather than after.
🤖 Generated with Claude Code