## File: README.md # mpv * [External links](#external-links) * [Overview](#overview) * [System requirements](#system-requirements) * [Downloads](#downloads) * [Changelog](#changelog) * [Compilation](#compilation) * [Release cycle](#release-cycle) * [Bug reports](#bug-reports) * [Contributing](#contributing) * [License](#license) * [Contact](#contact) ## External links * [Wiki](https://github.com/mpv-player/mpv/wiki) * [User Scripts](https://github.com/mpv-player/mpv/wiki/User-Scripts) * [FAQ][FAQ] * [Manual](https://mpv.io/manual/master/) ## Overview **mpv** is a free (as in freedom) media player for the command line. It supports a wide variety of media file formats, audio and video codecs, and subtitle types. There is a [FAQ][FAQ]. Releases can be found on the [release list][releases]. ## System requirements - A not too ancient Linux (usually, only the latest releases of distributions are actively supported), Windows 10 1607 or later, or macOS 10.15 or later. - A somewhat capable CPU. Hardware decoding might help if the CPU is too slow to decode video in realtime, but must be explicitly enabled with the `--hwdec` option. - A not too crappy GPU. mpv's focus is not on power-efficient playback on embedded or integrated GPUs (for example, hardware decoding is not even enabled by default). Low power GPUs may cause issues like tearing, stutter, etc. On such GPUs, it's recommended to use `--profile=fast` for smooth playback. The main video output uses shaders for video rendering and scaling, rather than GPU fixed function hardware. On Windows, you might want to make sure the graphics drivers are current. In some cases, ancient fallback video output methods can help (such as `--vo=xv` on Linux), but this use is not recommended or supported. mpv does not go out of its way to break on older hardware or old, unsupported operating systems, but development is not done with them in mind. Keeping compatibility with such setups is not guaranteed. If things work, consider it a happy accident. ## Downloads For semi-official builds and third-party packages please see [mpv.io/installation](https://mpv.io/installation/). ## Changelog There is no complete changelog; however, changes to the player core interface are listed in the [interface changelog][interface-changes]. Changes to the C API are documented in the [client API changelog][api-changes]. The [release list][releases] has a summary of most of the important changes on every release. Changes to the default key bindings are indicated in [restore-old-bindings.conf][restore-old-bindings]. Changes to the default OSC bindings are indicated in [restore-osc-bindings.conf][restore-osc-bindings]. ## Compilation Compiling with full features requires development files for several external libraries. Mpv requires [meson](https://mesonbuild.com/index.html) to build. Meson can be obtained from your distro or PyPI. After creating your build directory (e.g. `meson setup build`), you can view a list of all the build options via `meson configure build`. You could also just simply look at the `meson_options.txt` file. Logs are stored in `meson-logs` within your build directory. Example: meson setup build meson compile -C build meson install -C build For libplacebo, meson can use a git check out as a subproject for a convenient way to compile mpv if a sufficient libplacebo version is not easily available in the build environment. It will be statically linked with mpv. Example: mkdir -p subprojects git clone https://code.videolan.org/videolan/libplacebo.git --depth=1 --recursive subprojects/libplacebo Essential dependencies (incomplete list): - gcc or clang - X development headers (xlib, xrandr, xext, xscrnsaver, xpresent, libvdpau, libGL, GLX, EGL, xv, ...) - Audio output development headers (libasound/ALSA, pulseaudio) - FFmpeg libraries (libavutil libavcodec libavformat libswscale libavfilter and either libswresample or libavresample) - libplacebo - zlib - iconv (normally provided by the system libc) - libass (OSD, OSC, text subtitles) - Lua (optional, required for the OSC pseudo-GUI and youtube-dl integration) - libjpeg (optional, used for screenshots only) - uchardet (optional, for subtitle charset detection) - nvdec and vaapi libraries for hardware decoding on Linux (optional) Libass dependencies (when building libass): - gcc or clang, nasm on x86 and x86_64 - fribidi, freetype, fontconfig development headers (for libass) - harfbuzz (required for correct rendering of combining characters, particularly for correct rendering of non-English text on macOS, and Arabic/Indic scripts on any platform) FFmpeg dependencies (when building FFmpeg): - gcc or clang, nasm on x86 and x86_64 - OpenSSL or GnuTLS (have to be explicitly enabled when compiling FFmpeg) - libx264/libmp3lame/libfdk-aac if you want to use encoding (have to be explicitly enabled when compiling FFmpeg) - For native DASH playback, FFmpeg needs to be built with --enable-libxml2 (although there are security implications, and DASH support has lots of bugs). - AV1 decoding support requires dav1d. - For good nvidia support on Linux, make sure nv-codec-headers is installed and can be found by configure. Most of the above libraries are available in suitable versions on normal Linux distributions. For ease of compiling the latest git master of everything, you may wish to use the separately available build wrapper ([mpv-build][mpv-build]) which first compiles FFmpeg libraries and libass, and then compiles the player statically linked against those. If you want to build a Windows binary, see [Windows compilation][windows_compilation]. ## Release cycle Once or twice a year, a release is cut off from the current development state and is assigned a 0.X.0 version number. No further maintenance is done, except in the event of security issues. The goal of releases is to make Linux distributions happy. Linux distributions are also expected to apply their own patches in case of bugs. Releases other than the latest release are unsupported and unmaintained. See the [release policy document][release-policy] for more information. ## Bug reports Please use the [issue tracker][issue-tracker] provided by GitHub to send us bug reports or feature requests. Follow the template's instructions or the issue will likely be ignored or closed as invalid. Questions can be asked in the [discussions][discussions] or on IRC (see [Contact](#Contact) below). ## Contributing Please read [contribute.md][contribute.md]. For small changes you can just send us pull requests through GitHub. For bigger changes come and talk to us on IRC before you start working on them. It will make code review easier for both parties later on. You can check [the wiki](https://github.com/mpv-player/mpv/wiki/Stuff-to-do) or the [issue tracker](https://github.com/mpv-player/mpv/issues?q=is%3Aopen+is%3Aissue+label%3Ameta%3Afeature-request) for ideas on what you could contribute with. ## License GPLv2 "or later" by default, LGPLv2.1 "or later" with `-Dgpl=false`. See [details.](https://github.com/mpv-player/mpv/blob/master/Copyright) ## History This software is based on the MPlayer project. Before mpv existed as a project, the code base was briefly developed under the mplayer2 project. For details, see the [FAQ][FAQ]. ## Contact Most activity happens on the IRC channel and the GitHub issue tracker. - **GitHub issue tracker**: [issue tracker][issue-tracker] (report bugs here) - **Discussions**: [discussions][discussions] - **User IRC Channel**: `#mpv` on `irc.libera.chat` - **Developer IRC Channel**: `#mpv-devel` on `irc.libera.chat` [FAQ]: https://github.com/mpv-player/mpv/wiki/FAQ [releases]: https://github.com/mpv-player/mpv/releases [mpv-build]: https://github.com/mpv-player/mpv-build [issue-tracker]: https://github.com/mpv-player/mpv/issues [discussions]: https://github.com/mpv-player/mpv/discussions [release-policy]: https://github.com/mpv-player/mpv/blob/master/DOCS/release-policy.md [windows_compilation]: https://github.com/mpv-player/mpv/blob/master/DOCS/compile-windows.md [interface-changes]: https://github.com/mpv-player/mpv/blob/master/DOCS/interface-changes.rst [api-changes]: https://github.com/mpv-player/mpv/blob/master/DOCS/client-api-changes.rst [restore-old-bindings]: https://github.com/mpv-player/mpv/blob/master/etc/restore-old-bindings.conf [restore-osc-bindings]: https://github.com/mpv-player/mpv/blob/master/etc/restore-osc-bindings.conf [contribute.md]: https://github.com/mpv-player/mpv/blob/master/DOCS/contribute.md --- ## File: DOCS/man/af.rst AUDIO FILTERS ============= Audio filters allow you to modify the audio stream and its properties. The syntax is: ``--af=...`` Setup a chain of audio filters. See ``--vf`` (`VIDEO FILTERS`_) for the full syntax. This is an object settings list option. See `List Options`_ for details. .. note:: To get a full list of available audio filters, see ``--af=help``. Also, keep in mind that most actual filters are available via the ``lavfi`` wrapper, which gives you access to most of libavfilter's filters. This includes all filters that have been ported from MPlayer to libavfilter. The ``--vf`` description describes how libavfilter can be used and how to workaround deprecated mpv filters. See ``--vf`` group of options for info on how ``--af-add``, ``--af-pre``, ``--af-clr``, and possibly others work. Available filters are: ``lavcac3enc[=options]`` Encode multi-channel audio to AC-3 at runtime using libavcodec. Supports 16-bit native-endian input format, maximum 6 channels. The output is big-endian when outputting a raw AC-3 stream, native-endian when outputting to S/PDIF. If the input sample rate is not 48 kHz, 44.1 kHz or 32 kHz, it will be resampled to 48 kHz. ``tospdif=`` Output raw AC-3 stream if ``no``, output to S/PDIF for pass-through if ``yes`` (default). ``bitrate=`` The bitrate use for the AC-3 stream. Set it to 384 to get 384 kbps. The default is 640. Some receivers might not be able to handle this. Valid values: 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320, 384, 448, 512, 576, 640. The special value ``auto`` selects a default bitrate based on the input channel number: :1ch: 96 :2ch: 192 :3ch: 224 :4ch: 384 :5ch: 448 :6ch: 448 ``minch=`` If the input channel number is less than ````, the filter will detach itself (default: 3). ``encoder=`` Select the libavcodec encoder used. Currently, this should be an AC-3 encoder, and using another codec will fail horribly. ``format=format:srate:channels:out-srate:out-channels`` Does not do any format conversion itself. Rather, it may cause the filter system to insert necessary conversion filters before or after this filter if needed. It is primarily useful for controlling the audio format going into other filters. To specify the format for audio output, see ``--audio-format``, ``--audio-samplerate``, and ``--audio-channels``. This filter is able to force a particular format, whereas ``--audio-*`` may be overridden by the ao based on output compatibility. All parameters are optional. The first 3 parameters restrict what the filter accepts as input. They will therefore cause conversion filters to be inserted before this one. The ``out-`` parameters tell the filters or audio outputs following this filter how to interpret the data without actually doing a conversion. Setting these will probably just break things unless you really know you want this for some reason, such as testing or dealing with broken media. ```` Force conversion to this format. Use ``--af=format=format=help`` to get a list of valid formats. ```` Force conversion to a specific sample rate. The rate is an integer, 48000 for example. ```` Force mixing to a specific channel layout. See ``--audio-channels`` option for possible values. ```` ```` *NOTE*: this filter used to be named ``force``. The old ``format`` filter used to do conversion itself, unlike this one which lets the filter system handle the conversion. ``scaletempo[=option1:option2:...]`` Scales audio tempo without altering pitch, optionally synced to playback speed. This works by playing 'stride' ms of audio at normal speed then consuming 'stride*scale' ms of input audio. It pieces the strides together by blending 'overlap'% of stride with audio following the previous stride. It optionally performs a short statistical analysis on the next 'search' ms of audio to determine the best overlap position. ``scale=`` Nominal amount to scale tempo. Scales this amount in addition to speed. (default: 1.0) ``stride=`` Length in milliseconds to output each stride. Too high of a value will cause noticeable skips at high scale amounts and an echo at low scale amounts. Very low values will alter pitch. Increasing improves performance. (default: 60) ``overlap=`` Factor of stride to overlap. Decreasing improves performance. (default: .20) ``search=`` Length in milliseconds to search for best overlap position. Decreasing improves performance greatly. On slow systems, you will probably want to set this very low. (default: 14) ``speed=`` Set response to speed change. tempo Scale tempo in sync with speed (default). pitch Reverses effect of filter. Scales pitch without altering tempo. Add this to your ``input.conf`` to step by musical semi-tones:: [ multiply speed 0.9438743126816935 ] multiply speed 1.059463094352953 .. warning:: Loses sync with video. both Scale both tempo and pitch. none Ignore speed changes. .. admonition:: Examples ``mpv --af=scaletempo --speed=1.2 media.ogg`` Would play media at 1.2x normal speed, with audio at normal pitch. Changing playback speed would change audio tempo to match. ``mpv --af=scaletempo=scale=1.2:speed=none --speed=1.2 media.ogg`` Would play media at 1.2x normal speed, with audio at normal pitch, but changing playback speed would have no effect on audio tempo. ``mpv --af=scaletempo=stride=30:overlap=.50:search=10 media.ogg`` Would tweak the quality and performance parameters. ``mpv --af=scaletempo=scale=1.2:speed=pitch audio.ogg`` Would play media at 1.2x normal speed, with audio at normal pitch. Changing playback speed would change pitch, leaving audio tempo at 1.2x. ``scaletempo2[=option1:option2:...]`` Scales audio tempo without altering pitch. The algorithm is ported from chromium and uses the Waveform Similarity Overlap-and-add (WSOLA) method. It seems to achieves higher audio quality than scaletempo, and rubberband R2 engine, or ``engine=faster``. This filter is inserted automatically if ``audio-pitch-correction`` option is used (on by default) when the playback speed is changed. By default, the ``search-interval`` and ``window-size`` parameters have the same values as in chromium. ``min-speed=`` Mute audio if the playback speed is below ````. (default: 0.25) ``max-speed=`` Mute audio if the playback speed is above ```` and `` != 0``. (default: 8.0) ``search-interval=`` Length in milliseconds to search for best overlap position. (default: 40) ``window-size=`` Length in milliseconds of the overlap-and-add window. (default: 12) ``lavfi-tempo[=[filter=]]`` Scales audio tempo using ``atempo`` or ``ascale`` filters from FFmpeg's libavfilter. If ``ascale`` (Librempeg only) is not available in the loaded libavfilter, ``atempo`` will be used as a fall-back. This can be used in place of ``scaletempo`` and ``scaletempo2``. .. admonition:: Examples ``mpv --af=lavfi-tempo --speed=1.2 media.ogg`` Would play media at 1.2x normal speed at normal pitch with tempo scaled by the ``atempo`` filter from lavfi. ``mpv --af=lavfi-tempo=atempo --speed=1.2 media.ogg`` Same as above. ``mpv --af=lavfi-tempo=filter=atempo --speed=1.2 media.ogg`` Same as above. ``mpv --af=lavfi-tempo=ascale --speed=1.2 media.ogg`` Would play media at 1.2x normal speed at normal pitch with tempo scaled by the ``ascale`` filter from lavfi, unless the filter is not available, then ``atempo`` will be used as a fall-back. ``mpv --af=lavfi-tempo=filter=ascale --speed=1.2 media.ogg`` Same as above. ``rubberband`` High quality pitch correction with librubberband. This can be used in place of ``scaletempo`` and ``scaletempo2``, and will be used to adjust audio pitch when playing at speed different from normal. It can also be used to adjust audio pitch without changing playback speed. ``pitch-scale=`` Sets the pitch scaling factor. Frequencies are multiplied by this value. (default: 1.0) ``engine=`` Select the core Rubberband engine to be used. There are two available: :Faster: This is the Rubberband R2 engine. It uses significantly less CPU than the Finer (R3) engine. :Finer: This is the Rubberband R3 engine. This engine is only available with librubberband version 3 or newer. This produces significantly higher quality output, at the cost of higher CPU usage. (Default if available) This filter has a number of additional sub-options. You can list them with ``mpv --af=rubberband=help``. This will also show the default values for each option. The options are not documented here, because they are merely passed to librubberband. Look at the librubberband documentation to learn what each option does: https://breakfastquay.com/rubberband/code-doc/classRubberBand_1_1RubberBandStretcher.html Do note that certain options are only applicable to one of R2 (faster) and R3 (finer) engines. (The mapping of the mpv rubberband filter sub-option names and values to those of librubberband follows a simple pattern: ``"Option" + Name + Value``.) This filter supports the following ``af-command`` commands: ``set-pitch`` Set the ```` argument dynamically. This can be used to change the playback pitch at runtime. Note that speed is controlled using the standard ``speed`` property, not ``af-command``. ``multiply-pitch `` Multiply the current value of ```` dynamically. ``lavfi=graph`` Filter audio using FFmpeg's libavfilter. ```` Libavfilter graph. See ``lavfi`` video filter for details - the graph syntax is the same. .. warning:: Don't forget to quote libavfilter graphs as described in the lavfi video filter section. ``o=`` AVOptions. ``fix-pts=`` Determine PTS based on sample count (default: no). If this is enabled, the player won't rely on libavfilter passing through PTS accurately. Instead, it pass a sample count as PTS to libavfilter, and compute the PTS used by mpv based on that and the input PTS. This helps with filters which output a recomputed PTS instead of the original PTS (including filters which require the PTS to start at 0). mpv normally expects filters to not touch the PTS (or only to the extent of changing frame boundaries), so this is not the default, but it will be needed to use broken filters. In practice, these broken filters will either cause slow A/V desync over time (with some files), or break playback completely if you seek or start playback from the middle of a file. ``drop`` This filter drops or repeats audio frames to adapt to playback speed. It always operates on full audio frames, because it was made to handle SPDIF (compressed audio passthrough). This is used automatically if the ``--video-sync=display-adrop`` option is used. Do not use this filter (or the given option); they are extremely low quality. --- ## File: DOCS/man/ao.rst AUDIO OUTPUT DRIVERS ==================== Audio output drivers are interfaces to different audio output facilities. The syntax is: ``--ao=`` Specify a priority list of audio output drivers to be used. If the list has a trailing ',', mpv will fall back on drivers not contained in the list. This is an object settings list option. See `List Options`_ for details. .. note:: See ``--ao=help`` for a list of compiled-in audio output drivers sorted by autoprobe order. Note that the default audio output driver is subject to change, and must not be relied upon. If a certain AO needs to be used, it must be explicitly specified. Available audio output drivers are: ``alsa`` ALSA audio output driver. The following global options are supported by this audio output: ``--alsa-resample=yes`` Enable ALSA resampling plugin. (This is disabled by default, because some drivers report incorrect audio delay in some cases.) ``--alsa-mixer-device=`` Set the mixer device used with ``ao-volume`` (default: ``default``). ``--alsa-mixer-name=`` Set the name of the mixer element (default: ``Master``). This is for example ``PCM`` or ``Master``. ``--alsa-mixer-index=`` Set the index of the mixer channel (default: 0). Consider the output of "``amixer scontrols``", then the index is the number that follows the name of the element. ``--alsa-non-interleaved`` Allow output of non-interleaved formats (if the audio decoder uses this format). Currently disabled by default, because some popular ALSA plugins are utterly broken with non-interleaved formats. ``--alsa-ignore-chmap`` Don't read or set the channel map of the ALSA device - only request the required number of channels, and then pass the audio as-is to it. This option most likely should not be used. It can be useful for debugging, or for static setups with a specially engineered ALSA configuration (in this case you should always force the same layout with ``--audio-channels``, or it will work only for files which use the layout implicit to your ALSA device). ``--alsa-buffer-time=`` Set the requested buffer time in microseconds. A value of 0 skips requesting anything from the ALSA API. This and the ``--alsa-periods`` option uses the ALSA ``near`` functions to set the requested parameters. If doing so results in an empty configuration set, setting these parameters is skipped. Both options control the buffer size. A low buffer size can lead to higher CPU usage and audio dropouts, while a high buffer size can lead to higher latency in volume changes and other filtering. ``--alsa-periods=`` Number of periods requested from the ALSA API. See ``--alsa-buffer-time`` for further remarks. .. warning:: To get multichannel/surround audio, use ``--audio-channels=auto``. The default for this option is ``auto-safe``, which makes this audio output explicitly reject multichannel output, as there is no way to detect whether a certain channel layout is actually supported. You can also try `using the upmix plugin `_. This setup enables multichannel audio on the ``default`` device with automatic upmixing with shared access, so playing stereo and multichannel audio at the same time will work as expected. ``oss`` OSS audio output driver ``jack`` JACK (Jack Audio Connection Kit) audio output driver. The following global options are supported by this audio output: ``--jack-port=`` Connects to the ports with the given name (default: physical ports). ``--jack-name=`` Client name that is passed to JACK (default: ``mpv``). Useful if you want to have certain connections established automatically. ``--jack-autostart=`` Automatically start jackd if necessary (default: disabled). Note that this tends to be unreliable and will flood stdout with server messages. ``--jack-connect=`` Automatically create connections to output ports (default: enabled). When enabled, the maximum number of output channels will be limited to the number of available output ports. ``--jack-std-channel-layout=`` Select the standard channel layout (default: waveext). JACK itself has no notion of channel layouts (i.e. assigning which speaker a given channel is supposed to map to) - it just takes whatever the application outputs, and reroutes it to whatever the user defines. This means the user and the application are in charge of dealing with the channel layout. ``waveext`` uses WAVE_FORMAT_EXTENSIBLE order, which, even though it was defined by Microsoft, is the standard on many systems. The value ``any`` makes JACK accept whatever comes from the audio filter chain, regardless of channel layout and without reordering. This mode is probably not very useful, other than for debugging or when used with fixed setups. ``coreaudio`` (macOS only) Native macOS audio output driver using AudioUnits and the CoreAudio sound server. Automatically redirects to ``coreaudio_exclusive`` when playing compressed formats. The following global options are supported by this audio output: ``--coreaudio-change-physical-format=`` Change the physical format to one similar to the requested audio format (default: no). This has the advantage that multichannel audio output will actually work. The disadvantage is that it will change the system-wide audio settings. This is equivalent to changing the ``Format`` setting in the ``Audio Devices`` dialog in the ``Audio MIDI Setup`` utility. Note that this does not affect the selected speaker setup. ``--coreaudio-spdif-hack=`` Try to pass through AC3/DTS data as PCM. This is useful for drivers which do not report AC3 support. It converts the AC3 data to float, and assumes the driver will do the inverse conversion, which means a typical A/V receiver will pick it up as compressed IEC framed AC3 stream, ignoring that it's marked as PCM. This disables normal AC3 passthrough (even if the device reports it as supported). Use with extreme care. ``coreaudio_exclusive`` (macOS only) Native macOS audio output driver using direct device access and exclusive mode (bypasses the sound server). ``avfoundation`` (macOS only) Native macOS audio output driver using ``AVSampleBufferAudioRenderer`` in AVFoundation, which supports `spatial audio `_. .. warning:: Turning on spatial audio may hang the playback if mpv is not started out of the bundle, though playback with spatial audio off always works. ``audiounit`` (iOS only) Native iOS audio output driver using ``AudioUnits`` and AudioToolbox. ``openal`` OpenAL audio output driver. ``--openal-num-buffers=<2-128>`` Specify the number of audio buffers to use. Lower values are better for lower CPU usage. Default: 4. ``--openal-num-samples=<256-32768>`` Specify the number of complete samples to use for each buffer. Higher values are better for lower CPU usage. Default: 8192. ``--openal-direct-channels=`` Enable OpenAL Soft's direct channel extension when available to avoid tinting the sound with ambisonics or HRTF. Default: yes. ``pulse`` PulseAudio audio output driver The following global options are supported by this audio output: ``--pulse-host=`` Specify the host to use. An empty string uses a local connection, "localhost" uses network transfer (most likely not what you want). ``--pulse-buffer=<1-2000|native>`` Set the audio buffer size in milliseconds. A higher value buffers more data, and has a lower probability of buffer underruns. A smaller value makes the audio stream react faster, e.g. to playback speed changes. "native" lets the sound server determine buffers. ``--pulse-latency-hacks=`` Enable hacks to workaround PulseAudio timing bugs (default: yes). If enabled, mpv will do elaborate latency calculations on its own. If disabled, it will use PulseAudio automatically updated timing information. Disabling this might help with e.g. networked audio or some plugins, while enabling it might help in some unknown situations (it is currently enabled due to known bugs with PulseAudio 16.0). ``--pulse-allow-suspended=`` Allow mpv to use PulseAudio even if the sink is suspended (default: no). Can be useful if PulseAudio is running as a bridge to jack and mpv has its sink-input set to the one jack is using. ``pipewire`` PipeWire audio output driver The following global options are supported by this audio output: ``--pipewire-buffer=<1-2000|native>`` Set the audio buffer size in milliseconds. A higher value buffers more data, and has a lower probability of buffer underruns. A smaller value makes the audio stream react faster, e.g. to playback speed changes. "native" lets the sound server determine buffers. ``--pipewire-remote=`` Specify the PipeWire remote daemon name to connect to via local UNIX sockets. An empty string uses the default remote named ``pipewire-0``. ``--pipewire-volume-mode=`` Specify if the ``ao-volume`` property should apply to the channel volumes or the global volume. By default the channel volumes are used. ``sdl`` SDL 2.0+ audio output driver. Should work on any platform supported by SDL 2.0, but may require the ``SDL_AUDIODRIVER`` environment variable to be set appropriately for your system. .. note:: This driver is for compatibility with extremely foreign environments, such as systems where none of the other drivers are available. The following global options are supported by this audio output: ``--sdl-buflen=`` Sets the audio buffer length in seconds. Is used only as a hint by the sound system. Playing a file with ``-v`` will show the requested and obtained exact buffer size. A value of 0 selects the sound system default. ``null`` Produces no audio output but maintains video playback speed. You can use ``--ao=null --ao-null-untimed`` for benchmarking. The following global options are supported by this audio output: ``--ao-null-untimed`` Do not simulate timing of a perfect audio device. This means audio decoding will go as fast as possible, instead of timing it to the system clock. ``--ao-null-buffer`` Simulated buffer length in seconds. ``--ao-null-outburst`` Simulated chunk size in samples. ``--ao-null-speed`` Simulated audio playback speed as a multiplier. Usually, a real audio device will not go exactly as fast as the system clock. It will deviate just a little, and this option helps to simulate this. ``--ao-null-latency`` Simulated device latency. This is additional to EOF. ``--ao-null-broken-eof`` Simulate broken audio drivers, which always add the fixed device latency to the reported audio playback position. ``--ao-null-broken-delay`` Simulate broken audio drivers, which don't report latency correctly. ``--ao-null-channel-layouts`` If not empty, this is a ``,`` separated list of channel layouts the AO allows. This can be used to test channel layout selection. ``--ao-null-format`` Force the audio output format the AO will accept. If unset accepts any. ``pcm`` Raw PCM/WAVE file writer audio output The following global options are supported by this audio output: ``--ao-pcm-waveheader=`` Include or do not include the WAVE header (default: included). When not included, raw PCM will be generated. ``--ao-pcm-file=`` Write the sound to ```` instead of the default ``audiodump.wav``. If ``no-waveheader`` is specified, the default is ``audiodump.pcm``. ``--ao-pcm-append=`` Append to the file, instead of overwriting it. Always use this with the ``no-waveheader`` option - with ``waveheader`` it's broken, because it will write a WAVE header every time the file is opened. ``sndio`` Audio output to the OpenBSD sndio sound system (Note: only supports mono, stereo, 4.0, 5.1 and 7.1 channel layouts.) ``wasapi`` Audio output to the Windows Audio Session API. The following global options are supported by this audio output: ``--wasapi-exclusive-buffer=`` Set buffer duration in exclusive mode (i.e., with ``--audio-exclusive=yes``). ``default`` and ``min`` use the default and minimum device period reported by WASAPI, respectively. You can also directly specify the buffer duration in microseconds, in which case a duration shorter than the minimum device period will be rounded up to the minimum period. The default buffer duration should provide robust playback in most cases, but reportedly on some devices there are glitches following stream resets under the default setting. In such cases, specifying a shorter duration might help. --- ## File: DOCS/man/changes.rst CHANGELOG ========= There is no real changelog, but you can look at the following things: * The release changelog, which should contain most user-visible changes, including new features and bug fixes: https://github.com/mpv-player/mpv/releases * The git log, which is the "real" changelog * The file https://github.com/mpv-player/mpv/blob/master/DOCS/interface-changes.rst documents changes to the command and user interface, such as options and properties. * C API changes are listed in https://github.com/mpv-player/mpv/blob/master/DOCS/client-api-changes.rst * The file ``mplayer-changes.rst`` in the ``DOCS`` sub directory on the git repository, which used to be in place of this section. It documents some changes that happened since mplayer2 forked off MPlayer. (Not updated anymore.) --- ## File: DOCS/man/commands.rst CONSOLE COMMANDS ================ This script allows running and completing input commands in the console interactively, and also adds mpv's log to the console's log. Keybindings ----------- \` Open the console to enter commands. Commands -------- ``script-binding commands/open`` Open the console to enter commands. ``script-message-to commands type []`` Show the console and pre-fill it with the provided text, optionally specifying the initial cursor position as a positive integer starting from 1. The console is automatically closed after running the command. .. admonition:: Examples for input.conf ``% script-message-to commands type "seek absolute-percent" 6`` Enter a percent position to seek to. ``Ctrl+o script-message-to commands type "loadfile ''" 11`` Enter a file or URL to play, with autocompletion of paths in the filesystem. Configuration ------------- This script can be customized through a config file ``script-opts/commands.conf`` placed in mpv's user directory and through the ``--script-opts`` command-line option. The configuration syntax is described in `mp.options functions`_. Configurable Options ~~~~~~~~~~~~~~~~~~~~ ``persist_history`` Default: no Whether to save the command history to a file and load it. ``history_path`` Default: ``~~state/command_history.txt`` The file path for ``persist_history`` (see `FILES`_). ``remember_input`` Default: yes Whether to remember the input line and cursor position when closing the console, and prefill it the next time it is opened. --- ## File: DOCS/man/console.rst CONSOLE ======= This script provides the ability to process the user's textual input to other scripts through the ``mp.input`` API. It can be displayed on both the video window and the terminal. It can be disabled entirely using the ``--load-console=no`` option. Console can either process free-form text or select from a predefined list of items. Free-form text mode keybindings ------------------------------- ESC and Ctrl+[ Hide the console. ENTER, Ctrl+j and Ctrl+m Select the first completion if one wasn't already manually selected, and run the typed command. Shift+ENTER Type a literal newline character. LEFT and Ctrl+b Move the cursor to the previous character. RIGHT and Ctrl+f Move the cursor to the next character. Ctrl+LEFT and Alt+b Move the cursor to the beginning of the current word, or if between words, to the beginning of the previous word. Ctrl+RIGHT and Alt+f Move the cursor to the end of the current word, or if between words, to the end of the next word. HOME and Ctrl+a Move the cursor to the start of the current line. END and Ctrl+e Move the cursor to the end of the current line. BACKSPACE and Ctrl+h Delete the previous character. Ctrl+d Hide the console if the current line is empty, otherwise delete the next character. Ctrl+BACKSPACE and Ctrl+w Delete text from the cursor to the beginning of the current word, or if between words, to the beginning of the previous word. Ctrl+DEL and Alt+d Delete text from the cursor to the end of the current word, or if between words, to the end of the next word. Ctrl+u Delete text from the cursor to the beginning of the current line. Ctrl+k Delete text from the cursor to the end of the current line. Ctrl+c Clear the current line. UP and Ctrl+p Move back in the command history. DOWN and Ctrl+n Move forward in the command history. PGUP Go to the first command in the history. PGDN Stop navigating the command history. Ctrl+r Search the command history. See `SELECT`_ for the key bindings in this mode. Shift+UP Scroll the log one line up. Shift+DOWN Scroll the log one line down. INSERT Toggle insert mode. Ctrl+v Paste text (uses the clipboard on X11 and Wayland). Shift+INSERT Paste text (uses the primary selection on X11 and Wayland). Ctrl+y Copy the current line to the clipboard. TAB and Ctrl+i Cycle through completions. Shift+TAB Cycle through the completions backwards. Ctrl+l Clear all log messages from the console. MBTN_MID Paste text (uses the primary selection on X11 and Wayland). WHEEL_UP Move back in the command history. WHEEL_DOWN Move forward in the command history. Known issues ------------ - Non-ASCII keyboard input has restrictions - The cursor keys move between Unicode code-points, not grapheme clusters Configuration ------------- This script can be customized through a config file ``script-opts/console.conf`` placed in mpv's user directory and through the ``--script-opts`` command-line option. The configuration syntax is described in `mp.options functions`_. Note that ``mp.input`` clients can selectively override these options. Configurable Options ~~~~~~~~~~~~~~~~~~~~ ``monospace_font`` Default: platform dependent The monospace font used when there are completions to align in a grid. When there are no completions, ``--osd-font`` is used. ``font_size`` Default: 24 The font size. This will be multiplied by ``display-hidpi-scale`` when the console is not scaled with the window. ``border_size`` Default: 1.65 The font border size. ``background_alpha`` Default: 80 The transparency of the menu's background. Ranges from 0 (opaque) to 255 (fully transparent). ``gap`` Default: 0.2 The gap between menu items, specified as a percentage the font size. ``padding`` Default: 10 The padding of the menu. ``menu_outline_size`` Default: 0 The size of the menu's border. ``menu_outline_color`` Default: #FFFFFF The color of the menu's border. ``corner_radius`` Default: 8 The radius of the menu's corners. ``margin_x`` Default: same as ``--osd-margin-x`` The margin from the left of the window. ``margin_y`` Default: same as ``--osd-margin-y`` The margin from the bottom of the window. ``scale_with_window`` Default: ``auto`` Whether to scale the console with the window height. Can be ``yes``, ``no``, or ``auto``, which follows the value of ``--osd-scale-by-window``. ``focused_color`` Default: ``#222222`` The color of the focused item. ``focused_back_color`` Default: ``#FFFFFF`` The background color of the focused item. ``match_color`` Default: ``#0088FF`` The color of characters that match the searched string. ``exact_match`` Default: no Whether to match menu search queries exactly instead of fuzzily. Without this option, prefixing queries with ``'`` enables exact matching. ``case_sensitive`` Default: no Whether exact searches are case sensitive. Only works with ASCII characters. ``history_dedup`` Default: true Remove duplicate entries in history as to only keep the latest one. ``font_hw_ratio`` Default: auto The ratio of font height to font width. Adjusts grid width of completions. Values in the range 1.8..2.5 make sense for common monospace fonts. --- ## File: DOCS/man/encode.rst ENCODING ======== You can encode files from one format/codec to another using this facility. ``--o=`` Enables encoding mode and specifies the output file name. ``--of=`` 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. ``--ofopts=`` Specifies the output format options for libavformat. See ``--ofopts=help`` for a full list of supported options. This is a key/value list option. See `List Options`_ for details. ``--ofopts-add=