UVCProbeFix for macOS Tahoe - Fix Broken USB Webcam Video and Black Screen on Hackintosh

[MaLd0n]

UVCProbeFix is a macOS kernel extension designed to restore certain USB UVC webcams that are correctly detected by macOS but fail to produce a usable video stream, resulting in a black screen or a failed camera start.

 

Confirmed Working – Lenovo IdeaPad S145 Ice Lake

The fix has been verified through UVC runtime traces, not only by visual testing.

Before UVCProbeFix was active, the webcam returned a malformed PROBE response:

Frame:       4
Frame Size:  184549376
Payload:     16842753
Result:      Start Stream Failed

With UVCProbeFix loaded, the same camera negotiated:

Frame:       1
Frame Size:  614400
Payload:     3072
Interval:    333333

The captured PROBE response and COMMIT were byte-for-byte identical, after which macOS selected Stream Alternate Setting 6, opened the USB streaming pipe and reported start streaming for client.

The successful trace contains zero Start Stream Failed events.

Hardware: Lenovo IdeaPad S145 Ice Lake
Resolution: 640×480 YUV422 @ 30 FPS
Result: ✅ UVC negotiation recovered and video streaming successfully started.

 

The problem

Some UVC webcams enumerate normally and expose valid video formats, but their firmware returns malformed values during the UVC PROBE/COMMIT negotiation performed by macOS.

In the hardware case that led to this project, macOS selected a valid video mode, but the webcam returned an invalid GET_CUR(VS_PROBE_CONTROL) response containing incorrect frame-size and payload values.

macOS then committed those invalid parameters and attempted to start the stream, which resulted in a black image / stream startup failure.

The camera itself was functional. The failure happened during UVC negotiation.

What UVCProbeFix does

UVCProbeFix intercepts the affected negotiation path and applies a known-good recovery before macOS commits the broken configuration.

For the currently verified hardware case, the original negotiation behaves approximately like this:

macOS selects:
Frame 4
640x480
30 FPS

Camera returns:
Frame size: 184549376
Payload:    16842753

macOS COMMIT:
same invalid values

Result:
stream fails / black screen

UVCProbeFix detects this broken negotiation and performs a controlled re-negotiation using the working equivalent UVC frame.

The recovered negotiation becomes:

Frame:      1
Resolution: 640x480
Interval:   333333
Frame size: 614400
Payload:    3072

macOS then commits the corrected values and the camera starts producing real image data normally.

Important distinction

UVCProbeFix is not a generic webcam driver and it does not replace Apple's UVC stack.

It works alongside the existing macOS camera stack and targets a specific class of problems where:

• the webcam is detected;

• the UVC interface enumerates correctly;

• supported video formats are visible;

• PROBE/COMMIT negotiation occurs;

• but the camera firmware returns malformed negotiation values or a broken equivalent-frame path.

Problems involving USB power, physical connection, proprietary camera protocols, missing device enumeration, sensor failure or unsupported codecs are outside this recovery path.

Current release strategy

The production Release currently preserves the physically verified recovery implementation for the known working case.

The experimental branch also contains a descriptor-driven generic recovery engine intended to eventually support other webcams exhibiting the same class of UVC negotiation failure.

The generic design does not rely on a specific VID/PID or fixed camera model. Instead, it is being developed to:

• parse the webcam's own UVC descriptors;

• validate the returned PROBE data;

• identify impossible frame-size or payload values;

• discover equivalent frames dynamically;

• perform at most one safe re-negotiation;

• leave healthy webcams completely untouched;

• fail closed when a correction cannot be proven.

This generic path remains isolated from the stable Release until it passes sufficient real-hardware validation.

Compatibility

Initial target:

macOS Tahoe
Darwin 25.6
Intel x86_64
Lilu-based kernel extension environment

The current recovery has been physically validated on the hardware that originally exhibited the black-screen UVC negotiation issue.

Other webcams may exhibit a similar symptom for completely different reasons, so additional hardware must be analyzed before compatibility can be claimed.

Future webcam support

For additional webcams, the goal is not to create an endless VID/PID compatibility list.

The intended workflow is:

Passive UVC trace
        ↓
Analyze PROBE / COMMIT negotiation
        ↓
Parse the webcam's descriptors
        ↓
Identify the failure class
        ↓
Prove a safe recovery
        ↓
Add regression fixtures
        ↓
Test in Generic Recovery mode
        ↓
Hardware validation

This allows future fixes to be based on UVC behavior and descriptor evidence, rather than camera brand or model.

Safety

The project follows a conservative recovery policy:

• healthy negotiations are passed through unchanged;

• no arbitrary frame or payload values are guessed;

• unsupported or ambiguous cases remain untouched;

• internal recovery attempts are bounded;

• the stable legacy recovery remains isolated from experimental generic code.

Status

The original black-screen webcam case is working again under the stable recovery path.

Development is now focused on safely generalizing the same concept so that other UVC webcams with equivalent negotiation failures can potentially be recovered without camera-specific hardcoding.

Download Kext HERE

Download DUMP HERE

 

Credits

Special thanks to the developers and projects that made this work possible:

• Lilu by vit9696 / Acidanthera — kernel patching framework used by UVCProbeFix.

• MacKernelSDK by Acidanthera — kernel development headers and build support.

• Apple UVC / IOUSBHost stack — platform interfaces analyzed during development and debugging.

• Linux uvcvideo developers — valuable reference for UVC negotiation, descriptor parsing and recovery behavior.

• Olarila.com community — testing, feedback and hardware reports that help expand compatibility.

UVCProbeFix development and research: DNMTechLabs / MaLd0n
Contact: dnmtechlabs@gmail.com