Need help with mpv-playlistmanager?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

209 Stars 22 Forks The Unlicense 229 Commits 12 Opened issues


Mpv lua script to create and manage playlists

Services available


Need anything else?

Contributors list

# 48,097
2 commits


Mpv lua script to create and manage playlists.

This script allows you to see and interact with your playlist in an intuitive way. The key features are removing, reordering and playing files. Additional features include resolving url titles, parsing filenames according to patterns and creating/saving/shuffling/sorting playlists. The script also allows to automatically save the mpv playlist, e.g. for regular backups.

Default visual cues:
○ default file
▷ playing file
● hovered file(for removing, playing and moving)
▶ playing and hovered file
➔ selected file(file is being moved)
➤ playing and selected file
It will make sense once you try the script!


Copy the

file to your mpv scripts directory which is usually
. See and for more detailed information.


You can modify behaviour of the script in the settings variable in the lua file or a

lua-setting file in
directory. Note: the conf file will override any changed setting in the lua file. There is a playlistmanager.conf file in this repo with the default values of the script.

You can pass settings from the command line on startup such as

mpv --idle=once --script-opts=playlistmanager-loadfiles_on_start=yes

You can also change settings during runtime with a keybind or command like

KEY change-list script-opts append playlistmanager-showamount=10

If you are using save-position-on-quit then the playlist will write watch later config when switching between files.

Url title resolving

If you want playlistmanager to fetch and display titles of all playlist urls(mpv defaults to current file only) you will need to use

resolve_titles = yes
(default is no) setting. Title resolving requires
to be in PATH to work.


Static keybindings

  • sortplaylist(CTRL+p)
    • Sorts the current playlist with stripped values from filename(not media title, no paths, usercreated strips applied). To start playlist from start you can use a script message
      KEY script-message sortplaylist startover
      . Settings involving sort include alphanumeric sort(nonpadded numbers in order, case insensitivity), sort on mpv start and sort on file added to playlist.
  • shuffleplaylist(CTRL+P)
    • Shuffles the current playlist. Stops currently playing file and starts playlist from start of new playlist unlike native shuffle that doesn't shuffle current file.
  • reverseplaylist(CTRL+R)
    • Reverses the current playlist. Does not stop playing the current file.
  • loadfiles(P)
    • Attempts to load all files from the currently playing files directory to the playlist keeping the order. Option to run at startup if 0 or 1 files are opened, with 0 opens files from working directory. On startup with no file requires
      --idle=yes or --idle=once
  • saveplaylist(p)
    • Saves the current playlist to m3u file. Saves to
      by default.
  • showplaylist(SHIFT+ENTER)
    • Displays the current playlist and loads the dynamic keybinds for navigating

If you want to use the above controls from a "gui" rather than keybinds, then you can check out mpv-menu and use the

found in this repository.

Dynamic keybindings

  • moveup(UP)
    • Moves the cursor up in playlist, if at first entry loops to end of playlist.
  • movedown(DOWN)
    • Moves the cursor down in playlist, if at last entry loops to start of playlist.
  • movepageup (Page Up)
    • Moves the cursor one page up in the playlist, or to the first entry.
  • movepagedown (Page Down)
    • Moves the cursor one page down in the playlist, or to the last entry.
  • movebegin (Home)
    • Moves the cursor to the first entry in the playlist.
  • moveend (End)
    • Moves the cursor to the last entry in the playlist.
  • removefile(Backspace)
    • Removes the file currently selected with the cursor from the playlist
  • playfile(Enter)
    • Opens the file currently selected with the cursor, if cursor on playing file, open the next file
  • selectfile(RIGHT or LEFT)
    • Selects or unselects the file under the cursor
    • When moving the cursor the selected file will follow, allowing reordering of the playlist
  • unselectfile(no default bind)
    • Unselects the file under the cursor if it was selected
  • closeplaylist(ESC)
    • closes the playlist if it is open

Dynamic keybinds will only work when playlist is visible. There is a setting toggle to change them to static ones. You can override keybindings by their names above by adding the following in your input.conf

SPACE script-binding showplaylist
. However, Dynamic keybindings should be rebound in the settings to avoid overriding other conflicting keybinds and to support multiple keys per bind.

There is also a few script messages you can send to control the script:

KEY script-message playlistmanager command value value2

List of commands, values and their effects:


Value Value2 Effect
show playlist - / duration / toggle show for default duration, show for given seconds, toggle playlist visibility
show filename - / seconds shows stripped filename for default or set seconds
sort startover - Sorts the playlist, any value will start playlist from start on sort
shuffle - - Shuffles the playlist
reverse - - Reverses the playlist
loadfiles - / path - Loads files from playing files dir(default), or specified path
save - - Saves the playlist
playlist-next - - Plays next item in playlist (position of current file saved)
playlist-prev - - Plays previous item in playlist (position of current file saved)


RIGHT playlist-next ; script-message playlistmanager show playlist
Shows the playlist after playlist-next
KEY show-text "Shuffled playlist" ; script-message playlistmanager shuffle
Text message on shuffle

My other mpv scripts

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.