916 lines
No EOL
75 KiB
Markdown
916 lines
No EOL
75 KiB
Markdown
---
|
|
obj: application
|
|
website: https://mpv.io
|
|
flatpak-id: io.mpv.Mpv
|
|
---
|
|
|
|
# MPV
|
|
mpv is a based media player. It supports a wide variety of video [file formats](../../files/MIME.md), audio and video codecs, and subtitle types. Special input [URL](../../internet/URL.md) types are available to read input from a variety of sources other than disk files. Depending on platform, a variety of different video and audio output methods are supported.
|
|
|
|
## Usage
|
|
Usage: `mpv [options] [file|URL|PLAYLIST|-]`
|
|
|
|
## Default Input
|
|
| Input | Action |
|
|
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `LEFT` and `RIGHT` | Seek backward/forward 5 seconds. Shift+arrow does a 1 second exact seek. |
|
|
| `UP` and `DOWN` | Seek forward/backward 1 minute. Shift+arrow does a 5 second exact seek. |
|
|
| `Ctrl+LEFT` and `Ctrl+RIGHT` | Seek to the previous/next subtitle. Subject to some restrictions and might not always work |
|
|
| `Ctrl+Shift+LEFT` and `Ctrl+Shift+RIGHT` | Adjust subtitle delay so that the next or previous subtitle is displayed now. This is especially useful to sync subtitles to audio. |
|
|
| `[` and `]` | Decrease/increase current playback speed by 10%. |
|
|
| `{` and `}` | Halve/double current playback speed. |
|
|
| `BACKSPACE` | Reset playback speed to normal. |
|
|
| `Shift+BACKSPACE` | Undo the last seek. This works only if the playlist entry was not changed. Hitting it a second time will go back to the original position. |
|
|
| `Shift+Ctrl+BACKSPACE` | Mark the current position. This will then be used by Shift+BACKSPACE as revert position (once you seek back, the marker will be reset). You can use this to seek around in the file and then return to the exact position where you left off. |
|
|
| `<` and `>` | Go backward/forward in the playlist. |
|
|
| `ENTER` | Go forward in the playlist. |
|
|
| `p` and `SPACE` | Pause (pressing again unpauses). |
|
|
| `.` | Step forward. Pressing once will pause, every consecutive press will play one frame and then go into pause mode again. |
|
|
| `,` | Step backward. Pressing once will pause, every consecutive press will play one frame in reverse and then go into pause mode again. |
|
|
| `q` | Stop playing and quit. |
|
|
| `Q` | Like q, but store the current playback position. Playing the same file later will resume at the old playback position if possible. |
|
|
| `/` and `*` | Decrease/increase volume. |
|
|
| `9` and `0` | Decrease/increase volume. |
|
|
| `m` | Mute sound. |
|
|
| `_` | Cycle through the available video tracks. |
|
|
| `#` | Cycle through the available audio tracks. |
|
|
| `E` | Cycle through the available Editions. |
|
|
| `f` | Toggle fullscreen |
|
|
| `ESC` | Exit fullscreen mode. |
|
|
| `T` | Toggle stay-on-top (see also --ontop). |
|
|
| `o` and `P` | Show progression bar, elapsed time and total duration on the OSD. |
|
|
| `O` | Toggle OSD states between normal and playback time/duration. |
|
|
| `v` | Toggle subtitle visibility. |
|
|
| `j` and `J` | Cycle through the available subtitles. |
|
|
| `z` and `Z` | Adjust subtitle delay by +/- 0.1 seconds. |
|
|
| `l` | Set/clear A-B loop points. See ab-loop command for details. |
|
|
| `L` | Toggle infinite looping. |
|
|
| `Ctrl++` and `Ctrl+-` | Adjust audio delay (A/V sync) by +/- 0.1 seconds. |
|
|
| `Shift+g` and `Shift+f` | Adjust subtitle font size by +/- 10%. |
|
|
| `r` and `R` | Move subtitles up/down. |
|
|
| `s` | Take a screenshot. |
|
|
| `S` | Take a screenshot, without subtitles. |
|
|
| `Ctrl+s` | Take a screenshot, as the window shows it (with subtitles, OSD, and scaled video). |
|
|
| `PGUP` and `PGDWN` | Seek to the beginning of the previous/next chapter. In most cases, "previous" will actually go to the beginning of the current chapter. |
|
|
| `Alt+LEFT`, `Alt+RIGHT`, `Alt+UP`, `Alt+DOWN` | Move the video rectangle (panning). |
|
|
| `Alt++` and `Alt+-` | Combining `Alt` with the `+` or `-` keys changes video zoom. |
|
|
| `Alt+BACKSPACE` | Reset the pan/zoom settings. |
|
|
| `F8` | Show the playlist and the current position in it (useful only if a UI window is used, broken on the terminal). |
|
|
| `F9` | Show the list of audio and subtitle streams (useful only if a UI window is used, broken on the terminal). |
|
|
| `i` and `I` | Show/toggle an overlay displaying statistics about the currently playing file such as codec, framerate, number of dropped frames and so on. |
|
|
| `DEL` | Cycle OSC visibility between never / auto (mouse-move) / always |
|
|
| \` | Show the console. (`ESC` closes it again) |
|
|
| `1` and `2` | Adjust contrast. |
|
|
| `3` and `4` | Adjust brightness. |
|
|
| `5` and `6` | Adjust gamma. |
|
|
| `7` and `8` | Adjust saturation. |
|
|
|
|
## Options
|
|
### Track Selection
|
|
- `--alang=<languagecode[,languagecode,...]>`
|
|
Specify a priority list of audio languages to use, as IETF language tags. Equivalent ISO 639-1 two-letter and ISO 639-2 three-letter codes are treated the same. The first tag in the list whose language matches a track in the file will be used.
|
|
- `--slang=<languagecode[,languagecode,...]>`
|
|
Equivalent to `--alang`, for subtitle tracks.
|
|
- `--vlang=<...>`
|
|
Equivalent to `--alang` and `--slang`, for video tracks.
|
|
- `--aid=<ID|auto|no>`
|
|
Select audio track. `auto` selects the default, `no` disables audio. See also `--alang`. mpv normally prints available audio tracks on the terminal when starting playback of a file.
|
|
`--audio` is an alias for `--aid`.
|
|
- `--sid=<ID|auto|no>`
|
|
Display the subtitle stream specified by `<ID>`. `auto` selects the default, `no` disables subtitles.
|
|
`--sub` is an alias for `--sid`.
|
|
- `--vid=<ID|auto|no>`
|
|
Select video channel. `auto` selects the default, `no` disables video.
|
|
`--video` is an alias for `--vid`.
|
|
|
|
### Playback Control
|
|
- `--start=<relative time>`
|
|
Seek to given time position.
|
|
|
|
The general format for times is `[+|-][[hh:]mm:]ss[.ms]`. If the time is prefixed with `-`, the time is considered relative from the end of the file (as signaled by the demuxer/the file). A `+` is usually ignored.
|
|
|
|
The following alternative time specifications are recognized:
|
|
- `pp%` seeks to percent position pp (0-100).
|
|
- `#c` seeks to chapter number `c`. (Chapters start from 1.)
|
|
- `none` resets any previously set option (useful for libmpv).
|
|
- `--end=<relative time>`
|
|
Stop at given time. Use `--length` if the time should be relative to `--start`. See `--start` for valid option values and examples.
|
|
- `--length=<relative time>`
|
|
Stop after a given time relative to the start time. See `--start` for valid option values and examples.
|
|
If both `--end` and `--length` are provided, playback will stop when it reaches either of the two endpoints.
|
|
- `--speed=<0.01-100>`
|
|
Slow down or speed up playback by the factor given as parameter.
|
|
If `--audio-pitch-correction` (on by default) is used, playing with a speed higher than normal automatically inserts the `scaletempo2` audio filter.
|
|
- `--pause`
|
|
Start the player in paused state.
|
|
- `--shuffle`
|
|
Play files in random order.
|
|
- `--playlist-start=<auto|index>`
|
|
Set which file on the internal playlist to start playback with. The index is an integer, with 0 meaning the first file. The value auto means that the selection of the entry to play is left to the playback resume mechanism (default).
|
|
- `--loop-playlist=<N|inf|force|no>, --loop-playlist`
|
|
Loops playback `N` times. A value of 1 plays it one time (default), 2 two times, etc. `inf` means forever. `no` is the same as 1 and disables looping. If several files are specified on command line, the entire playlist is looped. `--loop-playlist` is the same as `--loop-playlist=inf`.
|
|
- `--loop-file=<N|inf|no>, --loop=<N|inf|no>`
|
|
Loop a single file `N` times. `inf` means forever, `no` means normal playback. For compatibility, `--loop-file` and `--loop-file=yes` are also accepted, and are the same as `--loop-file=inf`.
|
|
|
|
The difference to `--loop-playlist` is that this doesn't loop the playlist, just the file itself. If the playlist contains only a single file, the difference between the two option is that this option performs a seek on loop, instead of reloading the file.
|
|
- `--ab-loop-a=<time>, --ab-loop-b=<time>`
|
|
Set loop points. If playback passes the b timestamp, it will seek to the a timestamp. Seeking past the b point doesn't loop (this is intentional).
|
|
|
|
If a is after b, the behavior is as if the points were given in the right order, and the player will seek to b after crossing through a. This is different from old behavior, where looping was disabled (and as a bug, looped back to a on the end of the file).
|
|
- `--ab-loop-count=<N|inf>`
|
|
Run A-B loops only `N` times, then ignore the A-B loop points (default: `inf`). Every finished loop iteration will decrement this option by 1 (unless it is set to `inf` or 0). `inf` means that looping goes on forever. If this option is set to 0, A-B looping is ignored, and even the ab-loop command will not enable looping again
|
|
- `--play-direction=<forward|+|backward|->`
|
|
Control the playback direction (default: `forward`). Setting `backward` will attempt to play the file in reverse direction, with decreasing playback time. If this is set on playback starts, playback will start from the end of the file. If this is changed at during playback, a hr-seek will be issued to change the direction.
|
|
|
|
`+` and `-` are aliases for forward and backward.
|
|
|
|
### Program Behaviour
|
|
- `--no-config`
|
|
Do not load default configuration or any user files. This prevents loading of both the user-level and system-wide `mpv.conf` and `input.conf` files.
|
|
- `--list-options`
|
|
Prints all available options.
|
|
- `--list-properties`
|
|
Print a list of the available properties.
|
|
- `--list-protocols`
|
|
Print a list of the supported protocols.
|
|
- `--idle=<no|yes|once>`
|
|
Makes mpv wait idly instead of quitting when there is no file to play. Mostly useful in input mode, where mpv can be controlled through input commands. (Default: `no`)
|
|
- `--include=<configuration-file>`
|
|
Specify configuration file to be parsed after the default ones.
|
|
- `--load-scripts=<yes|no>`
|
|
If set to `no`, don't auto-load scripts from the scripts configuration subdirectory
|
|
- `--script=<filename>, --scripts=file1.lua:file2.lua:...`
|
|
Load a Lua script. The second option allows you to load multiple scripts by separating them with the path separator (`:` on Unix, `;` on [Windows](../../windows/Windows.md)).
|
|
- `--profile=<profile1,profile2,...>`
|
|
Use the given profile(s), `--profile=help` displays a list of the defined profiles.
|
|
- `--show-profile=<profile>`
|
|
Show the description and content of a profile. Lists all profiles if no parameter is provided.
|
|
- `--ytdl-format=<ytdl|best|worst|mp4|webm|...>`
|
|
Video format/quality that is directly passed to youtube-dl.
|
|
- `--ytdl-raw-options=<key>=<value>[,<key>=<value>[,...]]`
|
|
Pass arbitrary options to youtube-dl.
|
|
|
|
### Video
|
|
- `--vf=<filter1[=parameter1:parameter2:...],filter2,...>`
|
|
Specify a list of video filters to apply to the video stream. See VIDEO FILTERS for details and descriptions of the available filters. The option variants `--vf-add`, `--vf-pre`, and `--vf-clr` exist to modify a previously specified list, but you should not need these for typical use.
|
|
- `--video-aspect-override=<ratio|no>`
|
|
Override video aspect ratio, in case aspect information is incorrect or missing in the file being played.
|
|
- `--video-pan-x=<value>, --video-pan-y=<value>`
|
|
Moves the displayed video rectangle by the given value in the X or Y direction. The unit is in fractions of the size of the scaled video (the full size, even if parts of the video are not visible due to panscan or other options).
|
|
- `--video-rotate=<0-359|no>`
|
|
Rotate the video clockwise, in degrees. If `no` is given, the video is never rotated, even if the file has rotation metadata. (The rotation value is added to the rotation metadata, which means the value 0 would rotate the video according to the rotation metadata.)
|
|
- `--video-crop=<[W[xH]][+x+y]>, --video-crop=<x:y>`
|
|
Crop the video by starting at the x, y offset for w, h pixels. The crop is applied to the source video rectangle (before anamorphic stretch) by the VO. A crop rectangle that is not within the video rectangle will be ignored.
|
|
- `--video-zoom=<value>`
|
|
Adjust the video display scale factor by the given value. The parameter is given log 2. For example, `--video-zoom=0` is unscaled, `--video-zoom=1` is twice the size, `--video-zoom=-2` is one fourth of the size, and so on.
|
|
- `--video-scale-x=<value>, --video-scale-y=<value>`
|
|
Multiply the video display size with the given value (default: 1.0). If a non-default value is used, this will be different from the window size, so video will be either cut off, or black bars are added.
|
|
- `--video-align-x=<-1-1>, --video-align-y=<-1-1>`
|
|
Moves the video rectangle within the black borders, which are usually added to pad the video to screen if video and screen aspect ratios are different. `--video-align-y=-1` would move the video to the top of the screen (leaving a border only on the bottom), a value of 0 centers it (default), and a value of 1 would put the video at the bottom of the screen.
|
|
- `--video-margin-ratio-left=<val>, --video-margin-ratio-right=<val>, --video-margin-ratio-top=<val>, --video-margin-ratio-bottom=<val>`
|
|
Set extra video margins on each border (default: 0). Each value is a ratio of the window size, using a range 0.0-1.0. For example, setting the option `--video-margin-ratio-right=0.2` at a window size of 1000 pixels will add a 200 pixels border on the right side of the window.
|
|
|
|
The video is "boxed" by these margins. The window size is not changed. In particular it does not enlarge the window, and the margins will cause the video to be downscaled by default. This may or may not change in the future.
|
|
- `--frames=<number>`
|
|
Play/convert only first `<number>` video frames, then quit.
|
|
|
|
### Audio
|
|
- `--audio-pitch-correction=<yes|no>`
|
|
If this is enabled (default), playing with a speed different from normal automatically inserts the `scaletempo2` audio filter.
|
|
- `--audio-device=<name>`
|
|
Use the given audio device. This consists of the audio output name, e.g. alsa, followed by /, followed by the audio output specific device name. The default value for this option is `auto`, which tries every audio output in preference order with the default device.
|
|
|
|
You can list audio devices with `--audio-device=help`. This outputs the device name in quotes, followed by a description. The device name is what you have to pass to the `--audio-device` option.
|
|
- `--af=<filter1[=parameter1:parameter2:...],filter2,...>`
|
|
Specify a list of audio filters to apply to the audio stream.
|
|
- `--volume=<value>`
|
|
Set the startup volume. 0 means silence, 100 means no volume reduction or amplification. Negative values can be passed for compatibility, but are treated as 0.
|
|
- `--audio-delay=<sec>`
|
|
Audio delay in seconds (positive or negative float value). Positive values delay the audio, and negative values delay the video.
|
|
- `--mute=<yes|no|auto>`
|
|
Set startup audio mute status (default: `no`).
|
|
- `--audio-files=<files>`
|
|
Play audio from an external file while viewing a video.
|
|
- `--audio-file=<file>`
|
|
CLI/config file only alias for `--audio-files-append`. Each use of this option will add a new audio track. The details are similar to how `--sub-file` works.
|
|
|
|
### Subtitles
|
|
- `--sub-delay=<sec>`
|
|
Delays subtitles by `<sec>` seconds. Can be negative.
|
|
- `--sub-files=<file-list>, --sub-file=<filename>`
|
|
Add a subtitle file to the list of external subtitles.
|
|
|
|
If you use `--sub-file` only once, this subtitle file is displayed by default.
|
|
|
|
If `--sub-file` is used multiple times, the subtitle to use can be switched at runtime by cycling subtitle tracks. It's possible to show two subtitles at once: use `--sid` to select the first subtitle index, and `--secondary-sid` to select the second index. (The index is printed on the terminal output after the `--sid=` in the list of streams.)
|
|
- `--secondary-sid=<ID|auto|no>`
|
|
Select a secondary subtitle stream. This is similar to `--sid`. If a secondary subtitle is selected, it will be rendered as toptitle (i.e. on the top of the screen) alongside the normal subtitle, and provides a way to render two subtitles at once.
|
|
- `--sub-scale=<0-100>`
|
|
Factor for the text subtitle font size (default: 1).
|
|
This affects ASS subtitles as well, and may lead to incorrect subtitle rendering. Use with care, or use `--sub-font-size` instead.
|
|
- `--sub-pos=<0-150>`
|
|
Specify the position of subtitles on the screen. The value is the vertical position of the subtitle in % of the screen height. 100 is the original position, which is often not the absolute bottom of the screen, but with some margin between the bottom and the subtitle. Values above 100 move the subtitle further down.
|
|
- `--sub-speed=<0.1-10.0>`
|
|
Multiply the subtitle event timestamps with the given value. Can be used to fix the playback speed for frame-based subtitle formats. Affects text subtitles only.
|
|
- `--sub-fix-timing=<yes|no>`
|
|
Adjust subtitle timing is to remove minor gaps or overlaps between subtitles (if the difference is smaller than 210 ms, the gap or overlap is removed).
|
|
- `--sub-font-size=<size>`
|
|
Specify the sub font size. The unit is the size in scaled pixels at a window height of 720. The actual pixel size is scaled with the window height: if the window height is larger or smaller than 720, the actual size of the text increases or decreases as well.
|
|
- `--sub-shadow-offset=<size>`
|
|
Displacement of the sub text shadow in scaled pixels (see --sub-font-size for details). A value of 0 disables shadows.
|
|
|
|
### Window
|
|
- `--title=<string>`
|
|
Set the window title. This is used for the video window, and if possible, also sets the audio stream title. Properties are expanded.
|
|
- `--screen=<default|0-32>`
|
|
In multi-monitor configurations (i.e. a single desktop that spans across multiple displays), this option tells mpv which screen to display the video on.
|
|
- `--fullscreen, --fs`
|
|
Fullscreen playback.
|
|
- `--keep-open=<yes|no|always>`
|
|
Do not terminate when playing or seeking beyond the end of the file, and there is no next file to be played (and `--loop` is not used). Instead, pause the player. When trying to seek beyond end of the file, the player will attempt to seek to the last frame.
|
|
- `--image-display-duration=<seconds|inf>`
|
|
If the current file is an image, play the image for the given amount of seconds (default: 1). `inf` means the file is kept open forever (until the user stops playback manually).
|
|
- `--ontop`
|
|
Makes the player window stay on top of other windows.
|
|
On [Windows](../../windows/Windows.md), if combined with fullscreen mode, this causes mpv to be treated as exclusive fullscreen window that bypasses the Desktop Window Manager.
|
|
- `--geometry=<[W[xH]][+-x+-y][/WS]>, --geometry=<x:y>`
|
|
Adjust the initial window position or size. `W` and `H` set the window size in pixels. `x` and `y` set the window position, measured in pixels from the top-left corner of the screen to the top-left corner of the image being displayed. If a percentage sign (`%`) is given after the argument, it turns the value into a percentage of the screen size in that direction.
|
|
- `--autofit=<[W[xH]]>`
|
|
Set the initial window size to a maximum size specified by `WxH`, without changing the window's aspect ratio. The size is measured in pixels, or if a number is followed by a percentage sign (`%`) in percents of the screen size.
|
|
- `--window-scale=<factor>`
|
|
Resize the video window to a multiple (or fraction) of the video size. This option is applied before `--autofit` and other options are applied (so they override this option).
|
|
- `--auto-window-resize=<yes|no>`
|
|
By default, mpv will automatically resize itself if the video's size changes (i.e. advancing forward in a playlist). Setting this to no disables this behavior so the window size never changes automatically.
|
|
|
|
### Equalizer
|
|
- `--brightness=<-100-100>`
|
|
Adjust the brightness of the video signal (default: 0). Not supported by all video output drivers.
|
|
- `--contrast=<-100-100>`
|
|
Adjust the contrast of the video signal (default: 0). Not supported by all video output drivers.
|
|
- `--saturation=<-100-100>`
|
|
Adjust the saturation of the video signal (default: 0). You can get grayscale output with this option. Not supported by all video output drivers.
|
|
- `--gamma=<-100-100>`
|
|
Adjust the gamma of the video signal (default: 0). Not supported by all video output drivers.
|
|
- `--hue=<-100-100>`
|
|
Adjust the hue of the video signal (default: 0). You can get a colored negative of the image with this option. Not supported by all video output drivers.
|
|
|
|
### Demuxer
|
|
- `--directory-mode=<auto|lazy|recursive|ignore>`
|
|
When opening a directory, open subdirectories lazily, recursively or not at all. The default is `auto`, which behaves like `recursive` with `--shuffle`, and like `lazy` otherwise.
|
|
|
|
### Input
|
|
- `--input-conf=<filename>`
|
|
Specify input configuration file other than the default location in the mpv configuration directory (usually `~/.config/mpv/input.conf`).
|
|
- `--input-keylist`
|
|
Prints all keys that can be bound to commands.
|
|
- `--input-gamepad=<yes|no>`
|
|
Enable/disable SDL2 Gamepad support. Disabled by default.
|
|
|
|
### On Screen Controller
|
|
- `--osc, --no-osc`
|
|
Whether to load the on-screen-controller (default: yes).
|
|
- `--no-osd-bar, --osd-bar`
|
|
Disable display of the OSD bar.
|
|
- `--osd-font-size=<size>`
|
|
Specify the OSD font size. See `--sub-font-size` for details.
|
|
|
|
### Screenshot
|
|
- `--screenshot-format=<type>`
|
|
Set the image file type used for saving screenshots.
|
|
|
|
Available choices:
|
|
- `png`: [PNG](../../files/media/image/PNG.md)
|
|
- `jpg`: JPEG (default)
|
|
- `jpeg`: JPEG (alias for jpg)
|
|
- `webp`: WebP
|
|
- `jxl`: JPEG XL
|
|
- `avif`: [AVIF](../../files/media/image/AVIF.md)
|
|
- `--screenshot-template=<template>`
|
|
Specify the filename template used to save screenshots. The template specifies the filename without file extension, and can contain format specifiers, which will be substituted when taking a screenshot. By default, the template is `mpv-shot%n`, which results in filenames like `mpv-shot0012.png` for example.
|
|
|
|
The template can start with a relative or absolute path, in order to specify a directory location where screenshots should be saved.
|
|
|
|
Allowed format specifiers:
|
|
|
|
| Format | Description |
|
|
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `%[#][0X]n` | A sequence number, padded with zeros to length X (default: 04). E.g. passing the format %04n will yield 0012 on the 12th screenshot. The number is incremented every time a screenshot is taken or if the file already exists. The length X must be in the range 0-9. With the optional # sign, mpv will use the lowest available number. For example, if you take three screenshots--0001, 0002, 0003--and delete the first two, the next two screenshots will not be 0004 and 0005, but 0001 and 0002 again. |
|
|
| `%f` | Filename of the currently played video. |
|
|
| `%F` | Same as %f, but strip the file extension, including the dot. |
|
|
| `%x` | Directory path of the currently played video. If the video is not on the filesystem (but e.g. `http://`), this expand to an empty string. |
|
|
| `%X{fallback}` | Same as `%x`, but if the video file is not on the filesystem, return the fallback string inside the `{...}`. |
|
|
| `%p` | Current playback time, in the same format as used in the OSD. The result is a string of the form `HH:MM:SS`. For example, if the video is at the time position 5 minutes and 34 seconds, `%p` will be replaced with `00:05:34`. |
|
|
| `%P` | Similar to `%p`, but extended with the playback time in milliseconds. It is formatted as `HH:MM:SS.mmm`, with `mmm` being the millisecond part of the playback time. |
|
|
| `%wX` | Specify the current playback time using the format string `X`. `%p` is like `%wH:%wM:%wS`, and `%P` is like `%wH:%wM:%wS.%wT`.<br>Valid format specifiers:<br>- `%wH`: hour (padded with 0 to two digits)<br>- `%wh`: hour (not padded)<br>- `%wM`: minutes (00-59)<br>- `%wm`: total minutes (includes hours, unlike %wM)<br>- `%wS`: seconds (00-59)<br>- `%ws`: total seconds (includes hours and minutes)<br>- `%wf`: like %ws, but as float<br>- `%wT`: milliseconds (000-999) |
|
|
| `%tX` | Specify the current local date/time using the format `X`. This format specifier uses the UNIX `strftime()` function internally, and inserts the result of passing `%X` to `strftime`. For example, `%tm` will insert the number of the current month as number. You have to use multiple `%tX` specifiers to build a full date/time string. |
|
|
| `%%` | Replaced with the % character itself. |
|
|
- `--screenshot-dir=<path>`
|
|
Store screenshots in this directory. This path is joined with the filename generated by `--screenshot-template`. If the template filename is already absolute, the directory is ignored.
|
|
If the directory does not exist, it is created on the first screenshot. If it is not a directory, an error is generated when trying to write a screenshot.
|
|
|
|
### Cache
|
|
- `--cache=<yes|no|auto>`
|
|
Decide whether to use network cache settings (default: `auto`).
|
|
- `--cache-secs=<seconds>`
|
|
How many seconds of audio/video to prefetch if the cache is active.
|
|
|
|
### Network
|
|
- `--user-agent=<string>`
|
|
Use `<string>` as user agent for [HTTP](../../internet/HTTP.md) streaming.
|
|
- `--cookies, --no-cookies`
|
|
Support cookies when making [HTTP](../../internet/HTTP.md) requests. Disabled by default.
|
|
- `--cookies-file=<filename>`
|
|
Read [HTTP](../../internet/HTTP.md) [cookies](../../internet/Cookie.md) from `<filename>`. The file is assumed to be in Netscape format.
|
|
- `--http-header-fields=<field1,field2>`
|
|
Set custom [HTTP](../../internet/HTTP.md) fields when accessing [HTTP](../../internet/HTTP.md) stream.
|
|
- `--http-proxy=<proxy>`
|
|
[URL](../../internet/URL.md) of the [HTTP](../../internet/HTTP.md)/HTTPS proxy. If this is set, the `http_proxy` environment is ignored. The `no_proxy` environment variable is still respected. This option is silently ignored if it does not start with `http://`. Proxies are not used for https URLs. Setting this option does not try to make the ytdl script use the proxy.
|
|
|
|
## Video Filters
|
|
To see a list of all available video filters: `mpv -vf=help`
|
|
|
|
### crop
|
|
Crop the video
|
|
Usage: `mpv -vf=crop=<out_w>:<out_h>:<x>:<y>:<keep_aspect>:<exact>`
|
|
|
|
#### Options
|
|
| Option | Description |
|
|
| ------------- | ----------------------------------- |
|
|
| `out_w` | set the width crop area expression |
|
|
| `out_h` | set the height crop area expression |
|
|
| `x` | set the x crop area expression |
|
|
| `y` | set the y crop area expression |
|
|
| `keep_aspect` | keep aspect ratio |
|
|
| `exact` | do exact cropping |
|
|
|
|
### drawbox
|
|
Draw a colored box on the input video.
|
|
Usage: `mpv -vf=drawbox=<x>:<w>:<width>:<height>:<color>:<thickness>:<replace>:<box_source>`
|
|
|
|
#### Options
|
|
| Option | Description |
|
|
| ------------ | -------------------------------------------- |
|
|
| `x` | set horizontal position of the left box edge |
|
|
| `y` | set vertical position of the top box edge |
|
|
| `width` | set width of the box |
|
|
| `height` | set height of the box |
|
|
| `color` | set color of the box |
|
|
| `thickness` | set the box thickness |
|
|
| `replace` | replace color & alpha |
|
|
| `box_source` | use datas from bounding box in side data |
|
|
|
|
### eq
|
|
Adjust brightness, contrast, gamma, and saturation.
|
|
Usage: `mpv -vf=eq=<contrast>:<brightness>:<saturation>:<gamma>:<gamma_r>:<gamma_g>:<gamma_b>:<gamma_weight>`
|
|
|
|
#### Options
|
|
| Option | Description |
|
|
| -------------- | ---------------------------------------------------------------------- |
|
|
| `contrast` | set the contrast adjustment, negative values give a negative image |
|
|
| `brightness` | set the brightness adjustment |
|
|
| `saturation` | set the saturation adjustment |
|
|
| `gamma` | set the initial gamma value |
|
|
| `gamma_r` | gamma value for red |
|
|
| `gamma_g` | gamma value for green |
|
|
| `gamma_b` | gamma value for blue |
|
|
| `gamma_weight` | set the gamma weight which reduces the effect of gamma on bright areas |
|
|
|
|
### framerate
|
|
Upsamples or downsamples progressive source between specified frame rates.
|
|
Usage: `mpv -vf=framerate=<fps>`
|
|
|
|
### framestep
|
|
Select one frame every N frames.
|
|
Usage: `mpv -vf=framestep=<step>`
|
|
|
|
### gblur
|
|
Apply Gaussian Blur filter.
|
|
Usage: `mpv -vf=gblur=<sigma>:<steps>:<planes>:<sigmaV>`
|
|
|
|
#### Options
|
|
| Option | Description |
|
|
| -------- | -------------------- |
|
|
| `sigma` | set sigma |
|
|
| `steps` | set number of steps |
|
|
| `planes` | set planes to filter |
|
|
| `sigmaV` | set vertical sigma |
|
|
|
|
### hflip
|
|
Horizontally flip the input video.
|
|
Usage: `mpv -vf=hflip`
|
|
|
|
### vflip
|
|
Flip the input video vertically.
|
|
Usage: `mpv -vf=vflip`
|
|
|
|
### pixelize
|
|
Pixelize video.
|
|
Usage: `mpv -vf=pixelize=<width>:<height>`
|
|
|
|
### rotate
|
|
Rotate the input image.
|
|
Usage: `mpv -vf=rotate=<angle>:<out_w>:<out_h>:<fillcolor>:<bilinear>`
|
|
|
|
#### Options
|
|
| Option | Description |
|
|
| ----------- | ---------------------------- |
|
|
| `angle` | set angle (in radians) |
|
|
| `out_w` | set output width expression |
|
|
| `out_h` | set output height expression |
|
|
| `fillcolor` | set background fill color |
|
|
| `bilinear` | use bilinear interpolation |
|
|
|
|
### scale
|
|
Scale the input video size and/or convert the image format.
|
|
Usage: `mpv -vf=scale=<w>:<h>`
|
|
|
|
### swaprect
|
|
Swap 2 rectangular objects in video.
|
|
Usage: `mpv -vf=swaprect=<w>:<h>:<x1>:<y1>:<x2>:<y2>`
|
|
|
|
#### Options
|
|
| Option | Description |
|
|
| ------ | ---------------------------------- |
|
|
| `w` | set rect width |
|
|
| `h` | set rect height |
|
|
| `x1` | set 1st rect x top left coordinate |
|
|
| `y1` | set 1st rect y top left coordinate |
|
|
| `x2` | set 2nd rect x top left coordinate |
|
|
| `y2` | set 2nd rect y top left coordinate |
|
|
|
|
## Audio Filters
|
|
To see a list of all available audio filters: `mpv -af=help`
|
|
|
|
### volume
|
|
Change input volume.
|
|
Usage: `mpv -af=volume=<volume>`
|
|
|
|
## Encoding
|
|
You can encode files from one format/codec to another using this facility. This is useful if you want to apply filters to a file.
|
|
|
|
- `--o=<filename>`
|
|
Enables encoding mode and specifies the output file name.
|
|
- `--of=<format>`
|
|
Specifies the output format (overrides autodetection by the file name extension of the file specified by `-o`). See `--of=help` for a full list of supported formats.
|
|
- `--oac=<codec>`
|
|
Specifies the output audio codec. See `--oac=help` for a full list of supported codecs.
|
|
- `--oacopts=<options>`
|
|
Specifies the output audio codec options for libavcodec. See `--oacopts=help` for a full list of supported options.
|
|
Example:
|
|
```
|
|
# selects 128 kbps MP3 encoding.
|
|
--oac=libmp3lame --oacopts=b=128000
|
|
```
|
|
- `--ovc=<codec>`
|
|
Specifies the output video codec. See `--ovc=help` for a full list of supported codecs.
|
|
- `--ovcopts=<options>`
|
|
Specifies the output video codec options for libavcodec. See `--ovcopts=help` for a full list of supported options.
|
|
|
|
## Command Interface & Input Mapping
|
|
The keymap file is located in the mpv configuration directory (normally at `~/.config/mpv/input.conf` depending on platform). The default bindings are defined [here](https://github.com/mpv-player/mpv/blob/master/etc/input.conf).
|
|
The `input.conf` file consists of a list of key bindings, for example:
|
|
```
|
|
s screenshot # take a screenshot with the s key
|
|
LEFT seek 15 # map the left-arrow key to seeking forward by 15 seconds
|
|
```
|
|
|
|
Each line maps a key to an input command. Keys are specified with their literal value (upper case if combined with Shift), or a name for special keys. For example, `a` maps to the `a` key without `shift`, and `A` maps to `a` with shift.
|
|
Syntax: `[Shift+][Ctrl+][Alt+][Meta+]<key> [{<section>}] <command> ( ; <command> )*`
|
|
|
|
### List of Input Commands
|
|
Commands with parameters have the parameter name enclosed in `< / >`. Don't add those to the actual command. Optional arguments are enclosed in `[ / ]`. If you don't pass them, they will be set to a default value.
|
|
|
|
- `ignore`
|
|
Use this to "block" keys that should be unbound, and do nothing. Useful for disabling default bindings, without disabling all bindings with `--no-input-default-bindings`.
|
|
- `seek <target> [<flags>]`
|
|
Change the playback position. By default, seeks by a relative amount of seconds.
|
|
|
|
The second argument consists of flags controlling the seek mode:
|
|
|
|
| Mode | Description |
|
|
| ------------------ | ------------------------------------------------------------------------ |
|
|
| relative (default) | Seek relative to current position (a negative value seeks backwards). |
|
|
| absolute | Seek to a given time (a negative value starts from the end of the file). |
|
|
| absolute-percent | Seek to a given percent position. |
|
|
| relative-percent | Seek relative to current position in percent. |
|
|
| keyframes | Always restart playback at keyframe boundaries (fast). |
|
|
| exact | Always do exact/hr/precise seeks (slow). |
|
|
|
|
- `set <name> <value>`
|
|
Set the given property or option to the given value.
|
|
- `del <name>`
|
|
Delete the given property. Most properties cannot be deleted.
|
|
- `add <name> [<value>]`
|
|
Add the given value to the property or option. On overflow or underflow, clamp the property to the maximum. If `<value>` is omitted, assume 1.
|
|
- `screenshot <flags>`
|
|
Take a screenshot.
|
|
|
|
Multiple flags are available (some can be combined with +):
|
|
|
|
| Flag | Description |
|
|
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `<subtitles> (default)` | Save the video image, in its original resolution, and with subtitles. Some video outputs may still include the OSD in the output under certain circumstances. |
|
|
| `<video>` | Like subtitles, but typically without OSD or subtitles. The exact behavior depends on the selected video output. |
|
|
| `<window>` | Save the contents of the mpv window. Typically scaled, with OSD and subtitles. The exact behavior depends on the selected video output. |
|
|
| `<each-frame>` | Take a screenshot each frame. Issue this command again to stop taking screenshots. Note that you should disable frame-dropping when using this mode - or you might receive duplicate images in cases when a frame was dropped. This flag can be combined with the other flags, e.g. video+each-frame. |
|
|
|
|
- `playlist-next`
|
|
Go to the next entry on the playlist.
|
|
- `playlist-prev`
|
|
Go to the previous entry on the playlist.
|
|
- `playlist-play-index <integer|current|none>`
|
|
Start (or restart) playback of the given playlist index.
|
|
- `loadfile <url> [<flags> [<options>]]`
|
|
Load the given file or [URL](../../internet/URL.md) and play it. Technically, this is just a playlist manipulation command (which either replaces the playlist or appends an entry to it). Actual file loading happens independently. For example, a loadfile command that replaces the current file with a new one returns before the current file is stopped, and the new file even begins loading.
|
|
- `loadlist <url> [<flags>]`
|
|
Load the given playlist file or [URL](../../internet/URL.md) (like `--playlist`).
|
|
- `playlist-clear`
|
|
Clear the playlist, except the currently played file.
|
|
- `playlist-remove <index>`
|
|
Remove the playlist entry at the given index. Index values start counting with 0. The special value current removes the current entry. Note that removing the current entry also stops playback and starts playing the next entry.
|
|
- `playlist-move <index1> <index2>`
|
|
Move the playlist entry at index1, so that it takes the place of the entry index2. (Paradoxically, the moved playlist entry will not have the index value index2 after moving if index1 was lower than index2, because index2 refers to the target entry, not the index the entry will have after moving.)
|
|
- `playlist-shuffle`
|
|
Shuffle the playlist. This is similar to what is done on start if the `--shuffle` option is used.
|
|
- `run <command> [<arg1> [<arg2> [...]]]`
|
|
Run the given command. Unlike in MPlayer/mplayer2 and earlier versions of mpv (0.2.x and older), this doesn't call the [shell](../cli/Shell.md). Instead, the command is run directly, with each argument passed separately. Each argument is expanded like in Property Expansion.
|
|
This command has a variable number of arguments, and cannot be used with named arguments.
|
|
The program is run in a detached way. mpv doesn't wait until the command is completed, but continues playback right after spawning it.
|
|
- `quit [<code>]`
|
|
Exit the player. If an argument is given, it's used as process exit code.
|
|
- `sub-add <url> [<flags> [<title> [<lang>]]]`
|
|
Load the given subtitle file or stream. By default, it is selected as current subtitle after loading.
|
|
- `sub-remove [<id>]`
|
|
Remove the given subtitle track. If the id argument is missing, remove the current track. (Works on external subtitle files only.)
|
|
- `show-text <text> [<duration>|-1 [<level>]]`
|
|
Show text on the OSD. The string can contain properties, which are expanded as described in Property Expansion. This can be used to show playback time, filename, and so on. no-osd has no effect on this command.
|
|
- `expand-text <string>`
|
|
Property-expand the argument and return the expanded string. This can be used only through the client API or from a script using mp.command_native.
|
|
- `audio-add <url> [<flags> [<title> [<lang>]]]`
|
|
Load the given audio file.
|
|
- `audio-remove [<id>]`
|
|
Remove the given audio track.
|
|
- `audio-reload [<id>]`
|
|
Reload the given audio tracks.
|
|
- `video-add <url> [<flags> [<title> [<lang> [<albumart>]]]]`
|
|
Load the given video file.
|
|
- `video-remove [<id>]`
|
|
Remove the given video track.
|
|
- `video-reload [<id>]`
|
|
Reload the given video tracks.
|
|
|
|
### List of Properties
|
|
- `filename`
|
|
Currently played file, with path stripped. If this is an [URL](../../internet/URL.md), try to undo percent encoding as well. (The result is not necessarily correct, but looks better for display purposes. Use the `path` property to get an unmodified filename.)
|
|
- `filename/no-ext`
|
|
Like the filename property, but if the text contains a `.`, strip all text after the last `.`. Usually this removes the file extension.
|
|
- `file-size`
|
|
Length in bytes of the source file/stream.
|
|
- `estimated-frame-count`
|
|
Total number of frames in current file.
|
|
- `pid`
|
|
Process-id of mpv.
|
|
- `media-title`
|
|
If the currently played file has a title tag, use that. Otherwise, return the filename property.
|
|
- `file-format`
|
|
Symbolic name of the file format. In some cases, this is a comma-separated list of format names, e.g. mp4 is mov,mp4,m4a,3gp,3g2,mj2 (the list may grow in the future for any format).
|
|
- `duration`
|
|
Duration of the current file in seconds. If the duration is unknown, the property is unavailable. Note that the file duration is not always exactly known, so this is an estimate.
|
|
- `duration/full`
|
|
duration with milliseconds.
|
|
- `percent-pos` (RW)
|
|
Position in current file (0-100). The advantage over using this instead of calculating it out of other properties is that it properly falls back to estimating the playback position from the byte position, if the file duration is not known.
|
|
- `time-pos` (RW)
|
|
Position in current file in seconds.
|
|
- `time-pos/full`
|
|
`time-pos` with milliseconds.
|
|
- `time-remaining`
|
|
Remaining length of the file in seconds. Note that the file duration is not always exactly known, so this is an estimate.
|
|
- `time-remaining/full`
|
|
`time-remaining` with milliseconds.
|
|
- `playtime-remaining`
|
|
`time-remaining` scaled by the current speed.
|
|
- `playtime-remaining/full`
|
|
`playtime-remaining` with milliseconds.
|
|
- `chapter` (RW)
|
|
Current chapter number. The number of the first chapter is 0.
|
|
- `chapters`
|
|
Number of chapters.
|
|
- `metadata`
|
|
Metadata key/value pairs.
|
|
- `metadata/by-key/<key>`
|
|
Value of metadata entry `<key>`.
|
|
- `metadata/list/count`
|
|
Number of metadata entries.
|
|
- `metadata/list/N/key`
|
|
Key name of the Nth metadata entry. (The first entry is 0).
|
|
- `metadata/list/N/value`
|
|
Value of the Nth metadata entry.
|
|
- `width`, `height`
|
|
Video size. This uses the size of the video as decoded, or if no video frame has been decoded yet, the (possibly incorrect) container indicated size.
|
|
- `playlist-pos` (RW)
|
|
Current position on playlist. The first entry is on position 0. Writing to this property may start playback at the new position.
|
|
- `playlist-count`
|
|
Number of total playlist entries.
|
|
- `working-directory`
|
|
The working directory of the mpv process. Can be useful for JSON IPC users, because the command line player usually works with relative paths.
|
|
|
|
## Configuration
|
|
You can put all of the options in configuration files which will be read every time mpv is run. The system-wide configuration file 'mpv.conf' is in your configuration directory (e.g. `/etc/mpv` or `/usr/local/etc/mpv`), the user-specific one is `~/.config/mpv/mpv.conf`.
|
|
|
|
Almost all command line options can be put into the configuration file. Here is a small guide:
|
|
|
|
| Option | Configuration file entry |
|
|
| ----------------- | ------------------------ |
|
|
| --flag | flag |
|
|
| -opt val | opt=val |
|
|
| --opt=val | opt=val |
|
|
| -opt "has spaces" | opt=has spaces |
|
|
|
|
### Profiles
|
|
To ease working with different configurations, profiles can be defined in the configuration files. A profile starts with its name in square brackets, e.g. `[my-profile]`. All following options will be part of the profile. A description (shown by `--profile=help`) can be defined with the `profile-desc` option. To end the profile, start another one or use the profile name `default` to continue with normal options.
|
|
|
|
You can list profiles with `--profile=help`, and show the contents of a profile with `--show-profile=<name>` (replace `<name>` with the profile name). You can apply profiles on start with the `--profile=<name>` option, or at runtime with the `apply-profile <name>` command.
|
|
|
|
### Conditional Profiles
|
|
Profiles which have the `profile-cond` option set are applied automatically if the associated condition matches (unless auto profiles are disabled). The option takes a string, which is interpreted as Lua expression. If the expression evaluates as truthy, the profile is applied. If the expression errors or evaluates as falsy, the profile is not applied. This Lua code execution is not sandboxed.
|
|
|
|
Make only HD video look funny:
|
|
```
|
|
[something]
|
|
profile-desc=HD video
|
|
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
|
|
```
|
|
|
|
If you want the profile to be reverted if the condition goes to false again, you can set profile-restore:
|
|
```
|
|
[something]
|
|
profile-desc=Mess up video when entering fullscreen
|
|
profile-cond=fullscreen
|
|
profile-restore=copy
|
|
vf-add=rotate=PI/2 # rotate by 90 degrees
|
|
```
|
|
|
|
This appends the rotate filter to the video filter chain when entering fullscreen. When leaving fullscreen, the vf option is set to the value it had before entering fullscreen. Note that this would also remove any other filters that were added during fullscreen mode by the user. Avoiding this is trickier, and could for example be solved by adding a second profile with an inverse condition and operation:
|
|
```
|
|
[something]
|
|
profile-cond=fullscreen
|
|
vf-add=@rot:rotate=PI/2
|
|
|
|
[something-inv]
|
|
profile-cond=not fullscreen
|
|
vf-remove=@rot
|
|
```
|
|
|
|
## Lua Scripting
|
|
MPV can load Lua scripts.
|
|
mpv provides the built-in module mp, which contains functions to send commands to the mpv core and to retrieve information about playback state, user settings, file information, and so on.
|
|
Scripts can be passed to the `--script` option, and are automatically loaded from the scripts subdirectory of the mpv configuration directory (usually `~/.config/mpv/scripts/`).
|
|
|
|
Example - A script which leaves fullscreen mode when the player is paused:
|
|
```lua
|
|
function on_pause_change(name, value)
|
|
if value == true then
|
|
mp.set_property("fullscreen", "no")
|
|
end
|
|
end
|
|
mp.observe_property("pause", "bool", on_pause_change)
|
|
```
|
|
|
|
### mp functions
|
|
The mp module is preloaded, although it can be loaded manually with `require 'mp'`. It provides the core client API.
|
|
|
|
- `mp.command(string)`
|
|
Run the given command. This is similar to the commands used in `input.conf`.
|
|
Returns `true` on success, or `nil`, `error` on error.
|
|
- `mp.commandv(arg1, arg2, ...)`
|
|
Similar to `mp.command`, but pass each command argument as separate parameter. This has the advantage that you don't have to care about quoting and escaping in some cases.
|
|
|
|
Example:
|
|
```lua
|
|
mp.command("loadfile " .. filename .. " append")
|
|
mp.commandv("loadfile", filename, "append")
|
|
```
|
|
|
|
These two commands are equivalent, except that the first version breaks if the filename contains spaces or certain special characters.
|
|
|
|
Note that properties are not expanded. You can use either `mp.command`, the `expand-properties` prefix, or the `mp.get_property` family of functions.
|
|
|
|
Unlike `mp.command`, this will not use OSD by default either (except for some OSD-specific commands).
|
|
- `mp.del_property(name)`
|
|
Delete the given property. See `mp.get_property` and Properties for more information about properties. Most properties cannot be deleted.
|
|
|
|
Returns `true` on success, or `nil`, `error` on error.
|
|
- `mp.get_property(name [,def])`
|
|
Return the value of the given property as string. These are the same properties as used in `input.conf`. See Properties for a list of properties. The returned string is formatted similar to `${=name}`.
|
|
|
|
Returns the string on success, or def, error on error. def is the second parameter provided to the function, and is nil if it's missing.
|
|
- `mp.get_property_osd(name [,def])`
|
|
Similar to `mp.get_property`, but return the property value formatted for OSD. This is the same string as printed with `${name}` when used in `input.conf`.
|
|
|
|
Returns the string on success, or def, error on error. def is the second parameter provided to the function, and is an empty string if it's missing. Unlike `get_property()`, assigning the return value to a variable will always result in a string.
|
|
- `mp.get_property_bool(name [,def])`
|
|
Similar to `mp.get_property`, but return the property value as Boolean.
|
|
|
|
Returns a Boolean on success, or def, error on error.
|
|
- `mp.get_property_number(name [,def])`
|
|
Similar to `mp.get_property`, but return the property value as number.
|
|
|
|
Note that while Lua does not distinguish between integers and floats, mpv internals do. This function simply request a double float from mpv, and mpv will usually convert integer property values to float.
|
|
|
|
Returns a number on success, or def, error on error.
|
|
- `mp.get_property_native(name [,def])`
|
|
Similar to `mp.get_property`, but return the property value using the best Lua type for the property. Most time, this will return a string, Boolean, or number. Some properties (for example chapter-list) are returned as tables.
|
|
|
|
Returns a value on success, or def, error on error. Note that nil might be a possible, valid value too in some corner cases.
|
|
- `mp.set_property(name, value)`
|
|
Set the given property to the given string value.
|
|
|
|
Returns true on success, or nil, error on error.
|
|
- `mp.set_property_bool(name, value)`
|
|
Similar to `mp.set_property`, but set the given property to the given Boolean value.
|
|
- `mp.set_property_number(name, value)`
|
|
Similar to `mp.set_property`, but set the given property to the given numeric value.
|
|
|
|
Note that while Lua does not distinguish between integers and floats, mpv internals do. This function will test whether the number can be represented as integer, and if so, it will pass an integer value to mpv, otherwise a double float.
|
|
- `mp.set_property_native(name, value)`
|
|
Similar to `mp.set_property`, but set the given property using its native type.
|
|
|
|
Since there are several data types which cannot represented natively in Lua, this might not always work as expected. For example, while the Lua wrapper can do some guesswork to decide whether a Lua table is an array or a map, this would fail with empty tables. Also, there are not many properties for which it makes sense to use this, instead of set_property, set_property_bool, set_property_number. For these reasons, this function should probably be avoided for now, except for properties that use tables natively.
|
|
- `mp.get_time()`
|
|
Return the current mpv internal time in seconds as a number. This is basically the system time, with an arbitrary offset.
|
|
- `mp.add_key_binding(key, name|fn [,fn [,flags]])`
|
|
Register callback to be run on a key binding. The binding will be mapped to the given key, which is a string describing the physical key. This uses the same key names as in `input.conf`, and also allows combinations (e.g. `ctrl+a`). If the key is empty or `nil`, no physical key is registered, but the user still can create own bindings (see below).
|
|
|
|
After calling this function, key presses will cause the function fn to be called (unless the user remapped the key with another binding).
|
|
|
|
The name argument should be a short symbolic string. It allows the user to remap the key binding via `input.conf` using the `script-message` command, and the name of the key binding (see below for an example). The name should be unique across other bindings in the same script - if not, the previous binding with the same name will be overwritten. You can omit the name, in which case a random name is generated internally. (Omitting works as follows: either pass `nil` for name, or pass the fn argument in place of the name. The latter is not recommended and is handled for compatibility only.)
|
|
|
|
The last argument is used for optional flags. This is a table, which can have the following entries:
|
|
- repeatable
|
|
If set to true, enables key repeat for this specific binding.
|
|
- complex
|
|
If set to true, then fn is called on both key up and down events (as well as key repeat, if enabled), with the first argument being a table. This table has the following entries (and may contain undocumented ones):
|
|
- event
|
|
Set to one of the strings down, repeat, up or press (the latter if key up/down can't be tracked).
|
|
- is_mouse
|
|
Boolean Whether the event was caused by a mouse button.
|
|
- key_name
|
|
The name of they key that triggered this, or nil if invoked artificially. If the key name is unknown, it's an empty string.
|
|
- key_text
|
|
Text if triggered by a text key, otherwise nil. See description of script-binding command for details (this field is equivalent to the 5th argument).
|
|
|
|
Internally, key bindings are dispatched via the `script-message-to` or `script-binding` input commands and `mp.register_script_message`.
|
|
|
|
Example:
|
|
```lua
|
|
function something_handler()
|
|
print("the key was pressed")
|
|
end
|
|
mp.add_key_binding("x", "something", something_handler)
|
|
```
|
|
|
|
This will print the message the key was pressed when x was pressed.
|
|
|
|
The user can remap these key bindings. Then the user has to put the following into their `input.conf` to remap the command to the y key:
|
|
```
|
|
y script-binding something
|
|
```
|
|
|
|
This will print the message when the key y is pressed. (x will still work, unless the user remaps it.)
|
|
|
|
You can also explicitly send a message to a named script only. Assume the above script was using the filename `fooscript.lua`:
|
|
```
|
|
y script-binding fooscript/something
|
|
```
|
|
- `mp.remove_key_binding(name)`
|
|
Remove a key binding added with `mp.add_key_binding`. Use the same name as you used when adding the bindings. It's not possible to remove bindings for which you omitted the name.
|
|
- `mp.observe_property(name, type, fn)`
|
|
Watch a property for changes. If the property name is changed, then the function `fn(name)` will be called. type can be nil, or be set to one of none, native, bool, string, or number. none is the same as nil. For all other values, the new value of the property will be passed as second argument to fn, using `mp.get_property_<type>` to retrieve it. This means if type is for example string, fn is roughly called as in fn(name, mp.get_property_string(name)).
|
|
|
|
If possible, change events are coalesced. If a property is changed a bunch of times in a row, only the last change triggers the change function. (The exact behavior depends on timing and other things.)
|
|
|
|
If a property is unavailable, or on error, the value argument to fn is nil. (The `observe_property()` call always succeeds, even if a property does not exist.)
|
|
|
|
In some cases the function is not called even if the property changes. This depends on the property, and it's a valid feature request to ask for better update handling of a specific property.
|
|
|
|
If the type is none or nil, sporadic property change events are possible. This means the change function fn can be called even if the property doesn't actually change.
|
|
|
|
You always get an initial change notification. This is meant to initialize the user's state to the current value of the property.
|
|
- `mp.unobserve_property(fn)`
|
|
Undo `mp.observe_property(..., fn)`. This removes all property handlers that are equal to the fn parameter. This uses normal Lua == comparison, so be careful when dealing with closures.
|
|
- `mp.add_timeout(seconds, fn [, disabled])`
|
|
Call the given function fn when the given number of seconds has elapsed. Note that the number of seconds can be fractional. For now, the timer's resolution may be as low as 50 ms, although this will be improved in the future.
|
|
|
|
If the disabled argument is set to true or a truthy value, the timer will wait to be manually started with a call to its resume() method.
|
|
|
|
This is a one-shot timer: it will be removed when it's fired.
|
|
|
|
Returns a timer object. See `mp.add_periodic_timer` for details.
|
|
- `mp.add_periodic_timer(seconds, fn [, disabled])`
|
|
Call the given function periodically. This is like `mp.add_timeout`, but the timer is re-added after the function fn is run.
|
|
|
|
Returns a timer object. The timer object provides the following methods:
|
|
- `stop()`
|
|
Disable the timer. Does nothing if the timer is already disabled. This will remember the current elapsed time when stopping, so that `resume()` essentially unpauses the timer.
|
|
- `kill()`
|
|
Disable the timer. Resets the elapsed time. `resume()` will restart the timer.
|
|
- `resume()`
|
|
Restart the timer. If the timer was disabled with `stop()`, this will resume at the time it was stopped. If the timer was disabled with `kill()`, or if it's a previously fired one-shot timer (added with `add_timeout()`), this starts the timer from the beginning, using the initially configured timeout.
|
|
- `is_enabled()`
|
|
Whether the timer is currently enabled or was previously disabled (e.g. by `stop()` or `kill()`).
|
|
- `timeout` (RW)
|
|
This field contains the current timeout period. This value is not updated as time progresses. It's only used to calculate when the timer should fire next when the timer expires.
|
|
|
|
If you write this, you can call `t:kill() ; t:resume()` to reset the current timeout to the new one. (`t:stop()` won't use the new timeout.)
|
|
- `oneshot` (RW)
|
|
Whether the timer is periodic (false) or fires just once (true). This value is used when the timer expires (but before the timer callback function fn is run).
|
|
|
|
> Note that these are methods, and you have to call them using : instead of . (Refer to https://www.lua.org/manual/5.2/manual.html#3.4.9 .)
|
|
|
|
Example:
|
|
```lua
|
|
seconds = 0
|
|
timer = mp.add_periodic_timer(1, function()
|
|
print("called every second")
|
|
# stop it after 10 seconds
|
|
seconds = seconds + 1
|
|
if seconds >= 10 then
|
|
timer:kill()
|
|
end
|
|
end)
|
|
```
|
|
- `mp.osd_message(text [,duration])`
|
|
Show an OSD message on the screen. duration is in seconds, and is optional.
|
|
|
|
#### mp.utils
|
|
This built-in module provides generic helper functions for Lua, and have strictly speaking nothing to do with mpv or video/audio playback. They are provided for convenience. Most compensate for Lua's scarce standard library.
|
|
|
|
Be warned that any of these functions might disappear any time. They are not strictly part of the guaranteed API.
|
|
|
|
- `utils.getcwd()`
|
|
Returns the directory that mpv was launched from. On error, nil, error is returned.
|
|
- `utils.readdir(path [, filter])`
|
|
Enumerate all entries at the given path on the filesystem, and return them as array. Each entry is a directory entry (without the path). The list is unsorted (in whatever order the operating system returns it).
|
|
|
|
If the filter argument is given, it must be one of the following strings:
|
|
- `files`
|
|
List regular files only. This excludes directories, special files (like UNIX device files or FIFOs), and dead symlinks. It includes UNIX symlinks to regular files.
|
|
- `dirs`
|
|
List directories only, or symlinks to directories. `.` and `..` are not included.
|
|
- `normal`
|
|
Include the results of both files and dirs. (This is the default.)
|
|
- `all`
|
|
List all entries, even device files, dead symlinks, FIFOs, and the . and .. entries.
|
|
|
|
On error, nil, error is returned.
|
|
- `utils.file_info(path)`
|
|
Stats the given path for information and returns a table with the following entries:
|
|
- `mode`
|
|
protection bits
|
|
- `size`
|
|
size in bytes
|
|
- `atime`
|
|
time of last access
|
|
- `mtime`
|
|
time of last modification
|
|
- `ctime`
|
|
time of last metadata change
|
|
- `is_file`
|
|
Whether path is a regular file (boolean)
|
|
- `is_dir`
|
|
Whether path is a directory (boolean)
|
|
|
|
`mode` and `size` are integers. Timestamps (`atime`, `mtime` and `ctime`) are integer seconds since the Unix epoch (Unix time). The booleans `is_file` and `is_dir` are provided as a convenience; they can be and are derived from `mode`.
|
|
|
|
On error (e.g. path does not exist), nil, error is returned.
|
|
- `utils.split_path(path)`
|
|
Split a path into directory component and filename component, and return them. The first return value is always the directory. The second return value is the trailing part of the path, the directory entry.
|
|
- `utils.join_path(p1, p2)`
|
|
Return the concatenation of the 2 paths. Tries to be clever. For example, if `p2` is an absolute path, `p2` is returned without change.
|
|
- `utils.get_env_list()`
|
|
Returns the C environment as a list of strings.
|
|
- `utils.parse_json(str [, trail])`
|
|
Parses the given string argument as [JSON](../../files/JSON.md), and returns it as a Lua table. On error, returns nil, error. (Currently, error is just a string reading error, because there is no fine-grained error reporting of any kind.)
|
|
|
|
The returned value uses similar conventions as `mp.get_property_native()` to distinguish empty objects and arrays.
|
|
|
|
If the trail parameter is true (or any value equal to true), then trailing non-whitespace text is tolerated by the function, and the trailing text is returned as 3rd return value. (The 3rd return value is always there, but with trail set, no error is raised.)
|
|
- `utils.format_json(v)`
|
|
Format the given Lua table (or value) as a [JSON](../../files/JSON.md) string and return it. On error, returns nil, error. (Errors usually only happen on value types incompatible with [JSON](../../files/JSON.md).)
|
|
|
|
The argument value uses similar conventions as `mp.set_property_native()` to distinguish empty objects and arrays.
|
|
- `utils.to_string(v)`
|
|
Turn the given value into a string. Formats tables and their contents. This doesn't do anything special; it is only needed because Lua is terrible.
|
|
|
|
### [User Scripts](https://github.com/mpv-player/mpv/wiki/User-Scripts)
|
|
- **[autoloop](https://github.com/zc62/mpv-scripts/blob/master/autoloop.lua)**: Automatically loops files that are under a given duration (default 5 seconds).
|
|
- **[copyTime](https://github.com/Arieleg/mpv-copyTime)**: Get the current time of the video and copy it to the clipboard with the format `HH:MM:SS.MS`. |