fix(recording): align mixed Instant audio sources to their capture times

[richiemcilroy]

Instant recordings that mix the microphone with system audio could place system audio up to 60 ms before the microphone. Which offset a recording got depended on when the mixer thread first polled.

Cause

sequenceDiagram
    participant Mic
    participant System
    participant Mixer
    participant amix
    Mic->>Mixer: first sample captured at 200 ms
    System->>Mixer: first sample captured at 260 ms
    Note over Mixer: inputs reach amix without pts
    Mixer->>amix: mic samples become sample 0
    Mixer->>amix: system samples also become sample 0
    Note over amix: system is now 60 ms early (2,880 samples)

Loading

• Each input's first sample became its own zero inside amix, so the gap between the two sources' first samples was lost.
• A startup branch sometimes prepended one 2,560-sample silence block to a source that had not delivered yet. That left two modes, -60 ms or -6.67 ms, depending on the poll schedule.
• Output is stamped start + samples_out / rate, so the offset stayed for the rest of the recording.

Fix

Every mixer input now keeps a sample cursor on one shared timeline, which starts at the earliest captured sample (crates/recording/src/sources/audio_mixer.rs).

let correction = placement_correction(
    position - source.samples_supplied as i128, // capture time vs cursor, in samples
    source.info.sample_rate,
    buffer.inner.samples(),
);

Capture time vs the source's cursor	Action
within 2 ms	continue the source untouched (timestamp jitter)
2 to 10 ms	move the cursor at most 1 sample per 256 (clock drift)
10 ms or more, later	fill the gap with silence (late first packet, dropout, pause)
10 ms or more, earlier	drop the input whose time is already committed, and count it

• Watermark. Mixed audio is committed only up to the earliest end among inputs that have delivered. A source that has not delivered yet is waited for up to 1 s (STARTUP_GRACE). After that it is filled with silence, and its first packet lands at its capture time.
• Stop. All mixed sources stop together, then the mixer drains every input and flushes amix, so audio still queued in the mixer reaches the file. The drain keeps only audio captured before Stop. A mixer that has not closed 2 s later, or an encoder that stops draining it, costs the audio not yet delivered, never the recording.
• Pause. The mixer now delays its output, so audio reaching the pipeline after Pause can still be from before it. Mixed audio is now paused by capture time: SharedWallClockPause records each pause interval, and frames that span a pause boundary are split (crates/recording/src/output_pipeline/core.rs). Recordings with one audio source keep the wall-clock pause path.

Measured

Instant system-minus-mic offset, synthetic sources with known capture times:

	main	This PR
System minus mic	-60 ms or -6.7 ms, depending on the poll schedule	0.0 ms in every run (macOS 20, Windows 20, Linux 3)

• Both sources now share the microphone's existing whole-track offset, about 15 ms on Linux and inside the existing 5 to 34 ms bound. That offset comes from anchoring the mixed track (AudioAnchor::FirstFrame) and is unchanged here.
• Recordings with one audio source do not go through the mixer and are unchanged.
• On the built-in MacBook Pro microphone, capture timestamps showed no jitter and drifted 8 samples in 30 s (6 ppm), so the drift path moves the cursor about one sample every 4 s.

Confidence Score: 5/5

The PR appears safe to merge; no blocking findings remain.

Summary

The PR aligns mixed audio sources by capture time and preserves queued audio during Stop.

• Mixed microphone and system audio now line up by capture time.
• Stopping a mixed recording keeps audio captured before Stop.
• Mixed audio pauses now follow when each sample was captured.

All four earlier, unnumbered findings are addressed. No new actionable issues were found.

_{Reviews (6) · Last reviewed commit: "fix: read the pause flag under the pause..." · Reviewed by Greptile}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
cap-status	Ready	Preview	Oct 16, 2026 5:03pm UTC

[capy-ai]

Capy found 2 potential issues (2 medium).

[richiemcilroy]

@greptileai review

[capy-ai]

Capy found no issues.

[richiemcilroy]

@greptileai review this PR

[capy-ai]

Capy found no issues.

[richiemcilroy]

@greptileai review

[capy-ai]

Capy found 1 potential issue (1 medium).

[richiemcilroy]

@greptileai review

[capy-ai]

Capy found 1 potential issue (1 medium).

View 1 other finding in Capy.

[capy-ai]

Capy found no issues.

[richiemcilroy]

@greptileai review