Lua scripting in mpv video player

Recently, I needed to cut a video fragment without re-encoding. I wasn't happy with how LosslessCut handled it, so I started looking for alternatives.

On Reddit, I came across a post claiming that this could be done using the mpv-cut script. And this approach doesn't require an external GUI or additional programs.

I checked it and the mpv-cut script turned out to be a Lua script that lets you cut a video fragment directly while watching it in the mpv player.

I hadn’t expected that the minimalist mpv player would support scripts that expand its functionality. I decided to check it out and see how it works.

Using mpv-cut

Let's start with the script itself: how to install and use it.

mpv has a configuration folder. On Linux, it's located at ~/.config/mpv, and on Windows at %AppData%\Roaming\mpv. You need to create a scripts directory in this folder (if it doesn't already exist) and clone the Git repository there:

git clone -b release --single-branch "https://github.com/familyfriendlymikey/mpv-cut.git" ~/.config/mpv/scripts/mpv-cut

You also need to have ffmpeg installed and added to your system's PATH variable.

Once this is set up, opening a file in mpv will automatically activate the script. When you reach the fragment you want to extract, press "c" on your keyboard to start copying. Press "c" again to stop copying. The video fragment will be saved in the same directory as the source file with a name like COPY_1_video_FROM_00-00-07-457_TO_00-00-21-332.mkv.

You can play the saved fragment to verify that all streams (audio, video, and subtitles) are intact—nothing was re-encoded; only a section was cut out.

At this point, take a look at the main.lua file in the mpv-cut folder, but it may be too complex for a first script. So let’s start by writing a simple "Hello, World" script for mpv.

Hello, World for the mpv Player

Open your favorite text editor and create a file named hello.lua in the scripts folder. Enter the following code:

function hello_world()
    print("Hello, World!")
end

mp.add_key_binding("h", "hello_world", hello_world)

You don’t need to install Lua separately for mpv. The player has a built-in Lua interpreter.

Since mpv has no graphical menu, you define functions and bind them to key presses. In this case, pressing the "h" key will print "Hello, World!" to the terminal.

Here’s a sample video from the freely distributed Sintel animation by Blender. I’ll later demonstrate how to display a list of subtitles using this video.

You can test the script by playing any video and pressing "h" to check if "Hello, World!" appears in the terminal.

Subtitle List

Now, let's create an example that retrieves information from the currently playing video. Instead of "Hello, World!", we’ll print a list of subtitles to the terminal.

function show_subtitles()
    print("Subtitle List:")
    print("ID Language Format")

    local track_list = mp.get_property_native("track-list")

    for _, track in ipairs(track_list) do
        if track.type == "sub" then
            print(track.id, track.lang, track.codec)
        end
    end
end

mp.add_key_binding("h", "show_subtitles", show_subtitles)

The mp.get_property_native("track-list") function in mpv returns a list of all tracks in the current video file. This includes video, audio, and subtitle tracks, along with their metadata such as ID, language, codec type, and other properties.

This time, we bind the show_subtitles function to the "h" key.

The output looks something like this:

[hello] Subtitle List:
[hello] ID Language Format
[hello] 1 ger subrip
[hello] 2 eng subrip
[hello] 3 spa subrip
[hello] 4 fre subrip

In mpv, the 'j' key (located right next to 'h') cycles through available subtitle tracks and displays information about the current track on screen. Press "h" and "j" several times to compare the output of our script with the built-in subtitle track switching function to make sure that our script works correctly.

Where to Find More Information?

I wanted simply to demonstrate that mpv supports Lua scripting and provide a couple of examples. Here are some resources to learn more about this.

You can read about Lua scripting in mpv in the official documentation.

Examples of Lua scripts included with the mpv package can be found on Linux at: /usr/share/doc/mpv/examples/lua/

These scripts are also available in the mpv Git repository.

A large collection of user-contributed scripts can be found here:
https://github.com/mpv-player/mpv/wiki/User-Scripts

On mpv's Customizability

The flexibility and configurability of mpv are impressive, offering many possibilities for users.

For example, when learning languages, it's convenient to display subtitles in two languages simultaneously (mpv supports this even without scripts). With scripts, you can do much more: create Anki cards from video content, perform simple editing and cropping, automatically switch tracks, and so on.

Take another look at the user script collection - you might find a solution for your needs or inspiration for creating your own script.