fix(wgc-capture): pre-flight H.264 MFT check + actionable error

[EtienneLescot]

Summary

When MFCreateSinkWriterFromURL fails on Windows with hr=0x80070003, the user
sees a wall of HRESULT noise with no actionable next step. The root cause in
issue #15 is that no H.264 Media Foundation Transform (MFT) encoder is
registered on the system (missing Media Feature Pack, an empty
HKLM:\SOFTWARE\Microsoft\Windows Media Foundation\Transforms registry key,
or a GPU driver that did not register its hardware encoder). This change makes
the helper diagnose that situation directly so the stderr dump tells the user
(and us) what to try next.

This implements items 1 and 2 of issue #15 only. The explicit software
H.264 fallback via mfh264enc.dll (issue #18) is intentionally out of scope
for this PR; per the task contract it is tracked separately.

What changed

• electron/native/wgc-capture/src/mf_encoder.cpp — added three helpers
  in the anonymous namespace:

  • countRegisteredMfts(category, inputMajorType, outputSubtype) — enumerates
    MFTEnumEx activations, releases them, returns the count. Uses
    MFT_REGISTER_TYPE_INFO input/output type blobs (the universally supported
    signature) and MFT_ENUM_FLAG_ALL so both sync and async hardware MFTs
    (AMD AMF, NVIDIA NVENC, Intel Quick Sync) are counted.
  • countRegisteredH264VideoEncoders() — wraps the helper for H.264 video
    encoders.
  • countRegisteredAacAudioEncoders() — wraps the helper for AAC audio
    encoders.
  • logMissingH264EncoderError() — emits the four-bullet actionable error
    from the issue.

  In MFEncoder::initialize(...):

  • Before MFStartup, count H.264 encoders. If zero, emit the actionable
    error and return false.
  • On MFCreateSinkWriterFromURL failure, log the H.264 encoder count, the
    AAC encoder count (only when audio is requested), and the hex HRESULT.
    When an H.264 encoder IS registered but the sink writer still fails, log
    a hint pointing at output path / mux / driver incompatibility.

• electron/native/README.md — added one paragraph in the Windows section
  documenting the new pre-flight check and the diagnostic dump that follows a
  sink-writer failure.

No public API changes; mf_encoder.h is unchanged. Renderer / Electron main
process / IPC are unchanged. The Swift macOS helper is unchanged.

Why

Fixes #15. The user from the issue had a fully working system with all
required DLLs present but empty HKLM:\SOFTWARE\Microsoft\Windows Media Foundation\Transforms and HKLM:\SOFTWARE\Classes\MediaFoundation\Transforms
registry keys. Today the helper prints an opaque ERROR: MFCreateSinkWriterFromURL failed (hr=0x80070003) and stops. With this change, the same failure mode
produces:

ERROR: No H.264 video encoder MFT is registered on this system.
  Windows could not find any Media Foundation Transform that outputs MFVideoFormat_H264.
  MP4 recording requires an H.264 encoder. Without one, MFCreateSinkWriterFromURL fails (hr=0x80070003).
  Try the following fixes in order:
    1. Install the Media Feature Pack via Optional Features (Settings > Apps > Optional features > Add > Media Feature Pack),
       or run: Dism /online /add-capability /capabilityname:Media.MediaFeaturePack~~~~0.0.1.0
    2. Update your GPU drivers so the hardware H.264 encoder MFT (AMD AMF, NVIDIA NVENC, Intel Quick Sync) re-registers itself.
    3. Inspect the registered transforms under HKLM:\SOFTWARE\Microsoft\Windows Media Foundation\Transforms
       and HKLM:\SOFTWARE\Classes\MediaFoundation\Transforms.
    4. Reboot after driver or Media Feature Pack changes; MFT registration is cached at boot.

…and if the sink writer fails for a different reason (e.g. the H.264 encoder
IS registered but the mux is misconfigured), the same stderr dump now also
includes:

ERROR: MFCreateSinkWriterFromURL failed (hr=0x...)
  Registered H.264 video encoder MFTs: 2
  Registered AAC audio encoder MFTs: 1
  An H.264 encoder MFT is registered but the sink writer still failed. Possible causes: invalid output path or permissions, no MP4 mux configured, or GPU driver incompatibility with this Media Foundation build.

That is enough information to distinguish the four failure modes from the
issue (no H.264 / encoder exists but sink cannot wire it / AAC missing / other).

Testing

• npx tsc --noEmit: passes.
• npm run lint: same baseline as 1a17f8b — 309 pre-existing format
  errors on CRLF in TS files unrelated to this PR. This PR adds zero new lint
  errors (Biome ignores .cpp / .md extensions in this repo's config; the
  two changed files do not contribute to the count).
• npm run test (Vitest unit): 225/225 pass.
• npm run build:native:win: compile-tested on Windows with Visual
  Studio 2022. Both wgc-capture.exe and cursor-sampler.exe link
  successfully with no warnings from mf_encoder.cpp. The pre-existing
  C4245 / C4456 warnings in webcam_capture.cpp and dshow_webcam_capture.cpp
  are unchanged.

Manual smoke test status

Not performed on a real Windows recording session by the author. No
Windows VM was available in this environment; the build host is Linux but
the build script for Windows happens to also work because VS 2022 Build
Tools are installed there. The pre-flight path and sink-writer diagnostic
path are exercised only by a successful Windows recording session, which
requires a real display + GPU + Windows desktop.

Suggested manual smoke test on a real Windows host:

npm run build:native:win
npm run test:wgc-helper:win   # happy path; should record to MP4 with no errors

To exercise the new error path on a system with no H.264 encoder (rare; the
issue #15 reporter's system qualifies), the existing npm run test:wgc-helper:win
script should now print the actionable bullet list instead of the bare
HRESULT. To exercise the sink-writer diagnostic path, point the helper at an
invalid output path (e.g. a directory that does not exist) — the helper will
log the encoder counts plus the 0x... HRESULT.

Out of scope (confirmed)

• Issue [Feature]: Software H.264 fallback when GPU encoder MFT is unavailable #18 — explicit software H.264 fallback via mfh264enc.dll. This PR
  only surfaces the missing-encoder condition; it does not attempt to load
  mfh264enc.dll or any other software fallback encoder. That work remains
  to be tracked in a separate PR.

Summary by CodeRabbit

• Bug Fixes
  • Added a pre-flight validation for Windows recording to confirm required video encoders are available before starting, preventing unclear startup failures.
  • Improved failure diagnostics with clearer, actionable console output that distinguishes “missing video encoder” from other sink/writer setup issues.
  • When audio recording is enabled, enhanced error messages to also report the availability of audio encoder support.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 926bcc72-ce27-4f21-baba-12b04129d5bd

📥 Commits

Reviewing files that changed from the base of the PR and between b6263b1 and f8f4eeb.

📒 Files selected for processing (1)

• electron/native/wgc-capture/src/mf_encoder.cpp

🚧 Files skipped from review as they are similar to previous changes (1)

• electron/native/wgc-capture/src/mf_encoder.cpp

---

📝 Walkthrough

Walkthrough

Adds Media Foundation Transform enumeration helpers (countRegisteredMfts, encoder-specific wrappers, logMissingH264EncoderError) to mf_encoder.cpp. MFEncoder::initialize gains a pre-flight H.264 encoder check that fails immediately with an actionable error if none are registered. The MFCreateSinkWriterFromURL failure path is reworked to log the HRESULT and encoder counts. The README documents both behaviors.

Changes

H.264 MFT pre-flight check and improved sink-writer diagnostics

Layer / File(s)	Summary
MFT enumeration helpers and error message electron/native/wgc-capture/src/mf_encoder.cpp	Adds countRegisteredMfts(...) (uses MFTEnumEx, releases IMFActivate objects, returns count), thin wrappers countRegisteredH264VideoEncoders and countRegisteredAacAudioEncoders, and logMissingH264EncoderError that prints a multi-step actionable error to std::cerr.
Pre-flight check in initialize and reworked sink-writer error path electron/native/wgc-capture/src/mf_encoder.cpp	MFEncoder::initialize counts H.264 encoders before MFStartup and returns false immediately if none are found. The MFCreateSinkWriterFromURL call is made directly; on failure it prints the HRESULT, H.264 encoder count, optional AAC count, and a follow-up hint when H.264 is registered but sink-writer creation still fails.
README documentation electron/native/README.md	Documents the pre-flight MFTEnumEx enumeration, its failure mode when no H.264 encoders are registered, and the added stderr encoder-count logging on sink-writer failure.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related issues

• #15 — Failed to initialize Media Foundation encoder (hr=0x80070003): This PR directly addresses the root cause identified in the bug by adding a pre-flight MFTEnumEx check that detects missing H.264 encoder registrations (exactly the condition described in the issue—empty HKLM:\SOFTWARE\Classes\MediaFoundation\Transforms registry keys) and emits a clear, actionable error message instead of the opaque hr=0x80070003 failure.

Poem

🐰 Hop hop, before the encoder's begun,
I check if H.264 is there — find none?
I print a clear warning, no mystery left,
No silent 0x80070003 theft.
With MFTEnumEx I count and I see,
Now broken Windows machines know what to fix — yippee! 🎉

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 14.29% 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 clearly and concisely summarizes the main changes: adding a pre-flight H.264 MFT check and actionable error handling to wgc-capture.
Description check	✅ Passed	The PR description follows the template with all major sections completed: Summary, Related issue (Fixes #15), Type of change (Bug fix), Release impact, Desktop impact (Windows), and comprehensive Testing details.
Linked Issues check	✅ Passed	The PR fully implements items 1 and 2 from issue #15: pre-flight H.264 MFT enumeration with actionable error messaging, and enhanced diagnostic logging on sink writer failure to distinguish encoder registration states.
Out of Scope Changes check	✅ Passed	All changes are scoped to issue #15 items 1–2 (diagnosis and error messaging). Item 3 (software H.264 fallback via mfh264enc.dll) is explicitly documented as out of scope and tracked in issue #18.

_{✏️ 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/issue-15-mf-encoder-mft-preflight

---

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

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@electron/native/wgc-capture/src/mf_encoder.cpp`:
- Around line 61-63: Move the H.264 encoder preflight check block (the code at
lines 61-63 that calls MFTEnumEx and returns 0 on failure) to execute after the
MFStartup call completes successfully, since MFTEnumEx requires platform
initialization first. Additionally, revise the error handling for the
enumeration failure case to distinguish between actual enumeration errors and a
legitimate "no encoder registered" scenario, rather than mapping both to a
return value of 0, so that real errors are properly surfaced instead of being
hidden in the error message at line 200-203.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0f2cdcfc-9fbb-449f-8cec-7c9fab9ceb23

📥 Commits

Reviewing files that changed from the base of the PR and between 8246d07 and b6263b1.

📒 Files selected for processing (2)

• electron/native/README.md
• electron/native/wgc-capture/src/mf_encoder.cpp