Skip to content

Record your screen, ship a demo. Free and open-source, GPU-accelerated, no watermarks, no subscriptions. Windows, macOS, Linux. Actively maintained.

docs: describe the mixer's resume handshake and clock anchoring

EtienneLescot32857bbd7bf9
diff --git a/technical-documentation/architecture/recording.md b/technical-documentation/architecture/recording.md
index a27887c23..35bafa57d 100644
--- a/technical-documentation/architecture/recording.md
+++ b/technical-documentation/architecture/recording.md
@@ -70,7 +70,7 @@ Windows and macOS both write their screen video as a fragmented MP4 — `MFCreat
A session writes a screen video and a `.session.json` manifest. Windows normally muxes the webcam into that MP4; when `webcamPath` is supplied, it writes a separate webcam video. macOS currently writes the webcam as a separate Electron sidecar (`webcamVideoPath`) because native webcam composition is not part of the helper. Linux follows the Electron recorder's separate media-path convention. Audio that the selected backend captures is encoded into its screen output.
-The Windows helper mixes system loopback and microphone into one track, and timestamps it from a running count of emitted frames. That count is advanced by a clock rather than by the arrival of samples: a chunk goes out every 10 ms for as long as the recording runs, filled from whichever source has data and with silence where neither does. Advancing it only when a queue held samples is what made a take that began in silence emit nothing at all — WASAPI loopback delivers no packets while nothing is playing — so the first sound landed at timestamp zero and the track came out shorter than the take. A working microphone concealed it by streaming continuously, which is why it appeared as a system-audio desync on a machine whose microphone had failed. `npm run test:wgc-audio-timeline:win` measures where a tone played at a known instant actually lands. The mixer writes 100 ms behind real time, and that cushion is what keeps a continuous voice whole: the capture threads poll WASAPI and hand packets over late (15.6 ms at the default timer resolution, more on a busy machine), and mixing at real time zero-filled every chunk whose packet had not arrived yet. The result was holes of up to 10 ms inside words, heard as crackle (#911). The timestamps still come from the frame count, so the cushion delays the writing, not the audio. A pause or a stop writes what it still holds up to that instant, and a source that ran dry, such as loopback after a silence, resumes a cushion ahead so it still lands when it played.
+The Windows helper mixes system loopback and microphone into one track, and timestamps it from a running count of emitted frames. That count is advanced by a clock rather than by the arrival of samples: a chunk goes out every 10 ms for as long as the recording runs, filled from whichever source has data and with silence where neither does. Advancing it only when a queue held samples is what made a take that began in silence emit nothing at all — WASAPI loopback delivers no packets while nothing is playing — so the first sound landed at timestamp zero and the track came out shorter than the take. A working microphone concealed it by streaming continuously, which is why it appeared as a system-audio desync on a machine whose microphone had failed. `npm run test:wgc-audio-timeline:win` measures where a tone played at a known instant actually lands. The mixer writes 100 ms behind real time, and that cushion is what keeps a continuous voice whole: the capture threads poll WASAPI and hand packets over late (15.6 ms at the default timer resolution, more on a busy machine), and mixing at real time zero-filled every chunk whose packet had not arrived yet. The result was holes of up to 10 ms inside words, heard as crackle (#911). The timestamps still come from the frame count, so the cushion delays the writing, not the audio. A pause or a stop writes what it still holds up to that instant, and a resume waits for that before clearing the queues. A source that ran dry, such as loopback after a silence, is queued behind silence as long as the mixer's real lag, so it still lands when it played. The clock is anchored when the timeline begins and at each resume, not when the mixer thread next wakes.
Before the keep-alive below, a mic-only recording did nothing to the render (output) endpoint: system-audio capture was the only path that even opened it, and it reads rather than writes — which reads as idle to some wireless headsets' own firmware idle timers, and they power the set down mid-take (#724: a Corsair Void dropped reliably seven to ten minutes in, as a full disconnect the OS never observes; the USB dongle stays enumerated and the WASAPI endpoints stay ACTIVE throughout, so `IMMNotificationClient` sees nothing, and neither do the device's PnP properties). The helper therefore keeps the endpoint fed: when system audio is not being captured, it opens a second, ordinary shared-mode render stream on the default output device and writes a 19 kHz tone at 0.3% amplitude for as long as the take runs — above what the large majority of adults can hear, and real signal rather than packets flagged `AUDCLNT_BUFFERFLAGS_SILENT`, because the same hardware testing that found the timer also found that digital silence does not hold it off while an actual waveform does. The gate is not an optimization: loopback already fills the endpoint with real content when it runs, and anything this stream wrote beside it would be mixed straight into the recording's own system-audio track. It is a workaround, not a fix — the timer lives in the headset's firmware, below everything an application can observe or configure, and the per-vendor setting (iCUE for Corsair, equivalents elsewhere) is the only way to turn it off; "inaudible" is likewise per listener, since hearing range and driver harmonics vary. `OPENSCREEN_WGC_DISABLE_AUDIO_KEEPALIVE=1` turns the stream off. `OPENSCREEN_WGC_LOG_AUDIO_DEVICE_EVENTS=1` runs a diagnostic device watcher alongside the take, logging endpoint state transitions as JSON events to stderr — with the expectation, learned from #724, that a real firmware drop logs nothing at all, for exactly the reason above.