User Scripts

jgreco edited this page Nov 18, 2018 · 286 revisions

User Scripts

Here is a list of scripts that users of mpv have published, adding functionality that is not part of the core mpv player. Most of these scripts are unofficial 3rd party scripts. Anyone can add their own script by editing this wiki. Scripts are usually placed in ~/.config/mpv/scripts/.


  • Blackbox
    Advanced, modular media browser, file manager and playlist manager for mpv.

  • Colorbox
    Apply color correction presets.

  • Gallerizer
    Image gallery autoloader for mpv.

  • Leapfrog
    Effortlessly jump through your playlist, with your own custom jump size and direction, including the ability to jump randomly. Excellent when queuing lots of images and using mpv as an image viewer.

  • mpv-assrt
    Download subtitles from, with interactive OSD menu.

  • other.js
    Automatically save the adjusted volume (other parameters are also OK) to the specified configuration file under the specified path, use other scripts to get the volume value before starting mpv, and pass it to mpv to become the automatic volume function.

  • screenshot-to-clipboard
    Generates a temp screenshot file on desktop then copy to clipboard. (Windows only)

  • seek-show-position
    Shows the position and duration when seeking (formatted as: 00:00 / 120:00)

  • VideoPlayerCode's Modules.js (for developers)
    Tons of pre-written, open source JavaScript modules which helps you rapidly create your own JS user scripts (including a very helpful script config system based on mpv's Lua mp.options API). All modules are free to use (and extend) in your own scripts!

Lua Scripts

  • acompressor
    Dynamic range compressor using acompressor ffmpeg filter with controls to dynamically adjust parameters.

  • audio-balance
    Port of mpv's balance property to FFmpeg lavfi pan filter.

  • audio-file-keys
    Automatically apply key bindings when playing audio files.

  • autocrop
    Automatically crop the video by using lavfi's cropdetect filter to detect black bars.

  • autoloop
    Automatically loops files that are under a given duration (default 5 seconds).

  • autosave
    Periodically saves "watch later" data during playback, rather than only saving on quit.

  • autospeed
    To adjust monitor refresh rate and video speed for almost 1:1 playback. (*nix)

  • autospeedwin
    To adjust monitor refresh rate and video speed for almost 1:1 playback. (Windows)

  • autodeint
    Automatically deinterlace the video by using lavfi's idet filter to detect interlaced content.

  • auto-keep-gui-open
    Intelligently switches mpv's "keep-open" behavior based on whether you are running in video-mode or audio-only mode.

  • autoload
    Automatically load playlist entries before and after the currently playing file, by scanning the directory.

  • auto-profiles
    Automatically apply profiles based on predicates written as Lua expressions.

  • autosub
    Automatically download subtitles using subliminal.

  • betterchapters (update)
    Loads the next or previous playlist entry if there are no more chapters in the seek direction.

  • blackout
    A fast crossplatfrom boss-key, but without window minimization (and possible problems with some VO drivers).

  • blur-edges
    Replace black bars with a blurry copy of the video

  • bookmark
    Record and resume last play in current playing folder

  • boss-key
    UPDATED VERSION. Minimise and pause video at the same time. Windows/Linux. Eliminated the time lag in previous versions.

  • Tcl/Tk context menu
    Configurable context-menu based on Tcl/Tk, for *nix/Windows and probably macOS too.

  • clock
    Constantly show current time on the lower left corner of the video screen.

  • convert_script
    Script to quickly convert and crop videos from within mpv, with a GUI.

  • copy-permalink
    Copy mpv --time=<current-position> <path-playing> to clipboard. Useful for sharing when playing URLs.

  • crop
    Crop the video by defining the target rectangle with the cursor

  • curvesman
    Manipulate color curves filter of FFmpeg with hotkeys. Brighten up color, change color temperature/tone, hopefully more. Adjust yellow light tone to white light tone.

  • cycle-audio-device
    Cycle through available audio devices with key binds.

  • cycle-deinterlace-pullup
    Cycle between deinterlacing, pullup (IVTC), and both filters off.

  • cycle-denoise
    Cycle between lavfi's denoise filters (press n)

  • cycle_messages
    Cycle between custom OSD messages.

  • cycle-video-rotate
    Allows you to perform video rotation which perfectly cycles through all 360 degrees without any glitches.

  • dessubdb
    Download automatically subtitles from the using DESSubdb.

  • delete-file
    Provides the ability to delete files being played through mpv

  • locate-file
    Locate current media file on your OS file browser

  • delogo
    It removes the logo of the channels in a video (press n)

  • deframe
    It removes the frame of youtube videos (press g)

  • drag-to-pan
    Pan the current video or image with the cursor.

  • easycrop
    Manually crop a video during playback.

  • encode
    Re-encode or remux part of the current video. Can also preserve some filters, such as "crop".

  • equalizer
    5-bands equalizer with colorful display.

  • excerpt
    Allows you to quickly create excerpts from media files, you just have to set begin and end markers.

  • fastforward
    Instead of skipping forward in media files, speed up the playback for a few seconds. Playback speed decays back to 1x after a few seconds. Tap rapidly or hold down to go faster.

  • Filenavigator
    Navigate directories and open files from your system.

  • filter-test
    Test mpv/FFmpeg video filter(vf) strings with editable popup dialog.

  • find_subtitles
    (Down)load subtitles with subliminal.

  • firequalizer15
    Linear phase 15-bands equalizer.

  • fix_sub_timing
    Compute the correct speed/delay of subtitles by manually synching two points in time.

  • fpsadjust
    Automatically adjust playback speed to synchronize the video to the display if possible (eg. by adjusting 23.976 Hz to 24 Hz for better compatibility with a 60 Hz display). Obsolete: mpv now has a native display-sync option.

  • fuzzydir
    Allows using wildcards for sub-file-paths and audio-file-paths.

  • gallery-view
    View playlist in a grid view of thumbnails.

  • gpufreq
    Show current and maximum GPU frequencies for GPUs using the DRM stack on Linux.

  • KDialog-open-files
    Use KDE's KDialog to add files to playlist, subtitles to playing video or open URLs.

  • image-viewer
    Configurations, scripts and tips for using mpv as an image viewer.

  • interSubs
    Interactive subtitles. Instantly translate selected word/sentence. Works on Linux, macOS.

  • scrobbler
    Sends the information about playing tracks to, see for more info.

  • live-filters
    Add, remove or toggle ffmpeg video filters during mpv playback.

  • local-language
    Let the text displayed by mpv osd become the language you are most familiar with, that is, language localization, such as 【volume: 100%】 becomes 【音量:100%】.

  • lua-mpris
    Adds mpris support to mpv.

  • mark-chapter
    Temporarily mark the current playback position as a chapter so you can seek to it later. Don't forget to edit input.conf to give it a keybinding.

  • createchapter
    Similar as mark-chapter but with ability to export valid xml file.

  • minesweeper
    Minesweeper game.

  • mpegts-truncate
    Removes beginning of MPEG TS file up to current position without re-writing the whole file.

  • mpv-bookmarker
    Bookmark your favorite time on media files

  • mpv-Change-OSD-Media-Title
    Displays filename, percentage watched, current chapter, and number of frames dropped in the OSD media title and updates it whenever one of the values has changed.

  • mpv_crop_script
    Take cropped screenshots directly within mpv, without the need for external dependencies.

  • mpv_discordRPC
    Discord RPC integration for mpv using lua-discordRPC as base.

  • mpv_discordRPC (alternative version)
    Discord Rich Presence integration for mpv Media Player. Added some features and support: Linux, MacOS and Windows.

  • mpv_frame_info
    Show frame info, similar to ffdshow's OSD.

  • mpv-history
    Simple played media logger. Will generate a mpvhistory.log in the default mpv config folder (%APPDATA%/mpv/ or $HOME/.config/mpv/) in the format [$DATE $TIME] $PATH ($?MEDIA-TITLE). Only tested on Windows.

  • mpv-pdf
    View PDFs in mpv using ImageMagick. Supports: Linux, MacOS

  • mpv_slicing
    Cut uncompressed fragments of the video.

  • mpv_thumbnail_script
    Show preview thumbnails when hovering over the seekbar, without the need for external dependencies.

  • mpv-txt
    Play text files using text-to-speech (TTS). (Works on Linux, MacOS; see Dependencies).

  • mpvcontextmenu
    Comprehensive context-menu forked from Tcl/Tk context menu. Uses other scripts (see Requirements).

  • mpvmenu
    Adds a pop-up menu to mpv, which can be bound to a key or button

  • multi-command-if
    Very powerful conditional logic and multiple action engine for your keybindings, without having to write a single line of code!

  • myshows
    Marks currently watched episode on MyShows website.

  • nextfile
    Force opens next or previous file in the currently playing files folder.

  • notify
    Adds desktop notifications to the mpv media player, which show metadata like artist, album name and track name when the track changes.

  • ontop-playback
    Disables the ontop property when pausing, and enables it again when unpausing the video, if it was disabled. Change it only when the player is not in fullscreen to prevent screen flickering.

  • open-file-dialog
    (Windows) Launches a regular Windows file open dialog for loading videos.

  • osc-style
    Change the mpv osc to a more beautiful and practical look, which is the osc theme feature, a variety of styles to choose from,this is a tutorial and a preview.

  • osd-bar
    Always show osd progress bar, with the more beautiful color matching in the configuration file, you can make the osd progress bar display the current progress at the bottom of the window beautifully,this is a preview.

  • osd-clock
    Periodically shows OSD clock (many configurable options).

  • pause-indicator
    Displays a momentary icon that flashes in the middle of the screen, similar to YouTube.

  • pause-when-minimize
    Pauses the player video when minimizing, and unpauses it when brought up again.

  • peerflix-hook
    Allows streaming of magnet links using peerflix, similar to youtube-dl.

  • pitchcontrol
    Adjusts audio pitch in half-tone steps.

  • Playlistmanager
    Helps with creating playlists, saving them and modifying your current playlist.

  • playlistnoplayback
    If you enable the save play history and progress function, this lua script can solve the problem of automatically jumping to the previous playback progress when playing the next file when playing the playlist, that is, let the playlist always play the next file from the beginning every time. the limitations of this script, please see the comments section in the content.

  • progressbar
    A minimalistic OSC replacement. It provides a small, unintrusive progress bar that persists at the bottom of the video window.

  • quick-scale
    Quickly scale the video player to a target size, with full control over target scale and max scale. Helps you effortlessly resize a video to fit on your desktop, or any other video dimensions you need!

  • redshift_toggle
    Toggle redshift when loading a video file and when reaching the end of said file.

  • reload
    When an online video is stuck during buffering or got slow CDN source, restarting often helps. This script provides automatic reloading of videos that didn't have buffering progress for some time, keeping the current time position. It also adds Ctrl+r keybinding to reload video manually.

  • repl
    A REPL for input commands that is displayed on the video window.

  • rubberband_helper
    rubberband is great for keeping voices intelligible when the video playback is speed up, but it consumes a fair amount of CPU. This script allows you to degrade the audio filter back to scaletempo when playback speeds are high enough to make rubberband pointless. Note: mpv must be built with rubberband support; see mpv --af=rubberband=help

  • save-sub-delay
    This script saves the sub-delay quantity for each file. When next time the file is opened, sub-delay is automatically restored.

  • seek-to
    Seek to an absolute timestamp specified via keyboard input.

  • show-filename
    Show the name of the current playing file.

  • show-stream-title
    Show OSD stream/channel title when switching the IPTV channels from m3u playlist.

  • simple-loader
    (Linux) Browse dirs and files on OSD, and launch them with mpv.

  • simple-mpv-webui
    Web-based remote control.

  • skipchapters
    Automatically skip chapters matching a given list of regular expressions (eg. "OP" or "Opening").

  • skiptofade
    Seeks forward until a black screen appears. Built to skip openings. Uses the lavfi blackdetect filter.

  • SmartCopyPaste
    Powerful copy paste feature. Paste URL or local videos directly to mpv. Bookmark video and time by copying playing videos then paste to access bookmark. Add videos to playlist simply by pasting. Much more explained in the link above.

  • SmartHistory
    Powerful history feature. Log videos you open into %APPDATA%\mpv\mpvHistory.log along with time reached on each video. Optional resume by [ctrl]+[r] for all videos you have played previously and closed before completion (auto bookmark). Immediately find and play last opened video by [ctrl]+[l]. Much more explained in the link above.

  • sopcast
    Adds support for sop:// urls.

  • speed-transition
    Increases playback speed if a subtitle will not be displayed soon. Resumes normal speed just before the subtitle shows up.

  • speed-transition-Audio
    Experiment similar to speed-transition. changes playback speed based on volume thresholds.

  • subit
    Yet another script for downloading subtitles using subliminal. Supports better customization of options, such as easy language selection, authentication for providers that need it, and support for URLs.

  • subselect Tk
    Download subtitles with a GUI - select the one you want and automatically load them up in mpv. Supports searching for arbitrary names and different subtitle languages. Works on Windows and Linux, possibly macOS.

  • sub-cut
    Extract a part of the video as audio or video with subtitles.

  • sub-bilingual
    Generate bilingual subtitles.

  • sub-bookmarks
    Save current position and subtitles in .txt file.

  • sub-export
    Extract selected subtitles from .mkv file.

  • sub-playback
    Add interactive move, i.e. automatically pause at the end of the fragment with option to continue playback or replay it again with or without subtitles.

  • sub-replay
    Replay previous sentence.

  • sub-search
    Search for phrase in subtitles and skip to it.

  • sub-sentences
    Generate subtitles with sentences.

  • sub-voracious
    Reading and listening practice.

  • subs2srs
    Automatically add new card in Anki with audio, picture and text.

  • stats
    Display some statistics about the currently played file on-screen.

  • streamcache
    Provides for more network-glitch-robust caching of live streams by adjusting replay speed.

  • time
    Shows the current time or the time at which playback will end.

  • timer
    Allows the user to set a starting time and an ending time and see the time elapsed between those points with millisecond precision.

  • tree-profiles
    Automatically apply profiles to certain directories or files.

  • total_playtime
    Shows total playtime of current playlist.

  • trueautosub
    Improved fork of autosub, Automatically downloads subtitles if not present using subliminal. (osx/linux only)

  • tv-output
    (Linux) TV output handling - activate on mpv playback and deactivate on mpv shutdown.

  • unseen-playlistmaker
    Keeps track of watched files locally, and creates playlists of unwatched files.

  • visualizer
    Various audio visualization.

  • vo_battery
    (Linux) Choose the VO based on if the laptop is on battery or not.

  • webm
    Simple WebM maker for mpv, with no external dependencies.

  • xrandr
    Automatically sets the display refresh rate to the one best suitable for the video played

  • youtube-quality
    A menu for changing youtube video quality (ytdl-format) on the fly, as though you were using the web player.

  • zones
    Handles commands depending on where the mouse pointer is at, mostly for mouse wheel handling.

  • addfile
    (OS X) Add subtitle or audio track to playing video file

If you want to write your own Lua scripts, have a look at the documentation of mpv's Lua interface.

User Shaders

  • LumaSharpenHook
    A sharpen filter similar to using Unsharp Mask in Photoshop ported from SweetFX shader pack.

  • SSimDownscaler, SSimSuperRes, Krig, Adaptive Sharpen, etc.

    • SSimDownscaler: Perceptually based downscaler. More information is here.
    • SSimSuperRes: The aim of this shader is to make corrections to the image upscaled by mpv built-in scaler (removes ringing artifacts, restores original sharpness, etc).
    • Krig: Chroma scaler that uses luma information for high quality upscaling.
  • Noise
    Simplistic filter that adds a tunable amount of uniform white noise to the output.

  • Film Grain v1 and Film Grain v2. Two configurable shaders for applying gaussian-weighted white noise to the image. v2 is a smoothed version of v1, which uses an extra gaussian blur pass to shift the grain frequency spectrum. Both versions can trivially be adapted to add film grain to other channels besides LUMA by just adding it to the list of hooks.

  • Antiringing
    This is an antiringing filter that works by clamping to the local neighbourhood. Sort of inspired by the mpv built-in antiringing algorithm, but it's extended in such a way that it also works well for polar (EWA) filters, which the mpv built-in algorithm does not support at all.

  • nnedi3, superxbr and ravu
    User shaders for prescaling. These shaders should cover most functionality that prescale-luma= used to provide.

    Prescaler based on layered convolutional networks.

  • un360
    Converts equirectangular 360 degree video to be watchable, at a fixed perspective.

VapourSynth Scripts

  • mvtools
    Use MVTools's BlockFPS function to perform motion interpolation on the video in realtime.

  • nnedi3
    Use NNEDI3 to double the resolution of the video. This always performs a single doubling. Note that the vapoursynth-nnedi3 filter is so slow that this practically can't be used in realtime, so it's not much use in practice.

  • flash3kyuu
    Use flash3kyuu to deband the video, with reasonable (mildly grainy) default settings. Obsolete: mpv now ships with a similar debanding filter as shader.

C Plugins


  • play-with
    A WebExtension that can open a video stream on a web page with an external player.

  • playphrase
    Search and play phrases from movies and audiobooks.

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.