Skip to content

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

fix(windows): address review findings on the keep-alive and device watcher

EtienneLescote1f88ee04ded
diff --git a/electron/native/wgc-capture/src/wasapi_device_watcher.cpp b/electron/native/wgc-capture/src/wasapi_device_watcher.cpp
index 60384678d..8cd73c9b6 100644
--- a/electron/native/wgc-capture/src/wasapi_device_watcher.cpp
+++ b/electron/native/wgc-capture/src/wasapi_device_watcher.cpp
@@ -129,8 +129,12 @@ void WasapiDeviceWatcher::stop() {
deviceEnumerator_->UnregisterEndpointNotificationCallback(this);
}
registered_ = false;
- deviceEnumerator_.Reset();
+ // The worker dereferences deviceEnumerator_ (writeBaseline calls
+ // GetDefaultAudioEndpoint through it), and stop() can run while events are
+ // still queued -- main.cpp calls this on every early-failure path, potentially
+ // right after start() enqueued the baselines. Drain and join first, release
+ // the enumerator last, or the worker wakes up holding a dangling pointer.
if (worker_.joinable()) {
{
std::lock_guard<std::mutex> lock(queueMutex_);
@@ -139,11 +143,12 @@ void WasapiDeviceWatcher::stop() {
queueCv_.notify_one();
worker_.join();
}
+ deviceEnumerator_.Reset();
}
void WasapiDeviceWatcher::workerLoop() {
- // This thread owns all name resolution and all std::cout writes for this
- // watcher, so nothing here runs on an IMMNotificationClient callback thread.
+ // This thread owns all name resolution and all event writes for this watcher,
+ // so nothing here runs on an IMMNotificationClient callback thread.
while (true) {
PendingEvent event;
{
@@ -197,9 +202,10 @@ void WasapiDeviceWatcher::writeBaseline(const PendingEvent& event) {
device->GetState(&state);
const std::wstring name = friendlyNameForDevice(deviceEnumerator_.Get(), id);
- // Built as one complete string before the write, and written with a single
- // stream operation under outputMutex_, so main.cpp's own JSON writes can't
- // land in the middle of this line.
+ // Built as one complete string before the write, and emitted with a single
+ // stream operation. Events from helper threads go to stderr -- the
+ // microphone-defaulted warning set that precedent -- so stdout protocol
+ // lines stay owned by the main thread alone.
std::ostringstream line;
line << "{\"event\":\"audio-device-watch\",\"schemaVersion\":1,\"type\":\"baseline\","
"\"flow\":\""
@@ -207,8 +213,7 @@ void WasapiDeviceWatcher::writeBaseline(const PendingEvent& event) {
<< "\",\"deviceName\":\"" << jsonEscape(wideToUtf8(name)) << "\",\"state\":\""
<< deviceStateLabel(state) << "\",\"timestampMs\":" << nowUnixMillis() << "}\n";
- std::lock_guard<std::mutex> lock(outputMutex_);
- std::cout << line.str() << std::flush;
+ std::cerr << line.str() << std::flush;
}
void WasapiDeviceWatcher::enqueue(const wchar_t* eventName, LPCWSTR deviceId, const char* extraJson) {
@@ -236,8 +241,7 @@ void WasapiDeviceWatcher::writeDeviceEvent(const PendingEvent& event) {
}
line << ",\"timestampMs\":" << nowUnixMillis() << "}\n";
- std::lock_guard<std::mutex> lock(outputMutex_);
- std::cout << line.str() << std::flush;
+ std::cerr << line.str() << std::flush;
}
ULONG STDMETHODCALLTYPE WasapiDeviceWatcher::AddRef() {
@@ -295,7 +299,9 @@ HRESULT STDMETHODCALLTYPE WasapiDeviceWatcher::OnDefaultDeviceChanged(
if (role != eConsole) {
return S_OK;
}
- char extra[16];
+ // Sized for the longest payload: "flow":"capture" is 16 chars plus the
+ // terminator, and 16 bytes truncates the closing quote into a malformed line.
+ char extra[32];
snprintf(extra, sizeof(extra), "\"flow\":\"%s\"", flow == eRender ? "render" : "capture");
enqueue(L"default-changed", defaultDeviceId, extra);
return S_OK;
diff --git a/electron/native/wgc-capture/src/wasapi_device_watcher.h b/electron/native/wgc-capture/src/wasapi_device_watcher.h
index 930d104f1..47301d733 100644
--- a/electron/native/wgc-capture/src/wasapi_device_watcher.h
+++ b/electron/native/wgc-capture/src/wasapi_device_watcher.h
@@ -26,7 +26,17 @@
// A DEVICE_STATE_NOTPRESENT/UNPLUGGED transition on the render or capture endpoint,
// correlated with the moment the user hears the drop, points at (1) or (3). No event
// at all around the drop, with the endpoint remaining ACTIVE throughout, would point
-// at (2) instead.
+// at (2) instead -- but the converse does not hold: the confirmed case in #724
+// (Corsair Void Wireless) produced zero events across every live drop, because the
+// USB dongle stays enumerated and ACTIVE the whole time and only the RF link to the
+// earcups drops, which is invisible to IMMNotificationClient. So silence here does
+// not rule out a firmware timer; before concluding (2), check the vendor's own
+// power management (e.g. iCUE) and a with-loopback vs mic-only comparison.
+//
+// Events are written to stderr, as one complete line per write: thread-emitted
+// events go to stderr in this helper (the microphone-defaulted warning set that
+// precedent), leaving stdout protocol lines owned by the main thread alone. Both
+// streams end up merged in the drained helper log.
//
// IMMNotificationClient callbacks must be nonblocking (never resolve names, take a
// lock that can wait, or do I/O) per Microsoft's documented contract, so the
@@ -99,7 +109,4 @@ private:
std::condition_variable queueCv_;
std::queue<PendingEvent> queue_;
bool workerStopRequested_ = false;
- // Guards std::cout so the worker's writes and main.cpp's own JSON event writes
- // don't interleave into a malformed line.
- std::mutex outputMutex_;
};
diff --git a/electron/native/wgc-capture/src/wasapi_render_keepalive.h b/electron/native/wgc-capture/src/wasapi_render_keepalive.h
index 3862226be..de08b606f 100644
--- a/electron/native/wgc-capture/src/wasapi_render_keepalive.h
+++ b/electron/native/wgc-capture/src/wasapi_render_keepalive.h
@@ -9,9 +9,11 @@
// alive, and loopback capture already does that as a side effect when it runs.
//
// This opens an ordinary render stream on the same default output device and
-// writes a near-inaudible tone to it for as long as a recording is running,
-// independent of whether system audio is being captured, since mic-only is
-// exactly the case that leaves the endpoint untouched otherwise.
+// writes a near-inaudible tone to it for as long as a recording is running. It
+// only runs when system audio is NOT being captured: loopback capture already
+// fills the endpoint with real content of its own, so there is nothing to keep
+// alive, and anything written here alongside it would end up in the recording's
+// system-audio track.
//
// Real signal, not digital silence: confirmed on real hardware that writing
// AUDCLNT_BUFFERFLAGS_SILENT packets does not reliably stop a wireless headset's
@@ -25,11 +27,16 @@
// A first attempt at 1kHz / 1% amplitude was clearly audible in testing -- 1kHz
// sits in the most sensitive part of human hearing, so "quiet" in raw amplitude
// terms was still perceptibly loud. The tone is now 19kHz (above what the large
-// majority of adults can hear at all) at 0.3% amplitude, adapted downward if the
-// device's actual sample rate can't represent 19kHz cleanly. It is never captured
-// into the recording itself, since this writes to the render endpoint and the
-// recording only captures it when system-audio (loopback) is also on -- the same
-// case that already doesn't need this workaround.
+// majority of adults can hear at all) at 0.3% amplitude. It is not adapted to the
+// device: on a mix format whose sample rate cannot represent 19kHz with margin,
+// start() refuses to run at all rather than alias it into an audible frequency.
+// The tone is never captured into the recording itself, because this stream only
+// exists when loopback capture is off.
+//
+// Known limitation: the stream targets whatever the default render endpoint is at
+// start and never re-targets. If the user switches output devices mid-take, the
+// new default is not protected for the rest of the recording (the device watcher,
+// if enabled, logs the switch).
//
// Kill-switch: set OPENSCREEN_WGC_DISABLE_AUDIO_KEEPALIVE=1 to turn this off.
@@ -49,9 +56,10 @@ public:
WasapiRenderKeepAlive(const WasapiRenderKeepAlive&) = delete;
WasapiRenderKeepAlive& operator=(const WasapiRenderKeepAlive&) = delete;
- // Opens the default render endpoint in shared mode and starts writing silence.
- // Returns false on any failure -- including another app holding the device
- // exclusively -- which callers must treat as non-fatal to the recording itself.
+ // Opens the default render endpoint in shared mode and starts writing the
+ // keep-alive tone. Returns false on any failure -- including another app
+ // holding the device exclusively -- which callers must treat as non-fatal to
+ // the recording itself.
bool start();
void stop();
diff --git a/technical-documentation/architecture/recording.md b/technical-documentation/architecture/recording.md
index a191ec0c7..af1c6b101 100644
--- a/technical-documentation/architecture/recording.md
+++ b/technical-documentation/architecture/recording.md
@@ -72,6 +72,8 @@ A session writes a screen video and a `.session.json` manifest. Windows normally
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.
+What a mic-only recording does to the render (output) endpoint is: nothing. System-audio capture is the only path that even opens 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.
+
The macOS helper mixes the same two sources into one AAC track (`AudioTrackMixer`) and runs the same discipline, arrived at from the opposite direction. There the emit cursor is anchored to the writer session start and advanced by a monotonic clock read off `CMClockGetHostTimeClock` — the domain ScreenCaptureKit already timestamps its buffers in — with a 10 ms timer on the sample queue moving it while nothing is arriving to move it. The bug it replaces was the anchor, not the counter: `anchor` was set lazily on the first decoded buffer to `max(firstPresentationTime, sessionStart)`, so audio that first arrived four seconds in made frame zero of the track *be* four seconds in. The trailing half was worse still — `drain()` ran only from `ingest` and `finish`, and the helper never called `writer.endSession(atSourceTime:)` at all, so the file ended at the last sample anything happened to deliver. Both halves and any mid-take gap are now one mechanism: chunks go out for as long as the take runs, from whichever source covers them and from silence where none does, and a source is written off for a chunk only once it has gone 250 ms without delivering anything — a decision about when to stop waiting, which shifts nothing, and not a correction, which would. Measured from that source's own last delivery rather than from how far behind the clock its coverage sits, because those differ for a source that is alive but arriving late: a capture path delivering a fixed delay behind the audio it describes would be "behind" forever, so writing it off for that would emit silence and then drop its real samples, every chunk, for the whole take. A pause freezes the clock rather than resetting it, so what follows keeps the position it would have had. Whether ScreenCaptureKit's system-audio output is silence-gapped the way WASAPI loopback is has never been recorded anywhere, and it decides how much of a take the clock is carrying alone rather than how the mixer should work; the helper now reports it per take as `audio-timeline`, whose `undeliveredSeconds` is the whole track if the tap is gapped and near zero if it streams silence. That figure counts what each source handed over rather than what came out of the mixer — holes under two seconds are zero-filled into the source's own buffer, so a hole read off the mixed output would come back covered, which is the exact case it exists to catch — and `droppedSeconds` beside it is the cost side, counting audio that arrived too late to place and reading zero unless the grace is too short for that tap. `swift test` runs the mixer against a collecting sink and a hand-moved clock on every pull request (`swift-macos-helper` in ci.yml, the first Swift job this repository has had); `npm run test:sck-audio-timeline:mac` measures a real tone through a real device, comparing the audio track's length against the video track's in the same file.
The Linux helper mixes the same two sources into one AAC track as well (`AudioMix` in `electron/native/pipewire-capture/src/capture.rs`), and its emit cursor is the data-driven one Windows had: `AudioEncoder::next_pts` is a running count of the samples handed to the encoder, advanced only when a block is encoded, and `AudioMix::pump` returns early when no input has any. Nothing in that code makes a chunk go out for every chunk of real time — what does is the tap. System audio here is the default sink's MONITOR, and PipeWire keeps delivering its buffers whether or not anything is playing, silence included, where WASAPI loopback simply stops. So the count advances at real time for as long as the take runs and the cursor cannot stall. That is a property of the capture source and not of the timeline code, which is the thing to know before moving Linux audio off the sink monitor: a source that gates silence would reproduce the Windows failure above exactly (#406). The anchor half is a decision rather than an accident — the first video frame sets the epoch and clears the audio rings at that instant ("video frame 0 is now, so audio sample 0 is now too"), which is what keeps the pre-roll captured while the portal picker was up, an interval with no upper bound, from shifting the whole track earlier; `cargo test` covers it. The tail is covered by `Capture::finish`, which drains the rings and flushes the AAC encoder before the video flush, so the file ends with the take rather than with the last sound in it. What a mid-take overflow costs is bounded the same way: the ring drops its oldest samples and owes back silence of exactly that length, so the encoder falling two seconds behind leaves a gap where it happened instead of pulling every later sound earlier for the rest of the recording, and it is reported as `audio-dropped`. `npm run test:pw-audio-timeline:linux` measures it end to end — a tone played at a known instant, then the audio track's length against the video track's in the same file. Before it, the whole record that any of this held was one sentence in a commit message: a live 29-second capture whose 18-second tone came back as 18 seconds of steady signal, with the two streams ending 62 ms apart (video 29.100 s, audio 29.162 s). That 62 ms is also why the script allows 250 ms between the tracks where the macOS one allows 100: those two come out of a single writer session, and these two do not — the video track ends at the last `advance()` and the audio track at everything the rings still held, plus AAC's final padded block.