mpv Osc.conf Ignored: How to Fix It

You edited script-opts/osc.conf, restarted mpv, and the on-screen controller still looks exactly the same. When mpv ignores OSC customization, the usual causes are a misplaced file, the wrong active configuration directory, an invalid option name or value, an overridden setting, a disabled OSC, missing Lua scripting support, or a frontend that supplies its own controller. The steps below isolate those possibilities without deleting your configuration or disturbing unrelated subtitle, HDR, hardware-decoding, shader, yt-dlp, playlist, or input settings.

1. Confirm the Symptom With a Minimal Clean mpv Command

Begin by proving that the mpv process you are launching can display and customize its built-in on-screen controller. Use a local media file for this test. A local file removes network access, yt-dlp, stream authentication, and remote-server behavior from the investigation.

Open a terminal or command prompt and run:

mpv --no-config --osc=yes --script-opts=osc-layout=box,osc-scalewindowed=2.0 "path/to/video.mp4"

On Windows, replace mpv with the full path to mpv.exe if it is not available through PATH. Quote paths containing spaces. On Linux and macOS, confirm that the terminal command launches the same mpv installation used by your desktop shortcut or file association.

Move the pointer over the video window after playback begins. The clean test intentionally ignores your normal configuration and requests an enabled OSC with conspicuous layout and scale changes.

• If the controller changes, mpv's OSC works and your normal configuration path, file contents, profile, or override is responsible.
• If the default controller appears but does not change, inspect terminal output for an unknown script option or unavailable layout value.
• If no controller appears, verify that you launched plain mpv rather than a graphical frontend and check whether the build supports the scripting functionality needed by the OSC.
• If mpv cannot open the media, repeat the test with a simple, known-good local file before investigating the OSC.

Success means the controller becomes visibly larger or uses the requested layout. Once that happens, stop changing playback drivers, codecs, subtitle settings, or hardware decoding. They are not the cause of this symptom.

2. Check the OSC Configuration Directly

2.1 Put osc.conf in the script-opts directory

The OSC configuration does not normally belong directly beside mpv.conf. Its expected relative path is script-opts/osc.conf inside mpv's active user configuration directory.

Common locations are:

• Windows: %APPDATA%\mpv\script-opts\osc.conf
• Linux: ~/.config/mpv/script-opts/osc.conf
• macOS: ~/.config/mpv/script-opts/osc.conf

Environment variables, command-line arguments, packaging systems, or portable configurations can change the active directory. On Windows, a portable_config directory beside mpv.exe can take precedence over the roaming application-data location. Linux packages installed through sandboxed systems may also use package-specific storage or permissions.

Check that the filename is genuinely osc.conf, not osc.conf.txt. Windows File Explorer can hide known file extensions, making this mistake difficult to see. Also verify capitalization on case-sensitive filesystems. The directory should be named script-opts, including the hyphen.

A correct structure resembles:

mpv/
├── mpv.conf
├── input.conf
└── script-opts/
    └── osc.conf

Success means mpv loads a visible test value from this exact file after a complete restart. Once confirmed, keep the path and remove only the temporary test value.

2.2 Use OSC option names in the correct format

Inside osc.conf, write the OSC script's option name without the command-line osc- prefix. For example:

layout=box
scalewindowed=2.0
hidetimeout=1500

The equivalent command-line form places those options inside --script-opts and prefixes each one with the script name:

--script-opts=osc-layout=box,osc-scalewindowed=2.0,osc-hidetimeout=1500

Do not copy arbitrary examples without checking the mpv manual applicable to your installation. Option names can be misspelled, values can be outside accepted ranges, and an example written for a third-party OSC script may not apply to mpv's standard OSC. Use plain text, one assignment per line, and avoid typographic quotation marks.

For diagnosis, reduce osc.conf to one conspicuous, documented setting such as:

scalewindowed=2.0

Restart mpv and move the pointer over a windowed video. If the controller becomes much larger, the file is loading. Stop troubleshooting the path and reintroduce your preferred OSC settings one at a time. If one addition breaks or fails, that line is the likely problem.

2.3 Look for osc=no and later overrides

Open mpv.conf and search for:

osc=no

That setting disables the standard OSC. Change it to osc=yes for testing, or comment it out if you want the default behavior. Also inspect startup commands, desktop shortcuts, shell aliases, profiles, and frontend launch arguments for --no-osc or --osc=no.

Order matters when the same option is set more than once. A later command-line argument can override a value loaded from mpv.conf. Profiles may apply additional options when selected manually or automatically. If a profile contains osc=no, the OSC can disappear only for particular files, protocols, displays, or launch methods.

Success means the standard controller appears when the pointer enters the video window. At that point, do not change video output or hardware decoding. Find and remove only the conflicting OSC override.

2.4 Separate OSC options from input bindings

input.conf controls key and mouse bindings. It is not the correct location for OSC appearance settings. An input binding can still make the problem look like an OSC failure if it changes mouse behavior, disables interaction, or invokes script messages intended for another controller.

Temporarily rename only input.conf, restart mpv, and test pointer movement. Do not delete the file. If the OSC starts responding, restore the file and inspect custom mouse bindings or script commands individually.

Likewise, subtitle styling, audio-track selection, video-track selection, screenshot templates, HDR tone mapping, shaders, and hwdec do not determine whether osc.conf is parsed. They should be investigated only if the actual symptom concerns those features rather than the controller.

3. Verify OSC Lua Support and Frontend Behavior

3.1 Confirm that the standard OSC is available

mpv's standard OSC is implemented through its scripting system. A build without the relevant Lua scripting support may play video successfully while failing to provide the expected scripted controller. Run mpv from a terminal and examine its startup output. You can also use a verbose log as described later.

If your package lacks required scripting support, obtain mpv through the official project guidance or a trusted operating-system package source. Do not install random codec packs or download replacement binaries from unverified file-hosting sites. OSC availability is a player-build issue, not a missing media codec.

Success means terminal output shows no scripting or OSC initialization failure and --osc=yes produces the controller. Once verified, reinstalling codecs or changing GPU drivers will not improve osc.conf loading.

3.2 Determine whether a frontend owns the controller

Many applications use mpv as a playback engine while drawing their own controls. A frontend's toolbar may resemble mpv's OSC but remain completely independent from script-opts/osc.conf. Some frontends disable mpv's standard OSC intentionally to avoid displaying two controllers.

Launch the mpv executable directly from a terminal with a local file. If your OSC customization works there but not in the frontend, mpv is not ignoring the file. The frontend is replacing the controller, disabling it, using another configuration directory, or passing later options.

Check the frontend's documentation for its controller settings and mpv argument handling. Do not force both controllers on unless that is the behavior you want. Success means either the frontend's own controller is customized through its settings or the standard mpv OSC is deliberately enabled and visible.

4. Check Paths, Permissions, and Editing Errors

Permissions become relevant when mpv can see its configuration directory but cannot read osc.conf. Confirm that the user account launching mpv has read access to the file and execute access to its parent directories. Avoid running mpv as an administrator or with sudo merely to make configuration loading work, because that can switch the home directory and create misleading ownership problems.

On Linux and macOS, inspect the file with:

ls -l ~/.config/mpv/script-opts/osc.conf

On Windows, open the file's Properties dialog and check that it is not blocked or restricted to another account. If a text editor saved the file elsewhere because the target folder was protected, use Save As and verify the complete destination path.

Other common editing problems include:

• Saving rich text rather than plain text
• Using a similarly named directory for a different mpv installation
• Editing a symbolic link whose target no longer exists
• Launching mpv under another user account
• Leaving an invalid value or invisible copied character in the file
• Testing a window-only scale option while mpv is fullscreen

GPU drivers, display servers, audio backends, media bitrate, subtitles, HDR metadata, and hardware decoding are generally irrelevant when only OSC customization is ignored. They become relevant only when the entire window fails to render, pointer events do not reach the application, or playback itself is broken. Keep the investigation scoped to the observed symptom.

5. Use Terminal Output and Diagnostic Logging

5.1 Create a targeted mpv log

Run a local test while writing diagnostic output to a file:

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

Then search mpv-osc.log for terms such as osc, lua, script, config, unknown, and error. The goal is not to read every decoder message. Look specifically for the configuration files being loaded, script initialization, rejected options, or a command-line override.

If maximum verbosity produces too much output, narrow the message level after the first test. Keep the original log until you identify the active configuration path. Be careful before sharing logs publicly because launch arguments and URLs can contain local filenames, tokens, usernames, or private network addresses.

Success means the log identifies the loaded OSC script and contains no error for your test option. If the log shows a different configuration location, move or copy only osc.conf to the correct script-opts directory rather than deleting your existing configuration tree.

5.2 Inspect profiles and runtime information

If you suspect a named profile, ask mpv to display it:

mpv --show-profile=profile-name

Replace profile-name with the profile defined in mpv.conf. Review its expanded options for OSC disabling or script-option overrides. Automatically applied profiles also deserve attention if the issue occurs only with certain protocols, file extensions, or display conditions.

The stats overlay is useful for confirming which player instance, tracks, decoder, and output path are active, but it does not prove that osc.conf loaded. Similarly, the track list can explain missing subtitle, audio, or video controls, but it does not control the OSC's layout. Use those tools only if the controller appears and the real complaint is that a track selector is empty or a media track is unavailable.

For online URLs, first prove OSC behavior with a local file. yt-dlp location, network access, authentication, and stream limitations affect whether content opens, not whether a valid local osc.conf is parsed. This separation prevents two unrelated problems from being debugged at once.

6. Run a Clean Temporary Test Before Changing Multiple Options

A controlled comparison is safer than deleting the entire mpv folder. Preserve your configuration and test one layer at a time.

1. Close every mpv window and frontend using mpv.
2. Start a local file with --no-config --osc=yes.
3. Add a visible command-line OSC option through --script-opts.
4. If it works, launch normally with a one-line osc.conf.
5. If that fails, verify the active configuration directory and filename.
6. If it works, restore OSC options individually.
7. Restore custom scripts, profiles, and input bindings one group at a time.

This sequence tells you whether the fault is in mpv's OSC capability, config discovery, OSC syntax, or interaction with another customization. Restart mpv after every configuration-file change. OSC settings are normally read when the script initializes, so editing the file while an existing player process remains open should not be expected to update that process.

On systems or frontends that retain a background mpv process, closing the visible window may not end the process. Exit the frontend fully or verify through the operating system's process viewer. Success means a newly started process displays the revised controller. Once you see that result, stop changing settings and restore only the customizations you still need.

7. Quick Fix Checklist

• Place the file at script-opts/osc.conf inside the active mpv configuration directory.
• Confirm the file is not secretly named osc.conf.txt.
• Use plain OSC names such as scalewindowed=2.0 inside the file.
• Use osc-scalewindowed only in the --script-opts command-line form.
• Remove or override osc=no and --no-osc.
• Test plain mpv rather than a frontend with a custom controller.
• Confirm the mpv build provides the scripting support required by the OSC.
• Restart the entire mpv process after editing the file.
• Use a local file to eliminate yt-dlp, network, and stream failures.
• Generate a log and search for OSC, Lua, config, and option errors.
• Test profiles and custom scripts separately instead of deleting the configuration folder.

8. Frequently Asked Questions

8.1 Where should osc.conf be located?

It should normally be inside the script-opts directory under mpv's active configuration folder. Typical paths are %APPDATA%\mpv\script-opts\osc.conf on Windows and ~/.config/mpv/script-opts/osc.conf on Linux and macOS. Portable, sandboxed, or explicitly redirected installations may use another location.

8.2 Why does osc.conf work in mpv but not in my frontend?

The frontend may draw its own controls, disable mpv's standard OSC, pass overriding command-line options, or launch mpv with another configuration directory. Test the same file using the plain mpv executable. If customization works there, use the frontend's controller settings or documentation.

8.3 Does mpv need to be restarted after editing osc.conf?

Yes, a full restart is the reliable approach because OSC script options are loaded during initialization. Close all mpv windows and make sure a frontend has not retained a background process. Then open a new player instance and test the setting.

8.4 Can osc=no make mpv ignore all OSC customization?

Yes. If the standard OSC is disabled, changing its layout, scale, visibility timing, or buttons will not produce a visible result. Search mpv.conf, profiles, shortcuts, aliases, and frontend arguments for osc=no or --no-osc.

8.5 Are hardware decoding, HDR, subtitles, or yt-dlp responsible?

Usually not when the only symptom is an unchanged controller. Those components affect decoding, presentation, tracks, or online extraction. Test OSC behavior with a simple local file and --no-config. Investigate those systems only if playback, rendering, track availability, or URL opening is also failing.

8.6 What is the safest final test?

Run mpv directly with a local file, --no-config, --osc=yes, and one conspicuous --script-opts change. If that works, create a one-line script-opts/osc.conf in the confirmed active directory. When the same visual change appears after restart, the issue is fixed and you can restore options one at a time.