WebRTC for the Curious: how the free WebRTC book is read and built

Explaining the stack instead of the browser APIs

WebRTC for the Curious is a book, not a library. Nothing in the repository installs as a dependency, and the running instructions in the README only start a documentation server. The subject is the WebRTC stack itself: the promotional copy names ICE, SCTP, DTLS and SRTP and promises the full details of how they "work together to make up the WebRTC stack", set against "not just a tour of the APIs".

That framing settles the audience. An engineer wiring a call into a page needs a reference for one function signature, and this book is not trying to be that. It is written for the person underneath the call, the one deciding why a DTLS handshake stalls or why an ICE candidate pair never connects. The authors describe themselves as developers who wrote all of this from scratch, and they state that the book is vendor agnostic, which counts for readers whose media stack spans more than one implementation.

Reading the Markdown source or the rendered Hugo site

The project gives you two doors to the same text. One is `content/_index.md` inside the repository, the other is the published site at webrtcforthecurious.com. They are not separate editions. The site is generated from the repository, with `config.toml` at the top level holding the build settings and a `themes/` directory supplying the layout, so any difference between the GitHub copy and the online copy comes from the theme rather than from a second body of prose.

Reading the Markdown directly gives you plain text and none of the navigation the theme builds for you. Building the site gives you the rendered structure but costs a Hugo binary and submodules. For a first pass the repository copy is faster, since it needs nothing installed, and it is also the copy that carries translation work as it happens rather than as it was last published.

Clone recursively, install extended Hugo, run the server

The running section gives three steps in order. The first is a recursive clone, because the repository carries a `.gitmodules` file and anything living in a submodule stays empty without that flag:

git clone --recursive https://github.com/webrtc-for-the-curious/webrtc-for-the-curious.git

The second step is not a package manager command. You fetch the extended build of Hugo from the Hugo project yourself, and the README does not say which feature of this site needs the extended binary, so treat it as a fixed requirement rather than a preference. Then one command serves the book on your machine:

hugo server

No port, bind address or production mode is documented alongside that command, so Hugo defaults decide where the site lands and how it behaves.

Contributors without a local toolchain have a second route. The repository carries a `.devcontainer/` directory for Github Codespaces, and once a Codespace is running you click "Run Live Docs Server" in the statusbar to start the same server. That route carries one documented catch: Hugo's autoreload does not trigger a browser refresh from Codespaces, because WebSocket traffic is not proxied, so pages have to be reloaded by hand after every edit.

Python leads the language list but only 3 cover scripts use it

The repository reports Python as its primary language, which sends newcomers hunting for notebooks, sample servers or a test harness that are not in the repository. The book is Markdown under `content/`, rendered by Hugo, and the Python at the top level is 3 scripts with a single job: `make-cover.py` for the default cover, `make-cover-sv.py` for the Swedish edition and `make-cover-zh-cn.py` for the Simplified Chinese one.

That distribution has two consequences worth knowing before you clone. The language bar on the repository page describes the wrong kind of project, and it also conceals the fact that cover art was written for 2 translated editions out of the 10. Nothing in the top-level entries shows a build step that calls those scripts, so the documented path from a fresh clone to a rendered page is a straight line to `hugo server`.

10 translation trees and one nonstandard directory code

The top level holds `content/` plus 10 translated trees: `content.es/`, `content.fa/`, `content.fr/`, `content.id/`, `content.ja/`, `content.ru/`, `content.sv/`, `content.tr/` and `content.zh-cn/`. Read as a group, one name breaks the pattern. Every other directory uses a language code, and `content.kr/` uses a country code where the language code belongs.

Nobody has written down why. The README covers cloning, Hugo and contributing, and says nothing about how translations are declared or maintained. Hugo decides which tree serves which language from `config.toml`, so a contributor who follows the majority pattern and creates a new directory named for the Korean language code ends up with a tree the build does not know about, and the failure is quiet because the site still compiles. This is cheap to check before starting a translation and impossible to check from the README alone.

Nothing tagged, so a self-hosted copy tracks the master branch

The cost side of adopting this book is unusually cheap in permission and slightly awkward in mechanics. The work is public domain under CC0-1.0, the last push landed on 2026-07-21, and the repository publishes no GitHub releases, which means there is no tag for a self-hosted copy to pin against; the default branch is `master` and your build follows whatever sits there.

Upgrading is therefore a pull rather than a version bump, and chapters under `content/` can change under a site you already built. 2 entries in the top-level listing shape that risk. `.hugo_build.lock` is committed next to `config.toml`, so a clean clone arrives carrying a build lock generated on somebody else's machine. `.gitmodules` makes the recursive clone non-optional, and a CI checkout that skips submodules will hand you a site with holes rather than a clear error message.

Prose and a docs toolchain, no runnable WebRTC stack

The clearest limitation is what is absent. The top-level entries are a Hugo site: `layouts/`, `themes/`, `archetypes/`, a `.pandoc/` directory, the translation trees and the cover scripts. No application, signalling server or media pipeline sits there, so a chapter on DTLS or SCTP hands you a mechanism to reason about and nothing to run against. If your question is why your own stack behaves badly, that is exactly what you want. If your question is how to reproduce the behaviour, this repository cannot answer it.

The promotional copy also promises listening as well as reading, including interviews with authors of foundational WebRTC technology whose design decisions "pre-dated WebRTC by 20 years". Both entry points the README hands you, `content/_index.md` and webrtcforthecurious.com, are text-first, and the README does not say where that audio lives. Assume the written chapters are what you can rely on offline.

Narrative depth against the specification's normative text

The real alternative to this book is the WebRTC specification itself, and the difference in approach is the entire value on offer. A specification states what an endpoint must do. This book explains how the protocols ended up arranged that way, how implementers chase a failure below the API and how the pieces behave in production systems. The interviews and the accounts of applications that shipped are parts no specification carries, and the stated vendor neutrality keeps the examples from tying you to one stack.

The trade-off runs the other direction. A narrative ages differently from a specification: each chapter reflects what its authors knew when they wrote it, and the repository offers no dated editions, so the only freshness signal a reader gets is the last push. Keep the specification open beside the chapter when you need conformance text or an exact packet layout. Read the book when you need to understand why the stack behaves as it does, where the free cost and the missing install step make the decision easy.

Editorial conclusion

Worth an afternoon if you maintain a WebRTC stack and keep stalling below the API layer: the chapters on ICE, SCTP, DTLS and SRTP, the accounts of how implementers debug and the interviews are the reason to read it, and CC0 lets you reprint any of it without credit. It is the wrong choice for anyone wanting runnable media code or a versioned document, because the repository ships a docs toolchain and no dated editions. Before mirroring it for a team, clone with submodules, confirm your Hugo binary is the extended build, and check the chapter you need exists under the tree you actually read.

Frequently asked questions

Official sources

1. Issues
2. License: CC0-1.0
3. Project website
4. README
5. webrtc-for-the-curious/webrtc-for-the-curious on GitHub