OPTIONS ======= Track Selection --------------- ``--alang=`` Specify a priority list of audio languages to use. Different container formats employ different language codes. DVDs use ISO 639-1 two-letter language codes, Matroska, MPEG-TS and NUT use ISO 639-2 three-letter language codes, while OGM uses a free-form identifier. See also ``--aid``. This is a string list option. See `List Options`_ for details. .. admonition:: Examples - ``mpv dvd://1 --alang=hu,en`` chooses the Hungarian language track on a DVD and falls back on English if Hungarian is not available. - ``mpv --alang=jpn example.mkv`` plays a Matroska file with Japanese audio. ``--slang=`` Specify a priority list of subtitle languages to use. Different container formats employ different language codes. DVDs use ISO 639-1 two letter language codes, Matroska uses ISO 639-2 three letter language codes while OGM uses a free-form identifier. See also ``--sid``. This is a string list option. See `List Options`_ for details. .. admonition:: Examples - ``mpv dvd://1 --slang=hu,en`` chooses the Hungarian subtitle track on a DVD and falls back on English if Hungarian is not available. - ``mpv --slang=jpn example.mkv`` plays a Matroska file with Japanese subtitles. ``--vlang=<...>`` Equivalent to ``--alang`` and ``--slang``, for video tracks. This is a string list option. See `List Options`_ for details. ``--aid=`` 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``. ``--aid=no`` or ``--audio=no`` or ``--no-audio`` disables audio playback. (The latter variant does not work with the client API.) .. note:: The track selection options (``--aid`` but also ``--sid`` and the others) sometimes expose behavior that may appear strange. Also, the behavior tends to change around with each mpv release. The track selection properties will return the option value outside of playback (as expected), but during playback, the affective track selection is returned. For example, with ``--aid=auto``, the ``aid`` property will suddenly return ``2`` after playback initialization (assuming the file has at least 2 audio tracks, and the second is the default). At mpv 0.32.0 (and some releases before), if you passed a track value for which a corresponding track didn't exist (e.g. ``--aid=2`` and there was only 1 audio track), the ``aid`` property returned ``no``. However if another audio track was added during playback, and you tried to set the ``aid`` property to ``2``, nothing happened, because the ``aid`` option still had the value ``2``, and writing the same value has no effect. With mpv 0.33.0, the behavior was changed. Now track selection options are reset to ``auto`` at playback initialization, if the option had tries to select a track that does not exist. The same is done if the track exists, but fails to initialize. The consequence is that unlike before mpv 0.33.0, the user's track selection parameters are clobbered in certain situations. Also since mpv 0.33.0, trying to select a track by number will strictly select this track. Before this change, trying to select a track which did not exist would fall back to track default selection at playback initialization. The new behavior is more consistent. Setting a track selection property at runtime, and then playing a new file might reset the track selection to defaults, if the fingerprint of the track list of the new file is different. Be aware of tricky combinations of all of all of the above: for example, ``mpv --aid=2 file_with_2_audio_tracks.mkv file_with_1_audio_track.mkv`` would first play the correct track, and the second file without audio. If you then go back the first file, its first audio track will be played, and the second file is played with audio. If you do the same thing again but instead of using ``--aid=2`` you run ``set aid 2`` while the file is playing, then changing to the second file will play its audio track. This is because runtime selection enables the fingerprint heuristic. Most likely this is not the end. ``--sid=`` Display the subtitle stream specified by ````. ``auto`` selects the default, ``no`` disables subtitles. ``--sub`` is an alias for ``--sid``. ``--sid=no`` or ``--sub=no`` or ``--no-sub`` disables subtitle decoding. (The latter variant does not work with the client API.) ``--vid=`` Select video channel. ``auto`` selects the default, ``no`` disables video. ``--video`` is an alias for ``--vid``. ``--vid=no`` or ``--video=no`` or ``--no-video`` disables video playback. (The latter variant does not work with the client API.) If video is disabled, mpv will try to download the audio only if media is streamed with youtube-dl, because it saves bandwidth. This is done by setting the ytdl_format to "bestaudio/best" in the ytdl_hook.lua script. ``--edition=`` (Matroska files only) Specify the edition (set of chapters) to use, where 0 is the first. If set to ``auto`` (the default), mpv will choose the first edition declared as a default, or if there is no default, the first edition defined. ``--track-auto-selection=`` Enable the default track auto-selection (default: yes). Enabling this will make the player select streams according to ``--aid``, ``--alang``, and others. If it is disabled, no tracks are selected. In addition, the player will not exit if no tracks are selected, and wait instead (this wait mode is similar to pausing, but the pause option is not set). This is useful with ``--lavfi-complex``: you can start playback in this mode, and then set select tracks at runtime by setting the filter graph. Note that if ``--lavfi-complex`` is set before playback is started, the referenced tracks are always selected. ``--subs-with-matching-audio=`` When autoselecting a subtitle track, select a non-forced one even if the selected audio stream matches your preferred subtitle language (default: yes). Disable this if you'd like to only show subtitles for foreign audio or onscreen text. Playback Control ---------------- ``--start=`` 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 (but see below). 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). If ``--rebase-start-time=no`` is given, then prefixing times with ``+`` makes the time relative to the start of the file. A timestamp without prefix is considered an absolute time, i.e. should seek to a frame with a timestamp as the file contains it. As a bug, but also a hidden feature, putting 1 or more spaces before the ``+`` or ``-`` always interprets the time as absolute, which can be used to seek to negative timestamps (useful for debugging at most). .. admonition:: Examples ``--start=+56``, ``--start=00:56`` Seeks to the start time + 56 seconds. ``--start=-56``, ``--start=-00:56`` Seeks to the end time - 56 seconds. ``--start=01:10:00`` Seeks to 1 hour 10 min. ``--start=50%`` Seeks to the middle of the file. ``--start=30 --end=40`` Seeks to 30 seconds, plays 10 seconds, and exits. ``--start=-3:20 --length=10`` Seeks to 3 minutes and 20 seconds before the end of the file, plays 10 seconds, and exits. ``--start='#2' --end='#4'`` Plays chapters 2 and 3, and exits. ``--end=`` Stop at given time. Use ``--length`` if the time should be relative to ``--start``. See ``--start`` for valid option values and examples. ``--length=`` 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. Obscurity note: this does not work correctly if ``--rebase-start-time=no``, and the specified time is not an "absolute" time, as defined in the ``--start`` option description. ``--rebase-start-time=`` Whether to move the file start time to ``00:00:00`` (default: yes). This is less awkward for files which start at a random timestamp, such as transport streams. On the other hand, if there are timestamp resets, the resulting behavior can be rather weird. For this reason, and in case you are actually interested in the real timestamps, this behavior can be disabled with ``no``. ``--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=`` 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). If an entry with the given index doesn't exist, the behavior is unspecified and might change in future mpv versions. The same applies if the playlist contains further playlists (don't expect any reasonable behavior). Passing a playlist file to mpv should work with this option, though. E.g. ``mpv playlist.m3u --playlist-start=123`` will work as expected, as long as ``playlist.m3u`` does not link to further playlists. The value ``no`` is a deprecated alias for ``auto``. ``--playlist=`` Play files according to a playlist file. Supports some common formats. If no format is detected, it will be treated as list of files, separated by newline characters. You may need this option to load plaintext files as a playlist. Note that XML playlist formats are not supported. This option forces ``--demuxer=playlist`` to interpret the playlist file. Some playlist formats, notably CUE and optical disc formats, need to use different demuxers and will not work with this option. They still can be played directly, without using this option. You can play playlists directly, without this option. Before mpv version 0.31.0, this option disabled any security mechanisms that might be in place, but since 0.31.0 it uses the same security mechanisms as playing a playlist file directly. If you trust the playlist file, you can disable any security checks with ``--load-unsafe-playlists``. Because playlists can load other playlist entries, consider applying this option only to the playlist itself and not its entries, using something along these lines: ``mpv --{ --playlist=filename --load-unsafe-playlists --}`` .. warning:: The way older versions of mpv played playlist files via ``--playlist`` was not safe against maliciously constructed files. Such files may trigger harmful actions. This has been the case for all verions of mpv prior to 0.31.0, and all MPlayer versions, but unfortunately this fact was not well documented earlier, and some people have even misguidedly recommended the use of ``--playlist`` with untrusted sources. Do NOT use ``--playlist`` with random internet sources or files you do not trust if you are not sure your mpv is at least 0.31.0. In particular, playlists can contain entries using protocols other than local files, such as special protocols like ``avdevice://`` (which are inherently unsafe). ``--chapter-merge-threshold=`` Threshold for merging almost consecutive ordered chapter parts in milliseconds (default: 100). Some Matroska files with ordered chapters have inaccurate chapter end timestamps, causing a small gap between the end of one chapter and the start of the next one when they should match. If the end of one playback part is less than the given threshold away from the start of the next one then keep playing video normally over the chapter change instead of doing a seek. ``--chapter-seek-threshold=`` Distance in seconds from the beginning of a chapter within which a backward chapter seek will go to the previous chapter (default: 5.0). Past this threshold, a backward chapter seek will go to the beginning of the current chapter instead. A negative value means always go back to the previous chapter. ``--hr-seek=`` Select when to use precise seeks that are not limited to keyframes. Such seeks require decoding video from the previous keyframe up to the target position and so can take some time depending on decoding performance. For some video formats, precise seeks are disabled. This option selects the default choice to use for seeks; it is possible to explicitly override that default in the definition of key bindings and in input commands. :no: Never use precise seeks. :absolute: Use precise seeks if the seek is to an absolute position in the file, such as a chapter seek, but not for relative seeks like the default behavior of arrow keys (default). :default: Like ``absolute``, but enable hr-seeks in audio-only cases. The exact behavior is implementation specific and may change with new releases. :yes: Use precise seeks whenever possible. :always: Same as ``yes`` (for compatibility). ``--hr-seek-demuxer-offset=`` This option exists to work around failures to do precise seeks (as in ``--hr-seek``) caused by bugs or limitations in the demuxers for some file formats. Some demuxers fail to seek to a keyframe before the given target position, going to a later position instead. The value of this option is subtracted from the time stamp given to the demuxer. Thus, if you set this option to 1.5 and try to do a precise seek to 60 seconds, the demuxer is told to seek to time 58.5, which hopefully reduces the chance that it erroneously goes to some time later than 60 seconds. The downside of setting this option is that precise seeks become slower, as video between the earlier demuxer position and the real target may be unnecessarily decoded. ``--hr-seek-framedrop=`` Allow the video decoder to drop frames during seek, if these frames are before the seek target. If this is enabled, precise seeking can be faster, but if you're using video filters which modify timestamps or add new frames, it can lead to precise seeking skipping the target frame. This e.g. can break frame backstepping when deinterlacing is enabled. Default: ``yes`` ``--index=`` Controls how to seek in files. Note that if the index is missing from a file, it will be built on the fly by default, so you don't need to change this. But it might help with some broken files. :default: use an index if the file has one, or build it if missing :recreate: don't read or use the file's index .. note:: This option only works if the underlying media supports seeking (i.e. not with stdin, pipe, etc). ``--load-unsafe-playlists`` Load URLs from playlists which are considered unsafe (default: no). This includes special protocols and anything that doesn't refer to normal files. Local files and HTTP links on the other hand are always considered safe. In addition, if a playlist is loaded while this is set, the added playlist entries are not marked as originating from network or potentially unsafe location. (Instead, the behavior is as if the playlist entries were provided directly to mpv command line or ``loadfile`` command.) ``--access-references=`` Follow any references in the file being opened (default: yes). Disabling this is helpful if the file is automatically scanned (e.g. thumbnail generation). If the thumbnail scanner for example encounters a playlist file, which contains network URLs, and the scanner should not open these, enabling this option will prevent it. This option also disables ordered chapters, mov reference files, opening of archives, and a number of other features. On older FFmpeg versions, this will not work in some cases. Some FFmpeg demuxers might not respect this option. This option does not prevent opening of paired subtitle files and such. Use ``--autoload-files=no`` to prevent this. This option does not always work if you open non-files (for example using ``dvd://directory`` would open a whole bunch of files in the given directory). Prefixing the filename with ``./`` if it doesn't start with a ``/`` will avoid this. ``--loop-playlist=``, ``--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``. The ``force`` mode is like ``inf``, but does not skip playlist entries which have been marked as failing. This means the player might waste CPU time trying to loop a file that doesn't exist. But it might be useful for playing webradios under very bad network conditions. ``--loop-file=``, ``--loop=`` 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. .. note:: ``--loop-file`` counts the number of times it causes the player to seek to the beginning of the file, not the number of full playthroughs. This means ``--loop-file=1`` will end up playing the file twice. Contrast with ``--loop-playlist``, which counts the number of full playthroughs. ``--loop`` is an alias for this option. ``--ab-loop-a=