Fix Lightning webcam export flicker and harden export fallbacks

[webadderall]

Summary

• retry the main export decode path once with a readable file-backed source when packet reads fail
• keep Lightning webcam uploads on the safer canvas-staged path to avoid overlay flicker regressions
• pin webcam timing during temporal blur sampling and preserve the media-element fallback coverage
• round the Windows app icon and regenerate the packaged PNG/ICO assets

Testing

• npx vitest run src/lib/exporter/modernFrameRenderer.test.ts src/lib/exporter/modernVideoExporter.fallback.test.ts src/lib/exporter/streamingDecoder.test.ts

Summary by CodeRabbit

• Bug Fixes

  • Improved webcam overlay stability during temporal blur effects on WebGPU.
  • Enhanced video decode error recovery with automatic retry and fallback to alternative sources.
  • Better native encoder fallback handling when unavailable.

• Tests

  • Added comprehensive test coverage for webcam syncing and temporal blur rendering.
  • Extended test coverage for video decoder fallback mechanisms.

[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: 64311dfc-96a2-40f4-a6df-da8db424f943

📥 Commits

Reviewing files that changed from the base of the PR and between 6255890 and 62ab801.

⛔ Files ignored due to path filters (10)

• icons/icons/png/1024x1024.png is excluded by !**/*.png
• icons/icons/png/128x128.png is excluded by !**/*.png
• icons/icons/png/16x16.png is excluded by !**/*.png
• icons/icons/png/24x24.png is excluded by !**/*.png
• icons/icons/png/256x256.png is excluded by !**/*.png
• icons/icons/png/32x32.png is excluded by !**/*.png
• icons/icons/png/48x48.png is excluded by !**/*.png
• icons/icons/png/512x512.png is excluded by !**/*.png
• icons/icons/png/64x64.png is excluded by !**/*.png
• icons/icons/win/icon.ico is excluded by !**/*.ico

📒 Files selected for processing (5)

• src/lib/exporter/modernFrameRenderer.test.ts
• src/lib/exporter/modernFrameRenderer.ts
• src/lib/exporter/modernVideoExporter.fallback.test.ts
• src/lib/exporter/modernVideoExporter.ts
• src/lib/exporter/streamingDecoder.ts

---

📝 Walkthrough

Walkthrough

This PR strengthens export reliability and webcam rendering correctness. It adds a decode-failure retry mechanism with readable-file fallback, refactors native/WebCodecs encoder routing to handle late unavailability, threads reference time through temporal motion-blur webcam syncing for frame-center accuracy, and forces WebGPU webcam uploads through canvas staging for stability.

Changes

Export pipeline decode retry and native/WebCodecs fallback

Layer / File(s)	Summary
Streaming decoder forceReadableFileSource option src/lib/exporter/streamingDecoder.ts	loadMetadata() now accepts optional forceReadableFileSource flag to load via readable-file path before direct URL, with fallback preserved for non-forced calls.
Export decode failure retry with error detection src/lib/exporter/modernVideoExporter.ts, src/lib/exporter/modernVideoExporter.fallback.test.ts	export() detects primary-decode failures via token list and retries once with readable-file source enabled; backend selection is reset each iteration.
Native encoder deferred start and WebCodecs fallback src/lib/exporter/modernVideoExporter.ts	Deferred-native-encoder-start failures now log a warning, flip backpressure to WebCodecs, and initialize WebCodecs encoder to continue export instead of failing.

Webcam temporal reference timing and WebGPU stability

Layer / File(s)	Summary
Webcam sync reference time helpers and cache refresh src/lib/exporter/modernFrameRenderer.ts	refreshWebcamFrameCache(), resolveRenderableWebcamSource(), and new getExpectedWebcamTargetTimeSeconds() helper decouple webcam sync from currentVideoTime by accepting referenceTimeSeconds.
Webcam overlay update with reference time drift src/lib/exporter/modernFrameRenderer.ts	New updateWebcamOverlay() computes expected target time, measures actual time, calculates drift, and passes reference time downstream.
Temporal blur frame rendering with reference time override src/lib/exporter/modernFrameRenderer.ts	renderSceneSample() accepts webcamTimeSecondsOverride to pass frame-relative reference time; renderTemporalMotionBlurFrame() computes per-sample reference and passes it down.
WebGPU webcam canvas staging for stability src/lib/exporter/modernFrameRenderer.ts	stageVideoFrameForTexture() forces webcam uploads to canvas-staging path on WebGPU instead of retained VideoFrame uploads.
Webcam sync and temporal blur test coverage src/lib/exporter/modernFrameRenderer.test.ts	Adds WebGPU staging assertion, webcam live-state tests under offset/stale timelines, media-element cache-capture, decoder direct-render, and temporal blur sample-time pinning tests.
Type formatting and minor refactors src/lib/exporter/modernFrameRenderer.ts, src/lib/exporter/modernVideoExporter.ts, src/lib/exporter/streamingDecoder.ts	Multiline type/object formatting for clarity; no semantic changes.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related PRs

• webadderallorg/Recordly#461: Both PRs refactor native-defer/fallback control flow to route failures into WebCodecs instead of surfacing errors.
• webadderallorg/Recordly#447: Both PRs modify webcam sync and WebGPU staging for export recovery—main PR threads reference time through temporal samples while retrieved PR adds fallback to media-element sync.
• webadderallorg/Recordly#442: Both PRs adjust webcam temporal reference time and WebGPU frame/webcam staging during rendering.

Suggested labels

Checked

Suggested reviewers

• meiiie

Poem

🐰 Hops through time with temporal blur,
Webcam synced at frame's pure center,
Canvas staging keeps things stable,
Fallback loops make exports able. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description is incomplete per the template; it lacks most required sections (Motivation, Type of Change, Related Issues, Screenshots, Testing Guide, Checklist).	Complete the PR description template by adding all required sections: Motivation, Type of Change checkbox selection, Related Issue link, Testing Guide details, and the Checklist items.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly addresses both main changes: fixing Lightning webcam export flicker and hardening export fallbacks with a retry mechanism.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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/lightning-webcam-export-regressions

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint skipped: no ESLint configuration detected in root package.json. To enable, add eslint to devDependencies.

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

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.}