fix(windows): normalize WGC video timestamps

[meiiie]

Summary

• Normalize WGC Media Foundation sample timestamps relative to the first video frame instead of writing absolute QPC timestamps into the MP4.
• Keep static-frame extension on the same normalized timeline so long static captures preserve their visible duration without inflating container metadata.
• Rebuild the bundled wgc-capture.exe and update the helper manifest entry for the rebuilt binary/source fingerprint.

Why

After PR #551, static WGC captures no longer collapsed at the stream level, but direct packaged helper smoke still showed ffprobe format.duration around 544,000 seconds while the video stream duration was only about 6 seconds. That is noisy metadata and could confuse consumers that read container duration instead of stream duration.

Validation

• npm run build:windows-capture
• Native helper manifest verification for wgc-capture: passed
• Direct bundled-helper smoke capture, no audio: format.duration=6.533300, video stream duration=6.533300
• Direct bundled-helper smoke capture, system audio: video format.duration=6.533300, system WAV duration=6.523979, timing sidecar written with startDelayMs=0
• npx tsc --noEmit
• npm test -- src/hooks/useScreenRecorder.test.ts src/lib/mediaTiming.test.ts electron/ipc/export/native-video.test.ts (126 passed)
• npx biome check electron/native/bin/win32-x64/helpers-manifest.json
• git diff --check

Known Baseline Check

npm test -- electron/ipc/recording/diagnostics.test.ts fails on current origin/main and on this branch with the same pre-existing expectation mismatch: the helper returns recording.system.wav in addition to the embedded video audio and mic companion. I did not mix that unrelated test/behavior fix into this timestamp PR.

Summary by CodeRabbit

• Bug Fixes
  • Enhanced timestamp synchronization in screen capture encoding to ensure consistent frame timing, maintain proper timeline continuity, and improve overall video encoding reliability.
  • Improved temporal accuracy and frame sequencing for more stable and dependable capture operations.
  • Updated platform-specific integrity verification for Windows 64-bit systems.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: f34b6431-9c70-442d-a7b5-6a6db891f20c

📥 Commits

Reviewing files that changed from the base of the PR and between e024060 and 978f014.

⛔ Files ignored due to path filters (1)

• electron/native/bin/win32-x64/wgc-capture.exe is excluded by !**/*.exe

📒 Files selected for processing (3)

• electron/native/bin/win32-x64/helpers-manifest.json
• electron/native/wgc-capture/src/mf_encoder.cpp
• electron/native/wgc-capture/src/mf_encoder.h

---

📝 Walkthrough

Walkthrough

MFEncoder adds timestamp normalization to normalize incoming sample timestamps to an encoder-local timeline. New helper methods track the first sample time and normalize timestamps before writing frames and extending the prior frame. The build manifest is updated to reflect the compiled changes.

Changes

MFEncoder Timestamp Normalization

Layer / File(s)	Summary
Contract declarations and helper implementations electron/native/wgc-capture/src/mf_encoder.h, electron/native/wgc-capture/src/mf_encoder.cpp	Header declares normalizeWriteTimestampHnsLocked and normalizeTimelineTimestampHnsLocked private methods and adds firstSampleTimeHns_ member initialized to -1. Cpp implements the helper functions to initialize and clamp normalized timestamps on first use.
Frame processing and lifecycle with normalized timestamps electron/native/wgc-capture/src/mf_encoder.cpp	writeFrame computes normalized timestamps before extending the last frame and writing samples. finalize resets firstSampleTimeHns_ to -1 during encoder teardown.
Build artifact refresh electron/native/bin/win32-x64/helpers-manifest.json	wgc-capture helper manifest entry updated with new binary hash, source fingerprint, and timestamp.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• webadderallorg/Recordly#551: Both PRs modify MFEncoder to preserve MP4 timeline continuity via timestamp handling and frame extension, and both refresh the wgc-capture helper manifest.
• webadderallorg/Recordly#276: Both PRs implement WGC sample timestamp normalization by tracking first-frame timestamp and normalizing timestamps before encoding.

Suggested labels

Checked

Poem

🐰 The rabbit hops through time-slides pure,
Normalizing frames to encode secure,
First samples tracked, timestamps made whole,
A manifest refreshed to reach the goal!
✨📹

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: normalizing WGC video timestamps on Windows, which is the core objective of the PR.
Description check	✅ Passed	The description comprehensively covers all essential template sections: summary of changes, motivation (the problem it solves), validation steps, and related context.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/windows-wgc-relative-timestamps

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}