mpv OSC OSD Not Showing: How to Fix It

When the mpv on-screen controller, on-screen display, or basic overlay does not appear, the player itself may still play video and audio normally. The most likely causes are a disabled OSC, an OSD level set too low, a conflicting configuration or profile, missing Lua support in the installed build, a script error, overridden input bindings, or a video-output problem that prevents overlays from being rendered. Start with a clean test rather than changing unrelated subtitle, HDR, codec, or network settings. Once the controller or OSD appears, stop changing options and reintroduce your custom configuration gradually.

1. Confirm the Symptom With a Minimal Clean mpv Command

The quickest way to troubleshoot mpv OSC OSD not showing is to launch one known-good local video without loading your normal configuration. This separates an installation or rendering problem from a problem inside mpv.conf, input.conf, scripts, or profiles.

1.1 Run mpv without your configuration

Close existing mpv instances, open a terminal, and run the appropriate command with a local media file:

mpv --no-config --osc=yes --osd-level=3 "path/to/test-video.mp4"

On Windows, run the command from PowerShell or Command Prompt using the path to mpv.exe if mpv is not on PATH:

C:\path\to\mpv.exe --no-config --osc=yes --osd-level=3 "C:\Videos\test-video.mp4"

On Linux or macOS, quote paths containing spaces:

mpv --no-config --osc=yes --osd-level=3 "/home/user/Videos/test video.mp4"

Move the pointer over the video window after playback begins. The OSC normally uses automatic visibility, so it may remain hidden until mouse movement is detected. Also press O to cycle the standard OSD display if default input bindings are available.

Success means the playback controls appear after mouse movement, or an OSD status message appears when you use an applicable default binding. If that happens, mpv can render overlays and the fault is probably in your configuration, bindings, profile, or user scripts. Stop investigating GPU drivers and operating system permissions at this point.

1.2 Distinguish the OSC from the OSD

The OSC and OSD are related but not identical:

• The OSC is the interactive controller containing elements such as the seek bar and playback buttons.
• The OSD displays temporary text, status information, seek feedback, track changes, and similar messages.
• Script overlays, subtitle rendering, and the stats display use related rendering facilities but have separate controls.

If OSD text appears but the mouse-controlled bar does not, focus on OSC and script settings. If neither appears, examine OSD level, video output, configuration conflicts, and build capabilities. If subtitles appear but the OSC and OSD do not, subtitle rendering alone does not prove that the OSC script loaded correctly.

2. Check Options and Configuration Directly Related to OSC and OSD Visibility

2.1 Look for osc=no and script-disabling options

Open your active mpv.conf in a text editor and search for settings that disable the controller or scripts. Common examples include:

• osc=no
• load-scripts=no
• scripts= or command-line script options that replace or alter loaded scripts
• script-opts=osc-visibility=never
• A profile containing any of these settings

Comment out one suspicious line at a time by placing # at the beginning, save the file, and restart mpv completely. You can also explicitly test osc=yes. Do not delete the entire configuration directory, because doing so makes it harder to identify the actual cause and may remove scripts or settings you want to preserve.

If the OSC returns after removing osc=no or enabling script loading, the direct cause has been found. Stop changing video, subtitle, HDR, or hardware-decoding options.

2.2 Verify automatic and forced OSC visibility

The OSC generally hides itself during playback and becomes visible after pointer movement. A controller that appears briefly at startup and then disappears may therefore be working as designed. Move the pointer inside the actual video window rather than over a terminal or another display.

To test forced visibility, launch mpv with:

mpv --no-config --osc=yes --script-opts=osc-visibility=always "path/to/test-video.mp4"

If forced visibility works, overlay rendering and Lua script execution are functioning. The remaining issue concerns automatic visibility, pointer events, a script option, or window focus. Return visibility to automatic after testing if you do not want the controller permanently displayed.

If you maintain an osc.conf file, inspect its visibility value. A value equivalent to never intentionally hides the controller. Temporarily rename only that file, restart mpv, and test again.

2.3 Check OSD level and default input bindings

An OSD level of zero disables on-screen messages. Search your configuration, command aliases, desktop launcher, and profiles for osd-level=0. Temporarily set:

osd-level=3

You can also test from the command line:

mpv --no-config --osd-level=3 --input-default-bindings=yes "path/to/test-video.mp4"

Custom input.conf entries can replace expected behavior. A binding assigned to O, mouse movement, mouse buttons, or script commands may prevent the expected test from working. Run with --no-config first. If that succeeds, inspect input.conf for duplicate or overridden bindings instead of assuming the key documented for a default installation still performs its default action.

Users who intentionally disabled default bindings should test with --input-default-bindings=yes. Success means the OSD works and the missing response came from input configuration, not the renderer.

2.4 Inspect profiles and per-file options

A global setting may look correct while a profile changes it later. Review named profiles in mpv.conf, auto profiles, protocol-specific profiles, and extension-specific profiles. Pay particular attention to profiles used for HDR, online video, low-latency streams, audio-only playback, or high-performance hardware decoding.

Use the following command to inspect a named profile:

mpv --show-profile=PROFILE_NAME

Replace PROFILE_NAME with the profile you invoke. Check whether the displayed options disable the OSC, scripts, OSD, default bindings, or the video window. Also inspect command-line aliases and desktop shortcuts because command-line options normally take precedence over configuration-file values.

2.5 Confirm that the installed build supports Lua scripts

The traditional built-in OSC is implemented as a Lua script, so the mpv build needs Lua support for that OSC implementation to run. Packaging choices can differ between operating systems, distributions, and third-party builds. A minimal or unusually packaged build may omit capabilities available in mainstream packages.

Run mpv --version and review the build information. Then launch mpv from a terminal and look for messages about Lua, scripts, or failure to load the OSC. If the build lacks required scripting support, install mpv through a trusted operating-system repository, the official project guidance, or a reputable package manager. Do not download random replacement binaries or codec packs.

Success means terminal output shows no OSC script-loading failure and mouse movement reveals the controls. If Lua support is absent, editing osc.conf cannot repair the package itself.

3. Separate Overlay Problems From Media and System Problems

3.1 Test with a known-good local video

Online URLs, playlists, network streams, and high-bitrate media add dependencies that are unrelated to OSC rendering. A URL may wait for network data, require yt-dlp, redirect, expire, or fail before a normal playback window is established. Test a short local file that you know mpv can decode.

If the OSC works with the local file, mpv's overlay system is operational. Troubleshoot the URL, network, playlist, or external tool separately. Updating yt-dlp through its trusted installation method can help URL extraction failures, but yt-dlp does not draw the OSC. Changing its path is not an OSC fix unless the original symptom was actually a URL that never opened.

3.2 Account for audio-only playback and window creation

An audio file may play without a visible video window, leaving nowhere for the OSC to appear. Test with:

mpv --no-config --force-window=yes --osc=yes "path/to/audio-file.flac"

If a window opens and the controller appears, the original behavior was caused by the absence of a window rather than a broken OSC. Audio-track selection and the audio backend generally do not control OSC visibility, although an early playback failure can close the window before you see it.

3.3 Compare video output and hardware decoding

Custom video-output, GPU API, hardware-decoding, shader, or HDR settings can expose driver or rendering problems. They should be investigated only if the clean test fails or the overlay disappears when a specific profile is enabled.

Start by allowing mpv to choose normal defaults:

mpv --no-config --hwdec=no --osc=yes --osd-level=3 "path/to/test-video.mp4"

If this works, repeat with your usual hardware decoding setting. Then reintroduce custom shaders, HDR options, GPU contexts, and video-output options one group at a time. Do not change all of them simultaneously.

Success with --hwdec=no does not automatically prove the hardware decoder itself is defective. A GPU driver, output context, interoperation path, or profile combination may be responsible. Update drivers through the GPU vendor or operating system, not through third-party driver sites.

3.4 Consider the display server and window environment

On Linux, behavior can differ between X11 and Wayland depending on the compositor, input handling, and selected GPU context. On Windows and macOS, remote desktop sessions, unusual scaling arrangements, fullscreen behavior, or multiple-display transitions may affect pointer events or rendering.

First leave fullscreen mode, focus the window, and move the pointer directly over it. Disable only third-party overlay tools or window-management rules that clearly interact with mpv. If the OSC is always visible with osc-visibility=always but does not wake on mouse movement, the problem is more likely input or pointer-event handling than video decoding.

3.5 Avoid chasing unrelated subtitle and screenshot settings

Subtitle visibility options affect subtitles, not the standard OSC. Track selection such as sid=no, aid=no, or vid=no can change media behavior, but it does not normally disable the controller. Likewise, screenshot format and screenshot-directory settings do not govern OSD visibility.

There are limited indirect connections. Using vid=no may prevent a normal video window unless one is forced, and screenshots can intentionally omit overlays depending on the screenshot command or mode. If the complaint is that the OSD is missing only from saved screenshots, first confirm whether it remains visible in the live window. That is a screenshot-capture question, not an OSC-loading failure.

4. Use Logs and Runtime Information to Find the Conflict

4.1 Capture terminal output and a log file

Start mpv from a terminal instead of a graphical file association so errors remain visible. For a reusable log, run:

mpv --log-file=mpv-osc-test.log --msg-level=all=v "path/to/test-video.mp4"

Verbose logs can be large, so reproduce the problem, close mpv, and then search the log for terms such as osc, lua, script, error, vo, and gpu. Do not post logs publicly without checking them for local file paths, usernames, private stream addresses, access tokens, or headers.

A clear script-loading error should be addressed before changing decoder settings. A video-output initialization error points toward the GPU, driver, display server, or output configuration. A failed URL extraction message points toward the URL or external tool rather than the OSC.

4.2 Use the stats overlay and track list carefully

If the stats overlay can be opened through your build's active binding, script overlays are being rendered. That is useful evidence even when the OSC remains absent. Because custom input files can alter the default stats key, consult the active bindings or invoke the relevant script binding rather than relying solely on a remembered shortcut.

The track list helps determine whether mpv actually opened audio, video, and subtitle tracks. It is relevant when an empty, audio-only, or failed stream is mistaken for an overlay problem. If a valid video track is active and normal playback continues while all overlays are missing, return attention to OSD level, scripts, and video output.

4.3 Compare configured and clean runs

Create two logs using the same local file:

1. Run once with your normal configuration.
2. Run again with --no-config --osc=yes --osd-level=3.
3. Compare script-loading, profile, input, and video-output messages.
4. Identify the earliest meaningful difference instead of focusing on harmless informational lines.

If only the configured run fails, your installed mpv and basic overlay path are probably sound. The clean result provides a known baseline for controlled testing.

5. Run a Clean Temporary Test Before Making Permanent Changes

The safest repair method is to prove one change at a time. Keep a copy of individual configuration files before editing, but do not erase the whole configuration directory.

1. Test a known-good local video with --no-config, --osc=yes, and --osd-level=3.
2. Move the mouse inside the focused window and test a default OSD action.
3. If successful, run again with your normal mpv.conf but temporarily exclude user scripts.
4. Add input.conf and OSC script options back separately.
5. Enable named profiles, shaders, HDR settings, and hardware decoding one group at a time.
6. Restart mpv after each configuration change and repeat the same action.

Stop as soon as one restored option makes the OSC disappear. The last group contains the likely conflict. Narrow that group line by line. This method is faster and more reliable than simultaneously updating drivers, replacing packages, rewriting bindings, and changing media settings.

Success looks like repeatable behavior: the OSC appears on mouse movement, forced visibility works when requested, and OSD messages appear at the selected level. Once those results remain stable with your desired configuration, no further troubleshooting is necessary.

6. Quick Fix Checklist

• Run mpv --no-config --osc=yes --osd-level=3 "file".
• Move the pointer within the focused playback window.
• Remove or comment out osc=no.
• Check for load-scripts=no and OSC visibility set to never.
• Test forced visibility with osc-visibility=always.
• Enable default bindings temporarily and inspect custom input.conf entries.
• Check profiles with --show-profile.
• Confirm the installed mpv package has the scripting support required by the OSC.
• Use a local video before testing yt-dlp, playlists, or network streams.
• Use --force-window=yes for audio-only tests.
• Test without hardware decoding and custom shaders only if the clean overlay test fails.
• Capture a verbose log and search for Lua, OSC, script, video-output, and GPU errors.

7. Frequently Asked Questions

7.1 Why does the mpv OSC appear only when I move the mouse?

Automatic visibility is normal OSC behavior. The controller hides to avoid covering the picture and reappears after pointer activity. Use forced visibility temporarily to confirm it works, then return to automatic visibility if preferred.

7.2 Can the OSD work while the OSC is broken?

Yes. OSD messages and the script-based OSC are separate enough that one may work while the other fails. If OSD text appears but the controller does not, inspect OSC enablement, Lua support, OSC configuration, and script-loading errors.

7.3 Why does --no-config fix the problem?

It means the clean mpv baseline works and something normally loaded is changing behavior. Likely causes include mpv.conf, input.conf, an automatic profile, OSC script options, or a user script. Reintroduce those components individually until the symptom returns.

7.4 Does yt-dlp control the mpv OSC?

No. yt-dlp can resolve supported online URLs and provide media information to mpv, but it does not render the OSC. If local files show the controller and an online URL does not open correctly, troubleshoot URL extraction, network access, and the external tool separately.

7.5 Can hardware decoding or HDR settings hide overlays?

They do not normally disable the OSC by design, but a problematic GPU, output, shader, driver, or hardware-decoding combination can interfere with rendering. Test clean defaults and software decoding, then restore the advanced settings one group at a time.

7.6 Should I reinstall mpv immediately?

No. First use --no-config, verify OSC and OSD options, inspect logs, and confirm Lua support. Reinstall or replace the package only when evidence points to a damaged or feature-limited build, and use a trusted repository or package source.