How to Extend mpv Media Player with Lua Scripts?

The mpv media player is a highly customizable, open-source command-line player, and one of its most powerful features is its support for Lua scripting. By leveraging Lua, users can automate tasks, create custom user interfaces, manage playlists, and integrate third-party tools directly into their playback experience. This article provides a quick guide on how to find, install, and write basic Lua scripts to unlock the full potential of your mpv media player.

Understanding mpv’s Scripting Architecture

At its core, mpv exposes a comprehensive API (Application Programming Interface) to its internal scripting engine. This allows Lua scripts to intercept player events, read and modify property values, and bind custom functionality to keyboard shortcuts. Because Lua is lightweight and fast, these scripts run with minimal overhead, ensuring that your media playback remains smooth and responsive.

How to Install Existing mpv Lua Scripts

You do not need to be a programmer to benefit from Lua scripts, as the mpv community has created hundreds of pre-made extensions. To install a script, follow these steps:

1. Locate your mpv configuration directory:

• Windows: %%APPDATA%%\mpv\ or the portable_config folder inside your mpv directory.
• Linux/macOS: ~/.config/mpv/

2. Create a scripts folder: If it does not already exist, create a new folder named scripts inside your configuration directory.
3. Download and drop: Place any downloaded .lua script files directly into this scripts folder. mpv will automatically load them the next time it starts.

Writing Your First Custom Lua Script

If you want to build your own functionality, creating a basic script is remarkably straightforward. Below is an example of a simple Lua script that displays a custom message on the screen and prints a log to the console when a specific key is pressed.

-- Define the function to execute
function display_welcome_message()
    mp.osd_message("Hello from your custom Lua script!", 3)
    print("Welcome message triggered successfully.")
end

-- Bind the function to the 'ctrl+g' key combination
mp.add_key_binding("ctrl+g", "show-welcome", display_welcome_message)

Key Components of the Script

• mp.osd_message(text, duration): This function displays On-Screen Display (OSD) text directly over the video player window for a specified number of seconds.
• print(text): This outputs text to the terminal or command prompt window running mpv, which is highly useful for debugging your code.
• mp.add_key_binding(key, name, function): This binds a specific keyboard shortcut to your custom Lua function, allowing for seamless interactivity.

Popular Use Cases for mpv Lua Extensions

The possibilities with Lua scripting are vast. Some of the most popular community-driven scripts focus on enhancing the default user experience in the following areas:

• Advanced On-Screen Controllers (OSC): Replacing the minimal default player interface with modern, feature-rich graphical interfaces.
• Autoload Next File: Automatically searching the current directory and appending the next chronological video or audio track to the active playlist.
• Subtitle Managers: Integrating with online databases to automatically fetch, rename, and load subtitles based on the currently playing file hash.
• Playback Logging: Keeping a detailed history of everything you watch, which can optionally sync to third-party tracking services like Trakt or Last.fm.