mpv Media Player

mpv supports both single-file scripts and directory-based scripts.

Single File Scripts

• Use the .lua extension for Lua scripts.
• Files with the .disable extension are ignored by mpv.
• The script name (returned by mp.get_script_name()) is derived by stripping the extension and replacing non-alphanumeric characters with _ (e.g., my-tools.lua becomes my_tools).

Directory-based Scripts (Recommended for complex scripts)

If you point mpv to a directory (via --script or the scripts/ folder), mpv treats the directory as a single script and looks for a main.lua file inside it.

Important Rules for Directories:

• Do not place other files or directories starting with main. in the top level of your script directory (e.g., avoid having both main.lua and main.js).
• Use mp.get_script_directory() to locate the script's path for loading data files or other assets.
• mpv appends the script's top-level directory to the Lua package path, allowing you to use standard Lua require statements to import local modules.

Conditional profiles are applied automatically when a specific condition is met. These conditions are written as Lua expressions in the profile-cond option.

How it works

• If the expression evaluates to truthy, the profile is applied.
• If it evaluates to falsy or errors, the profile is not applied (and is 'unapplied' if it was previously active).
• The condition is re-evaluated whenever any property referenced in the expression changes.

Accessing Properties

• Automatic mapping: Identifiers are treated as properties. Note that _ in an identifier is converted to - (e.g., playback_time $\rightarrow$ playback-time).
• Robust access: Use p.property_name or get("property-name", default_value) to avoid issues with name collisions.

Reverting Conditional Profiles

To ensure a profile is removed when the condition becomes false, you must set profile-restore (e.g., profile-restore=copy).

# Make only HD video look funny
[something]
profile-desc=HD video sucks
profile-cond=width >= 1280
hue=-50

# Make only videos containing "youtube" or "youtu.be" in their path brighter
[youtube]
profile-cond=path:find('youtu%.?be')
gamma=20

# Revert profile when entering/leaving fullscreen
[something]
profile-desc=Mess Up video when entering fullscreen
profile-cond=fullscreen
profile-restore=copy
vf-add=rotate=PI/2

Profiles allow you to group settings under a name.

Defining Profiles

In a config file, a profile starts with [profile-name]. All subsequent options belong to that profile until another profile or [default] is declared.

Applying Profiles

• At startup: Use the --profile=<name> CLI flag.
• At runtime: Use the apply-profile <name> command.

Inspecting Profiles

• List available profiles: --profile=help
• View contents of a profile: --show-profile=<name>

Profile Restoration

Since apply-profile is destructive (it overwrites existing values), you can use the profile-restore option to allow reverting to previous states using apply-profile <name> restore.

profile-restore modes:

• default: No restoration possible.
• copy: Backs up old values before applying the profile. Restoring uses this backup.
• copy-equal: Similar to copy, but only restores an option if its current value matches the value set by the profile (useful if the user manually changed an option after applying the profile).

# normal top-level option
fullscreen=yes

# a profile that can be enabled with --profile=big-cache
[big-cache]
cache=yes
demuxer-max-bytes=512MiB
demuxer-readahead-secs=20

[network]
profile-desc="profile for content over network"
force-window=immediate
# include other profiles
profile=big-cache

[reduce-judder]
video-sync=display-resample
interpolation=yes

The mpv event loop is a continuous cycle that polls and dispatches mpv events, processes timers, and then waits for the next event.

If you need to intercept or debug all events sent to your script, you can implement a custom event loop. mpv will automatically attempt to call a function named mp_event_loop after the script loads if it exists.

Key components of the loop:

• Event Polling: Uses mp.wait_event(wait) to wait for events.
• Event Dispatching: Uses mp.dispatch_event(e) to trigger registered handlers (event handlers, property observers, script messages, etc.).
• Timer Processing: Uses mp.process_timers() to execute pending timers.
• Idle Observers: Uses mp.notify_idle_observers() to notify observers when the loop is about to sleep.

function mp_event_loop() {
    var wait = 0;
    do {
        var e = mp.wait_event(wait);
        dump(e);  // there could be a lot of prints...
        if (e.event != "none") {
            mp.dispatch_event(e);
            wait = 0;
        } else {
            wait = mp.process_timers() / 1000;
            if (wait != 0) {
                mp.notify_idle_observers();
                wait = mp.peek_timers_wait() / 1000;
            }
        }
    } while (mp.keep_running);
}