mpv VideoToolbox Not Working macOS: How to Fix It

When mpv VideoToolbox is not working on macOS, the visible symptom may be high CPU usage, dropped frames, stuttering 4K playback, an unexpected software decoder, incorrect HDR output, or a file that refuses to play. The likely causes fall into a few categories: VideoToolbox is not enabled in the effective configuration, the installed mpv build lacks the expected capability, the media format is unsupported by the Mac's hardware, another option or script changes decoder selection, or hardware decoding works but the video-output and display path creates a separate problem. The safest approach is to establish a clean baseline, read mpv's terminal output, and change one variable at a time.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin with a local media file that plays successfully with software decoding. A local file removes yt-dlp, websites, authentication, network instability, and playlist handling from the first test. Open Terminal and run:

mpv --no-config --hwdec=videotoolbox --vo=gpu-next "/path/to/test-video.mkv"

Replace the sample path with the real file path. You can type the command through the opening quotation mark, drag the file from Finder into Terminal, add the closing quotation mark, and press Return. Quoting matters when a path contains spaces, brackets, apostrophes, or shell wildcard characters.

The --no-config option temporarily prevents normal user configuration files from affecting the test. It does not delete or modify those files. The --hwdec=videotoolbox option requests Apple's VideoToolbox hardware-decoding path, while --vo=gpu-next selects mpv's modern GPU video output.

Success means the video opens, terminal output identifies a VideoToolbox hardware-decoding path, playback remains stable, and CPU usage or dropped frames improves appropriately for the file. If that happens, stop changing system-level settings. The Mac, mpv build, file, and basic VideoToolbox path are compatible. Your persistent configuration, profile, binding, or script is then the likely cause.

1.1 Compare VideoToolbox With Software Decoding

Run the same file again with hardware decoding disabled:

mpv --no-config --hwdec=no --vo=gpu-next "/path/to/test-video.mkv"

If software decoding works but the explicit VideoToolbox test fails, you have isolated the problem to hardware decoding or its interaction with video output. If both commands fail identically, VideoToolbox may not be the root cause. Check the file, selected track, output driver, storage location, or broader mpv installation.

1.2 Ask the Installed Build Which Hardware Decoders It Exposes

Run:

mpv --no-config --hwdec=help

Review the output for VideoToolbox-related entries. The exact list depends on the installed build and platform. If no relevant entry appears, repeatedly editing mpv.conf will not create missing build support. Verify which mpv executable your shell is invoking with:

command -v mpv

Then inspect its version and build information:

mpv --version

This catches a common problem in which Terminal launches an older executable from a different package manager or directory while the user assumes it is launching a newer application bundle.

2. Check Options, Profiles, Scripts, and Tracks That Can Change the Result

Once the clean command succeeds, restore your normal setup carefully. Do not delete the entire configuration directory. First locate and inspect mpv.conf, commonly stored under ~/.config/mpv/. Depending on how mpv was installed and launched, another supported macOS configuration location may also be used. Terminal startup output and a log can help confirm which files are loaded.

2.1 Inspect the Effective Hardware-Decoding Option

Search configuration files for options such as:

• hwdec=no, which disables hardware decoding
• hwdec=auto or hwdec=auto-safe, which lets mpv select from available methods
• hwdec=videotoolbox, which explicitly requests VideoToolbox
• hwdec=videotoolbox-copy, which uses a copy-back path
• vo= settings that replace the video-output driver used in the clean test

mpv generally applies later option assignments over earlier ones. An option in a profile or command line can therefore override a setting near the top of mpv.conf. Look for duplicate assignments rather than assuming the first one is effective.

For a conservative everyday configuration, start with only the option that the clean test proved successful. Do not combine several untested GPU, HDR, shader, scaling, and decoder changes in the same edit.

2.2 Review Profiles and Input Bindings

Profiles can activate based on file properties, protocol, resolution, or a manual command. Inspect profile blocks in mpv.conf and any separate profile configuration. To display the contents of a named profile, use:

mpv --show-profile=PROFILE_NAME

Replace PROFILE_NAME with the real name. Check whether the profile changes hwdec, vo, HDR behavior, video tracks, filters, or shaders.

Also search input.conf for bindings that cycle hardware decoding, disable video, change tracks, load scripts, toggle filters, or apply profiles. A key pressed during playback can make behavior appear inconsistent between otherwise identical tests.

2.3 Temporarily Disable Scripts and Complex Shaders

A script can set properties at startup or after a file loads. Shaders and video filters can also require formats or frame access that change the practical behavior of a hardware-decoding pipeline. Test without normal configuration first, then temporarily move only the suspected script out of the scripts directory or disable its autoload mechanism. Test one component at a time.

If VideoToolbox works without a script but fails when that script returns, inspect the script's documentation and options. Success is a repeatable change tied to that specific component. Stop there rather than changing unrelated macOS permissions.

2.4 Confirm the Intended Video and Audio Tracks

A container may include multiple video tracks, cover art, alternate encodes, or unsupported auxiliary streams. Use mpv's track list or press the default stats-overlay key during playback to inspect the active track. You can also run:

mpv --no-config --hwdec=videotoolbox --vid=auto --aid=auto "/path/to/test-video.mkv"

Subtitle rendering normally occurs after video decoding and does not, by itself, prove that VideoToolbox failed. However, unusually complex styled subtitles can increase CPU or GPU load. Compare playback with subtitles disabled using --sid=no. If the decoder remains VideoToolbox but frame timing improves, the issue is subtitle rendering load rather than decoder selection.

Audio problems should be separated in the same way. Test with --audio=no only as a diagnostic step. If video becomes stable, investigate the selected audio track, external audio file, passthrough configuration, or audio device instead of changing hwdec.

3. Check Codec, Bit Depth, HDR, and Display Limitations

VideoToolbox is an operating-system framework that applications can use for hardware-accelerated video processing. Actual decoding support depends on the codec, profile, level, chroma format, bit depth, operating system, and specific Mac hardware. A format being supported by mpv's software decoders does not guarantee that every Mac can decode the same format in hardware.

3.1 Identify the Actual Codec Instead of Relying on the Extension

An MKV, MP4, or MOV extension identifies a container, not necessarily the encoded video format. Inspect mpv's terminal output or stats overlay for the video codec, profile, resolution, frame rate, pixel format, and bit depth.

Common variables include H.264 versus HEVC, 8-bit versus 10-bit video, 4:2:0 versus less common chroma formats, unusually high codec levels, and formats such as AV1 on hardware that does not accelerate them. Hardware support varies across Mac generations, so avoid treating a codec name alone as proof of compatibility.

If one ordinary H.264 file uses VideoToolbox but a particular 10-bit or unusual-profile file falls back to software, mpv itself is probably functioning correctly. The practical choices are to use safe software decoding, test copy-back, or use a compatible encode obtained from a lawful source. Do not install random codec packs. VideoToolbox capability is not added by a Windows-style codec bundle.

3.2 Test the VideoToolbox Copy-Back Path

Some filters, render paths, screenshots, or format conversions behave better when decoded frames are copied back into system memory. Test:

mpv --no-config --hwdec=videotoolbox-copy --vo=gpu-next "/path/to/test-video.mkv"

Copy-back can cost performance because frames must be transferred, but it is a valuable compatibility test. If direct VideoToolbox fails while videotoolbox-copy works reliably, use the copy-back method for the affected files or profile. Stop changing settings once playback, seeking, subtitles, and screenshots all behave correctly.

3.3 Separate HDR Output Problems From Decoder Problems

Successful hardware decoding does not guarantee correct HDR presentation. HDR output also depends on the encoded metadata, mpv's rendering and tone-mapping options, macOS display behavior, the display's capabilities, and the connection path. An external monitor, dock, adapter, cable, refresh-rate selection, or mirrored-display mode may limit the available color and HDR pipeline.

First test the same file on the Mac's built-in display, if available. Then test the external display without custom shaders or manually forced color-space options. If the log still reports VideoToolbox while the image is washed out, clipped, unusually dark, or displayed as SDR, the decoder is working. Investigate HDR passthrough, tone mapping, display mode, and output settings as a separate issue.

Do not force HDR metadata merely because a file looks wrong. Incorrect metadata overrides can make diagnosis harder. Return to defaults, confirm the source's real properties, and add one documented HDR option at a time.

3.4 Test Screenshots Without Misdiagnosing Playback

A screenshot failure does not necessarily mean hardware decoding failed. Direct hardware frames may interact differently with screenshot capture than copied or software-decoded frames. If playback is accelerated but screenshots are blank, incorrectly colored, or fail, compare direct VideoToolbox, videotoolbox-copy, and software decoding with the same frame.

If copy-back fixes screenshots while playback remains acceptable, it is a targeted solution. If only screenshot behavior changes, do not describe the original issue as a general decoder failure.

4. Check macOS Access, Paths, External Tools, and Network Inputs

macOS permissions rarely determine whether a supported local codec can use VideoToolbox, but they can prevent mpv or its launching terminal from reading files in protected locations. If the error concerns file access rather than decoder initialization, confirm that Terminal or the relevant mpv application has permission to access folders such as Desktop, Documents, removable volumes, or network locations.

Test by copying a lawful sample file to a simple user-owned directory and using its absolute path. If it works there, the issue is access or path handling, not VideoToolbox.

4.1 Isolate yt-dlp and Online URL Problems

For online media, mpv may rely on yt-dlp to resolve a webpage into playable streams. VideoToolbox only becomes relevant after mpv receives a compatible video stream. If URL extraction fails, authentication is required, the site changes, or yt-dlp is missing from the executable search path, changing hwdec cannot repair the extraction stage.

Confirm that a local file works first. Then run the online URL with verbose logging and inspect whether mpv identifies video and audio tracks. Check the external tool independently with:

command -v yt-dlp

If you configured a custom yt-dlp path, verify that it points to a trusted, executable installation. Use lawful streams and comply with the service's terms. Do not attempt to bypass DRM.

4.2 Distinguish Network Trouble From Decode Trouble

Buffering, reconnects, expired signed URLs, slow network shares, and unstable live streams can all resemble decoding stutter. Test the same stream at a lower lawful quality, inspect cache and demuxer messages, or download a permitted sample for local comparison. If the local copy uses VideoToolbox smoothly, decoder configuration is not the primary problem.

For network shares, compare playback after copying the file locally. If both copies report the same decoder but only the remote one stalls, investigate network throughput, latency, server behavior, and caching.

5. Use Terminal Output and Logs to Find the Exact Failure

Terminal output is more reliable than guessing from fan noise or CPU percentages. Create a focused log with:

mpv --no-config --hwdec=videotoolbox --msg-level=all=v --log-file="$HOME/Desktop/mpv-videotoolbox.log" "/path/to/test-video.mkv"

The log may contain local paths, URLs, filenames, system details, and other private information. Review and redact it before sharing publicly.

5.1 Search for Decoder Selection and Fallback Messages

Search the log for terms such as videotoolbox, hwdec, decoder, format, fallback, vo, and error. You are looking for the sequence of events:

1. mpv opens the intended source
2. It identifies the intended video track and codec
3. It attempts to initialize a VideoToolbox decoder
4. It either uses that path or explains why it cannot
5. It initializes the video output and begins presenting frames

A decoder name associated with VideoToolbox indicates hardware-decoder selection. A software decoder name after a failed hardware attempt indicates fallback. The exact wording can vary by mpv and FFmpeg build, so interpret the surrounding lines instead of matching one copied phrase from an old forum post.

5.2 Use the Stats Overlay During Playback

mpv's stats overlay can show decoder, frame timing, dropped frames, display synchronization, and media properties. In a default setup, the i key commonly displays statistics, although custom input bindings can change this. Compare direct VideoToolbox, copy-back, and software runs at the same scene.

Success is not merely a decoder label. The correct test is stable playback with expected seeking, subtitle behavior, color output, and acceptable resource use. If hardware decoding causes corruption or crashes while software playback is smooth, software decoding is the safer choice for that media.

6. Run a Clean Temporary Test Before Making Permanent Changes

Use a small test matrix and record the result of each command. This prevents several simultaneous edits from hiding the real cause.

1. Test software decoding with --no-config --hwdec=no
2. Test direct VideoToolbox with --no-config --hwdec=videotoolbox
3. Test copy-back with --no-config --hwdec=videotoolbox-copy
4. Repeat the successful command with your normal configuration enabled
5. Reintroduce the suspected profile, script, shader, subtitles, external display, or online source individually

If all three clean decoding tests fail, test a second known-good local file. If software works but both VideoToolbox modes fail across compatible test files, inspect build support and logs. If direct mode fails but copy-back works, use copy-back where required. If all clean modes work, the issue is inside your normal configuration or the original source.

When a test succeeds repeatedly, stop changing unrelated options. Preserve the working command, then translate only the necessary option into mpv.conf or a narrow profile.

7. Quick Fix Checklist

• Test a known-good local file before troubleshooting URLs, playlists, or network shares
• Run mpv --no-config --hwdec=videotoolbox to establish a clean baseline
• Use mpv --hwdec=help to confirm the installed build exposes VideoToolbox options
• Verify the executable path with command -v mpv
• Compare the same file with --hwdec=no
• Try --hwdec=videotoolbox-copy for filters, screenshots, or compatibility problems
• Check the actual codec, profile, bit depth, chroma format, and active video track
• Search configuration files for duplicate hwdec and vo assignments
• Inspect profiles with --show-profile and review custom input bindings
• Temporarily test without scripts, shaders, subtitles, or external audio
• Separate washed-out HDR output from successful hardware-decoder initialization
• Test the built-in display when an external display, dock, or adapter is involved
• Use a verbose log to identify hardware initialization and software fallback
• Confirm local playback before investigating yt-dlp or network access
• Use software decoding when it is more stable for an unsupported or problematic file

8. Frequently Asked Questions

8.1 How Do I Know Whether mpv Is Actually Using VideoToolbox?

Launch mpv from Terminal with an explicit --hwdec=videotoolbox option and inspect the startup output or a verbose log. Look for VideoToolbox in the selected hardware-decoding path and confirm the active decoder in the stats overlay. Do not rely solely on CPU usage because rendering, subtitles, shaders, audio, and other work can still consume CPU.

8.2 Why Does VideoToolbox Work for One File but Not Another?

The files may use different codecs, profiles, levels, bit depths, chroma formats, resolutions, or frame rates. Their containers can also hold different active tracks. Hardware capability varies by Mac model. If a conventional file works but an unusual file falls back cleanly to software, the behavior can be an expected media limitation rather than an mpv player issue.

8.3 Is VideoToolbox Copy-Back Still Hardware Decoding?

Yes, the decoding stage can still be hardware accelerated, but decoded frames are copied back to system memory. That copy may reduce efficiency compared with a direct path. It can nevertheless improve compatibility with certain filters, screenshots, render paths, or formats.

8.4 Can an External HDR Display Stop VideoToolbox From Working?

An external display usually affects presentation rather than basic decoder availability. Docks, adapters, cables, display modes, and macOS HDR settings can affect color, refresh rate, and HDR output. Check the log. If VideoToolbox initializes successfully but the picture is incorrect, troubleshoot the display and HDR path separately.

8.5 Is It Safe to Fall Back to Software Decoding?

Yes. Use --hwdec=no for a temporary test or a targeted profile. Software decoding may use more CPU and battery power, especially for high-resolution media, but it is a normal and safe fallback. If it produces stable, correct playback, it is preferable to forcing an incompatible hardware path.

8.6 Should I Delete My Entire mpv Configuration?

No. Start with --no-config, which bypasses configuration temporarily without deleting anything. If the clean test works, inspect options, profiles, bindings, and scripts individually. Back up files before editing them, and make one change per test so you can identify the exact fix.