pax_global_header00006660000000000000000000000064130277427060014522gustar00rootroot0000000000000052 comment=10a005df0c981050afc35184a42173bea7ea2527 mpv-0.23.0/000077500000000000000000000000001302774270600124065ustar00rootroot00000000000000mpv-0.23.0/.github/000077500000000000000000000000001302774270600137465ustar00rootroot00000000000000mpv-0.23.0/.github/ISSUE_TEMPLATE000066400000000000000000000012651302774270600160600ustar00rootroot00000000000000### mpv version and platform If you're not using git master or the latest release, update. ### Reproduction steps ### Expected behavior ### Actual behavior ### Log file Make a log file made with -v or --log-file=output.txt, paste it to http://sprunge.us or a similar site, and replace this text with a link to it. Providing a log file is strongly encouraged. It is very helpful for reproducing bugs or getting important technical context. Without a log it might not be possible to analyze and fix certain bugs. ### Sample files Sample files needed to reproduce this issue can be uploaded to https://0x0.st/ or similar sites. (Only needed if the issue cannot be reproduced without it.)mpv-0.23.0/.github/PULL_REQUEST_TEMPLATE000066400000000000000000000006611302774270600171530ustar00rootroot00000000000000Ideally, you shouldn't need enter any text here, and your commit messages should explain your changes sufficiently (especially why they are needed). Read https://github.com/mpv-player/mpv/blob/master/DOCS/contribute.md for coding style and development conventions. Remove this text block, but if you haven't agreed to it before, leave the following sentence in place: I agree that my changes can be relicensed to LGPL 2.1 or later. mpv-0.23.0/.gitignore000066400000000000000000000006461302774270600144040ustar00rootroot00000000000000*.o *.a *.d *.exe *.pyc .depend /config.h /config.mak /config.log /mpv /mpv.app /version.h /input/input_conf.h /tags /TAGS /video/out/x11_icon.inc /demux/ebml_defs.c /demux/ebml_types.h /sub/osd_font.h /player/lua/*.inc /player/builtin_conf.inc /DOCS/man/mpv.1 /DOCS/man/mpv.aux /DOCS/man/mpv.log /DOCS/man/mpv.out /DOCS/man/mpv.pdf /DOCS/man/mpv.toc /waf /waf-* /waf3-* /build /.waf* /.lock-waf_* /old_build /Makefile mpv-0.23.0/.travis.yml000066400000000000000000000030021302774270600145120ustar00rootroot00000000000000language: c os: - linux - osx env: matrix: - LIBAV=libav-stable - LIBAV=libav-git - LIBAV=ffmpeg-stable - LIBAV=ffmpeg-git global: # Coverity token - secure: "H21mSRlMhk4BKS0xHZvCFGJxteCP0hRVUxTuNfM2Z9HBsyutuLEYMtViLO86VtM+Tqla3xXPzUdS4ozLwI72Ax/5ZUDXACROj73yW6QhFB5D6rLut12+FjqC7M33Qv2hl0xwgNBmR5dsm1ToP37+Wn+ecJQNvN8fkTXF+HVzOEw=" # Travis token for mpv.io - secure: "nlTVLJK6kRhtXvhKCoJ3YdFGHuKaq/eHowfPw25hqRWuBOZd+HjHY5KIYjV7SxuKFDpJE4GpNcvA3Q31nsqomxpkLYgrwjg6TSazN7ZP+x85ZgV1QGFebrPfGm2n5UR5CAPAwFoeF3pZheLi4bajVzwq1fWW+x3grS188P9OZso=" compiler: - clang - gcc branches: only: - master - ci - coverity_scan matrix: exclude: - os: osx env: LIBAV=libav-stable - os: osx env: LIBAV=libav-git - os: osx env: LIBAV=ffmpeg-git - os: osx compiler: gcc - os: linux env: LIBAV=ffmpeg-stable - os: linux compiler: clang before_install: TOOLS/travis-deps libass-stable $LIBAV script: - ./bootstrap.py - ./waf configure - ./waf build after_script: TOOLS/travis-rebuild-website notifications: email: false irc: channels: - "irc.freenode.org#mpv-devel" on_success: change on_failure: always addons: coverity_scan: project: name: "mpv-player/mpv" description: "Build submitted via Travis CI" notification_email: mpv-team@googlegroups.com build_command_prepend: "./bootstrap.py && ./waf configure" build_command: "./waf build" branch_pattern: coverity_scan mpv-0.23.0/Copyright000066400000000000000000000027131302774270600143040ustar00rootroot00000000000000mpv is a fork of mplayer2, which is a fork of MPlayer. mpv as a whole is licensed as GPL version 2 or later (see LICENSE). Most source files are GPLv2+, but some files are available under a more liberal license, such as LGPLv2.1+, BSD, MIT, ISC, and possibly others. Look at the copyright header of each source file, and grep the sources for "Copyright" if you need to know details. Files without Copyright notice are licensed as LGPLv2.1+. All new contributions must be LGPLv2.1+ licensed, or if the changes are done on GPL code, must come with the implicit agreement that the project can relicense the code to LGPLv2.1+ at a later point without asking the contributor. (This is a safeguard for making potential relicensing of the project to LGPLv2.1+ easier.) Using a more liberal license compatible to LGPLv2.1+ is also ok. For information about authors and contributors, consult the git log, which contains the complete SVN and CVS history as well. Note that mplayer2 as a whole is licensed under GPLv3+. This is because it uses a copy of talloc (part of Samba), which is LGPLv3+, and the next compatible license for this mix is GPLv3+. MPlayer as a whole is licensed under GPLv2 (incompatible to GPLv3!), because some files are licensed to GPLv2 (and _not_ any later version of the license). In particular, this affects the file libmpdemux/demux_ty_osd.c. It is disabled under mplayer2, and has been removed from mpv. "v2.1+" in this context means "version 2.1 or later". mpv-0.23.0/DOCS/000077500000000000000000000000001302774270600131365ustar00rootroot00000000000000mpv-0.23.0/DOCS/client-api-changes.rst000066400000000000000000000203731302774270600173300ustar00rootroot00000000000000Introduction ============ This file lists all changes that can cause compatibility issues when using mpv through the client API (libmpv and ``client.h``). Since the client API interfaces to input handling (commands, properties) as well as command line options, you should also look at ``interface-changes.rst``. Normally, changes to the C API that are incompatible to previous iterations receive a major version bump (i.e. the first version number is increased), while C API additions bump the minor version (i.e. the second number is increased). Changes to properties/commands/options may also lead to a minor version bump, in particular if they are incompatible. The version number is the same as used for MPV_CLIENT_API_VERSION (see ``client.h`` how to convert between major/minor version numbers and the flat 32 bit integer). Also, read the section ``Compatibility`` in ``client.h``. Options, commands, properties ============================= Changes to these are not listed here, but in ``interface-changes.rst``. (Before client API version 1.17, they were listed here partially.) This listing includes changes to the bare C API and behavior only, not what you can access with them. API changes =========== :: --- mpv 0.23.0 --- 1.24 - the deprecated mpv_suspend() and mpv_resume() APIs now do nothing. --- mpv 0.22.0 --- 1.23 - deprecate setting "no-" options via mpv_set_option*(). For example, instead of "no-video=" you should set "video=no". - do not override the SIGPIPE signal handler anymore. This was done as workaround for the FFmpeg TLS code, which has been fixed long ago. - deprecate mpv_suspend() and mpv_resume(). They will be stubbed out in mpv 0.23.0. - make mpv_set_property() work to some degree before mpv_initialize(). It can now be used instead of mpv_set_option(). - semi-deprecate mpv_set_option()/mpv_set_option_string(). You should use mpv_set_property() instead. There are some deprecated properties which conflict with some options (see client.h remarks on mpv_set_option()), for which mpv_set_option() might still be required. In future mpv releases, the conflicting deprecated options/properties will be removed, and mpv_set_option() will internally translate API calls to mpv_set_property(). - qthelper.hpp: deprecate get_property_variant, set_property_variant, set_option_variant, command_variant, and replace them with get_property, set_property, command. --- mpv 0.19.0 --- 1.22 - add stream_cb API for custom protocols --- mpv 0.18.1 --- ---- - remove "status" log level from mpv_request_log_messages() docs. This is 100% equivalent to "v". The behavior is still the same, thus no actual API change. --- mpv 0.18.0 --- 1.21 - mpv_set_property() changes behavior with MPV_FORMAT_NODE. Before this change it rejected mpv_nodes with format==MPV_FORMAT_STRING if the property was not a string or did not have special mechanisms in place the function failed. Now it always invokes the option string parser, and mpv_node with a basic data type works exactly as if the function is invoked with that type directly. This new behavior is equivalent to mpv_set_option(). This also affects the mp.set_property_native() Lua function. - generally, setting choice options/properties with "yes"/"no" options can now be set as MPV_FORMAT_FLAG - reading a choice property as MPV_FORMAT_NODE will now return a MPV_FORMAT_FLAG value if the choice is "yes" (true) or "no" (false) This implicitly affects Lua and JSON IPC interfaces as well. - big changes to vo-cmdline on vo_opengl and vo_opengl_hq (but not vo_opengl_cb): options are now normally not reset, but applied on top of the current options. The special undocumented value "-" still works, but now resets all options to before any vo-cmdline command has been called. --- mpv 0.12.0 --- 1.20 - deprecate "GL_MP_D3D_interfaces"/"glMPGetD3DInterface", and introduce "GL_MP_MPGetNativeDisplay"/"glMPGetNativeDisplay" (this is a backwards-compatible rename) --- mpv 0.11.0 --- --- mpv 0.10.0 --- 1.19 - add "GL_MP_D3D_interfaces" pseudo extension to make it possible to use DXVA2 in OpenGL fullscreen mode in some situations - mpv_request_log_messages() now accepts "terminal-default" as parameter 1.18 - add MPV_END_FILE_REASON_REDIRECT, and change behavior of MPV_EVENT_END_FILE accordingly - a bunch of interface-changes.rst changes 1.17 - mpv_initialize() now blocks SIGPIPE (details see client.h) --- mpv 0.9.0 --- 1.16 - add mpv_opengl_cb_report_flip() - introduce mpv_opengl_cb_draw() and deprecate mpv_opengl_cb_render() - add MPV_FORMAT_BYTE_ARRAY 1.15 - mpv_initialize() will now load config files. This requires setting the "config" and "config-dir" options. In particular, it will load mpv.conf. - minor backwards-compatible change to the "seek" and "screenshot" commands (new flag syntax, old additional args deprecated) --- mpv 0.8.0 --- 1.14 - add mpv_wait_async_requests() - the --msg-level option changes its native type from a flat string to a key-value list (setting/reading the option as string still works) 1.13 - add MPV_EVENT_QUEUE_OVERFLOW 1.12 - add class Handle to qthelper.hpp - improve opengl_cb.h API uninitialization behavior, and fix the qml example - add mpv_create_client() function 1.11 - add OpenGL rendering interop API - allows an application to combine its own and mpv's OpenGL rendering Warning: this API is not stable yet - anything in opengl_cb.h might be changed in completely incompatible ways in minor API bumps --- mpv 0.7.0 --- 1.10 - deprecate/disable everything directly related to script_dispatch (most likely affects nobody) 1.9 - add enum mpv_end_file_reason for mpv_event_end_file.reason - add MPV_END_FILE_REASON_ERROR and the mpv_event_end_file.error field for slightly better error reporting on playback failure - add --stop-playback-on-init-failure option, and make it the default behavior for libmpv only - add qthelper.hpp set_option_variant() - mark the following events as deprecated: MPV_EVENT_TRACKS_CHANGED MPV_EVENT_TRACK_SWITCHED MPV_EVENT_PAUSE MPV_EVENT_UNPAUSE MPV_EVENT_METADATA_UPDATE MPV_EVENT_CHAPTER_CHANGE They are handled better with mpv_observe_property() as mentioned in the documentation comments. They are not removed and still work. 1.8 - add qthelper.hpp 1.7 - add mpv_command_node(), mpv_command_node_async() 1.6 - modify "core-idle" property behavior - MPV_EVENT_LOG_MESSAGE now always sends complete lines - introduce numeric log levels (mpv_log_level) --- mpv 0.6.0 --- 1.5 - change in X11 and "--wid" behavior again. The previous change didn't work as expected, and now the behavior can be explicitly controlled with the "input-x11-keyboard" option. This is only a temporary measure until XEmbed is implemented and confirmed working. Note: in 1.6, "input-x11-keyboard" was renamed to "input-vo-keyboard", although the old option name still works. 1.4 - subtle change in X11 and "--wid" behavior (this change was added to 0.5.2, and broke some things, see #1090) --- mpv 0.5.0 --- 1.3 - add MPV_MAKE_VERSION() 1.2 - remove "stream-time-pos" property (no replacement) 1.1 - remap dvdnav:// to dvd:// - add "--cache-file", "--cache-file-size" - add "--colormatrix-primaries" (and property) - add "primaries" sub-field to image format properties - add "playback-time" property - extend the "--start" option; a leading "+", which was previously insignificant is now significant - add "cache-free" and "cache-used" properties - OSX: the "coreaudio" AO spdif code is split into a separate AO --- mpv 0.4.0 --- 1.0 - the API is declared stable mpv-0.23.0/DOCS/compile-windows.md000066400000000000000000000155411302774270600166060ustar00rootroot00000000000000Compiling for Windows ===================== Compiling for Windows is supported with MinGW-w64. This can be used to produce both 32-bit and 64-bit executables, and it works for building on Windows and cross-compiling from Linux and Cygwin. MinGW-w64 is available from: http://mingw-w64.sourceforge.net. While building a complete MinGW-w64 toolchain yourself is possible, there are a few build environments and scripts to help ease the process, such as MSYS2 and MXE. Note that MinGW environments included in Linux distributions are often broken, outdated and useless, and usually don't use MinGW-w64. **Warning**: the original MinGW (http://www.mingw.org) is unsupported. Cross-compilation ================= When cross-compiling, you have to run mpv's configure with these arguments: ```bash DEST_OS=win32 TARGET=i686-w64-mingw32 ./waf configure ``` [MXE](http://mxe.cc) makes it very easy to bootstrap a complete MingGW-w64 environment from a Linux machine. See a working example below. Alternatively, you can try [mingw-w64-cmake](https://github.com/lachs0r/mingw-w64-cmake), which bootstraps a MinGW-w64 environment and builds mpv and dependencies. Example with MXE ---------------- ```bash # Before starting, make sure you install MXE prerequisites. MXE will download # and build all target dependencies, but no host dependencies. For example, # you need a working compiler, or MXE can't build the crosscompiler. # # Refer to # # http://mxe.cc/#requirements # # Scroll down for disto/OS-specific instructions to install them. # Download MXE. Note that compiling the required packages requires about 1.4 GB # or more! cd /opt git clone https://github.com/mxe/mxe mxe cd mxe # Set build options. # The JOBS environment variable controls threads to use when building. DO NOT # use the regular `make -j4` option with MXE as it will slow down the build. # Alternatively, you can set this in the make command by appending "JOBS=4" # to the end of command: echo "JOBS := 4" >> settings.mk # The MXE_TARGET environment variable builds MinGW-w64 for 32 bit targets. # Alternatively, you can specify this in the make command by appending # "MXE_TARGETS=i686-w64-mingw32" to the end of command: echo "MXE_TARGETS := i686-w64-mingw32.static" >> settings.mk # If you want to build 64 bit version, use this: # echo "MXE_TARGETS := x86_64-w64-mingw32.static" >> settings.mk # Build required packages. The following provide a minimum required to build # a reasonable mpv binary (though not an absolute minimum). make gcc ffmpeg libass jpeg lua # Add MXE binaries to $PATH export PATH=/opt/mxe/usr/bin/:$PATH # Build mpv. The target will be used to automatically select the name of the # build tools involved (e.g. it will use i686-w64-mingw32.static-gcc). cd .. git clone https://github.com/mpv-player/mpv.git cd mpv python ./bootstrap.py DEST_OS=win32 TARGET=i686-w64-mingw32.static ./waf configure # Or, if 64 bit version, # DEST_OS=win32 TARGET=x86_64-w64-mingw32.static ./waf configure ./waf build ``` Native compilation with MSYS2 ============================= For Windows developers looking to get started quickly, MSYS2 can be used to compile mpv natively on a Windows machine. The MSYS2 repositories have binary packages for most of mpv's dependencies, so the process should only involve building mpv itself. To build 64-bit mpv on Windows: Installing MSYS2 ---------------- 1. Download an installer from https://msys2.github.io/ It doesn't matter whether the i686 or the x86_64 version is used. Both can build 32-bit and 64-bit binaries when running on a 64-bit version of Windows. 2. Start a MinGW-w64 shell (``mingw64.exe``). Note that this is different from the MSYS2 shell that is started from the final installation dialog. For a 32-bit build, use ``mingw32.exe``. Updating MSYS2 -------------- To prevent errors during post-install, the MSYS2 core runtime must be updated separately. ```bash # Check for core updates. If instructed, close the shell window and reopen it # before continuing. pacman -Syu # Update everything else pacman -Su ``` Installing mpv dependencies --------------------------- ```bash # Install MSYS2 build dependencies and a MinGW-w64 compiler pacman -S git mingw-w64-x86_64-pkg-config python mingw-w64-x86_64-gcc # Install the most important MinGW-w64 dependencies. libass, libbluray and # lcms2 are also pulled in as dependencies of ffmpeg. pacman -S mingw-w64-x86_64-ffmpeg mingw-w64-x86_64-libjpeg-turbo mingw-w64-x86_64-lua51 # Install additional (optional) dependencies pacman -S mingw-w64-x86_64-libdvdnav mingw-w64-x86_64-libguess mingw-w64-x86_64-angleproject-git ``` For a 32-bit build, install ``mingw-w64-i686-*`` packages instead. Building mpv ------------ Clone the latest mpv from git and install waf: ```bash git clone https://github.com/mpv-player/mpv.git && cd mpv ./bootstrap.py ``` Finally, compile and install mpv. Binaries will be installed to ``/mingw64/bin``. ```bash # For a 32-bit build, use --prefix=/mingw32 instead ./waf configure CC=gcc.exe --check-c-compiler=gcc --prefix=/mingw64 ./waf install ``` Or, compile and install both libmpv and mpv: ```bash ./waf configure CC=gcc.exe --check-c-compiler=gcc --enable-libmpv-shared --prefix=/mingw64 ./waf install # waf installs libmpv dll to the wrong directory, so fix it up mv -f /mingw64/lib/mpv-1.dll /mingw64/bin/ ``` Linking libmpv with MSVC programs --------------------------------- You can build C++ programs in Visual Studio and link them with libmpv. To do this, you need a Visual Studio which supports ``stdint.h`` (recent ones do), and you need to create a import library for the mpv DLL: ```bash lib /def:mpv.def /name:mpv-1.dll /out:mpv.lib /MACHINE:X64 ``` The string in the ``/name:`` parameter must match the filename of the DLL (this is simply the filename the MSVC linker will use). The ``mpv.def`` can be retrieved from the mpv build directory, or can be produced by MingGW's gendef.exe helper from the mpv DLL. Static linking is not possible. Running mpv ----------- If you want to run mpv from the MinGW-w64 shell, you will find the experience much more pleasant if you use the ``winpty`` utility ```bash pacman -S winpty winpty mpv.com ToS-4k-1920.mov ``` If you want to move / copy ``mpv.exe`` and ``mpv.com`` to somewhere other than ``/mingw64/bin/`` for use outside the MinGW-w64 shell, they will still depend on DLLs in that folder. The simplest solution is to add ``C:\msys64\mingw64\bin`` to the windows system ``%PATH%``. Beware though that this can cause problems or confusion in Cygwin if that is also installed on the machine. Use of the ANGLE OpenGL backend requires a copy of the D3D compiler DLL that matches the version of the D3D SDK that ANGLE was built with (``d3dcompiler_43.dll`` in case of MinGW-built ANGLE) in the path or in the same folder as mpv. It must be of the same architecture (x86_64 / i686) as the mpv you compiled. You can find copies here: https://mpv.srsfckn.biz/d3dcompiler.7z mpv-0.23.0/DOCS/contribute.md000066400000000000000000000136351302774270600156460ustar00rootroot00000000000000How to contribute ================= General ------- The main contact for mpv development is IRC, specifically #mpv and #mpv-devel on Freenode. Sending patches --------------- - Make a github pull request, or send a link to a plaintext patch created with ``git format-patch``. diffs posted as pastebins (especially if the http link returns HTML) just cause extra work for everyone, because they lack commit message and authorship information. - All new code must be LGPLv2.1+ licensed, or come with the implicit agreement that it will be relicensed to LGPLv2.1+ later (see ``Copyright`` in the repository root directory). - When creating pull requests, be sure to test your changes. If you didn't, please say so in the pull request message. - Write informative commit messages. Use present tense to describe the situation with the patch applied, and past tense for the situation before the change. - The subject line (the first line in a commit message) should contain a prefix identifying the sub system, followed by a short description what impact this commit has. This subject line shouldn't be longer than 72 characters, because it messes up the output of many git tools otherwise. For example, you fixed a crash in af_volume.c: - Bad: ``fixed the bug (wtf?)`` - Good: ``af_volume: fix crash due to null pointer access`` Having a prefix gives context, and is especially useful when trying to find a specific change by looking at the history, or when running ``git blame``. - The body of the commit message (everything else after the subject line) should be as informative as possible and contain everything that isn't obvious. Don't hesitate to dump as much information as you can - it doesn't cost you anything. Put some effort into it. If someone finds a bug months or years later, and finds that it's caused by your commit (even though your commit was supposed to fix another bug), it would be bad if there wasn't enough information to test the original bug. The old bug might be reintroduced while fixing the new bug. The commit message should be wrapped on 72 characters per line, because git tools usually do not break text automatically. On the other hand, you do not need to break text that would be unnatural to break (like data for test cases, or long URLs). Important: put an empty line between the subject line and the commit message. If this is missing, it will break display in common git tools. - Try to separate cosmetic and functional changes. It's ok to make a few additional cosmetic changes in the same file you're working on. But don't do something like reformatting a whole file, and hiding an actual functional change in the same commit. - If you add a new command line option, document it in options.rst. If you add a new input property, document it in input.rst. Changes to the user interface (options, properties, commands) should be documented in interface-changes.rst. Changes to libmpv should be documented in client-api-changes.rst. Code formatting --------------- mpv uses C99 with K&R formatting, with some exceptions. - Use the K&R indent style. - Use 4 spaces of indentation, never use tabs (except in Makefiles). - Add a single space between keywords and binary operators. There are some other cases where spaces should be added. Example: ```C if ((a * b) > c) { // code some_function(a, b, c); } ``` - Break lines on 80 columns. There is a hard limit of 85 columns. You may ignore this limit if there's a strong case that not breaking the line will increase readability. Going over 85 columns might provoke endless discussions about whether such a limit is needed or not, so avoid it. - If the body of an if/for/while statement has more than 1 physical lines, then always add braces, even if they're technically redundant. Bad: ```C if (a) // do something if b if (b) do_something(); ``` Good: ```C if (a) { // do something if b if (b) do_something(); } ``` - If the body of an if statement uses braces, the else branch should also use braces (and reverse). Example: ```C if (a) { // do something something(); something_else(); } else { one_line(); } ``` - If an if condition spans multiple physical lines, then put the opening brace for the if body on the next physical line. (Also, preferably always add a brace, even if technically none is needed.) Example: ```C if (very_long_condition_a && very_long_condition_b) { code(); } else { ... } ``` - Remove any trailing whitespace. - If the file you're editing uses formatting different from from what is described here, it's probably an old file from times when nobody followed a consistent style. You're free to use the existing style, or the new style, or to send a patch to reformat the file to the new style before making functional changes. General coding -------------- - Use C99. Also freely make use of C99 features if it's appropriate, such as stdbool.h. - Don't use GNU-only features. In some cases they may be warranted, if they are optional (such as attributes enabling printf-like format string checks). But in general, standard C99 should be used. - The same applies to libc functions. We have to be Windows-compatible too. Use functions guaranteed by C99 or POSIX only, unless your use is guarded by a configure check. - Prefer fusing declaration and initialization, rather than putting declarations on the top of a block. Obvious data flow is more important than avoiding mixing declarations and statements, which is just a C90 artifact. - tech-overview.txt might help to get an overview how mpv is structured. - If you add features that require intrusive changes, discuss them on the dev channel first. There might be a better way to add a feature and it can avoid wasted work. mpv-0.23.0/DOCS/edl-mpv.rst000066400000000000000000000104761302774270600152440ustar00rootroot00000000000000EDL files ========= EDL files basically concatenate ranges of video/audio from multiple source files into a single continuous virtual file. Each such range is called a segment, and consists of source file, source offset, and segment length. For example:: # mpv EDL v0 f1.mkv,10,20 f2.mkv f1.mkv,40,10 This would skip the first 10 seconds of the file f1.mkv, then play the next 20 seconds, then switch to the file f2.mkv and play all of it, then switch back to f1.mkv, skip to the 40 second mark, and play 10 seconds, and then stop playback. The difference to specifying the files directly on command line (and using ``--{ --start=10 --length=20 f1.mkv --}`` etc.) is that the virtual EDL file appears as a virtual timeline (like a single file), instead as a playlist. The general simplified syntax is:: # mpv EDL v0 ,, If the start time is omitted, 0 is used. If the length is omitted, the estimated remaining duration of the source file is used. Note:: Usage of relative or absolute paths as well as any protocol prefixes may be prevented for security reasons. Syntax of mpv EDL files ======================= Generally, the format is relatively strict. No superfluous whitespace (except empty lines and commented lines) are allowed. You must use UNIX line breaks. The first line in the file must be ``# mpv EDL v0``. This designates that the file uses format version 0, which is not frozen yet and may change any time. (If you need a stable EDL file format, make a feature request. Likewise, if you have suggestions for improvements, it's not too late yet.) The rest of the lines belong to one of these classes: 1) An empty or commented line. A comment starts with ``#``, which must be the first character in the line. The rest of the line (up until the next line break) is ignored. An empty line has 0 bytes between two line feed bytes. 2) A segment entry in all other cases. Each segment entry consists of a list of named or unnamed parameters. Parameters are separated with ``,``. Named parameters consist of a name, followed by ``=``, followed by the value. Unnamed parameters have only a value, and the name is implicit from the parameter position. Syntax:: segment_entry ::= ( ',' )* param ::= [ '=' ] ( | '%' '%' ) The ``name`` string can consist of any characters, except ``=%,;\n``. The ``value`` string can consist of any characters except of ``,;\n``. The construct starting with ``%`` allows defining any value with arbitrary contents inline, where ``number`` is an integer giving the number of bytes in ``valuebytes``. If a parameter value contains disallowed characters, it has to be guarded by a length specifier using this syntax. The parameter name defines the meaning of the parameter: 1) ``file``, the source file to use for this segment. 2) ``start``, a time value that specifies the start offset into the source file. 3) ``length``, a time value that specifies the length of the segment. See the section below for the format of timestamps. Unnamed parameters carry implicit names. The parameter position determines which of the parameters listed above is set. For example, the second parameter implicitly uses the name ``start``. Example:: # mpv EDL v0 %18%filename,with,.mkv,10,length=20,param3=%13%value,escaped,param4=value2 this sets ``file`` to ``filename,with,.mkv``, ``start`` to ``10``, ``length`` to ``20``, ``param3`` to ``value,escaped``, ``param4`` to ``value2``. Instead of line breaks, the character ``;`` can be used. Line feed bytes and ``;`` are treated equally. Timestamp format ================ Currently, time values are floating point values in seconds. As an extension, you can set the ``timestamps=chapters`` option. If this option is set, timestamps have to be integers, and refer to chapter numbers, starting with 0. Example:: # mpv EDL v0 file.mkv,2,4,timestamps=chapters Plays chapter 3 and ends with the start of chapter 7 (4 chapters later). Syntax of EDL URIs ================== mpv accepts inline EDL data in form of ``edl://`` URIs. Other than the header, the syntax is exactly the same. It's far more convenient to use ``;`` instead of line breaks, but that is orthogonal. Example: ``edl://f1.mkv,length=5,start=10;f2.mkv,30,20;f3.mkv`` mpv-0.23.0/DOCS/encoding.rst000066400000000000000000000123351302774270600154620ustar00rootroot00000000000000General usage ============= :: mpv infile -o outfile [-of outfileformat] [-ofopts formatoptions] \ [-ofps outfps | -oautofps] [-oharddup] [-ocopyts | -orawts] [-oneverdrop] \ [(any other mpv options)] \ -ovc outvideocodec [-ovcopts outvideocodecoptions] \ -oac outaudiocodec [-oacopts outaudiocodecoptions] Help for these options is provided if giving help as parameter, as in:: mpv -ovc help The suboptions of these generally are identical to ffmpeg's (as option parsing is simply delegated to ffmpeg). The option -ocopyts enables copying timestamps from the source as-is, instead of fixing them to match audio playback time (note: this doesn't work with all output container formats); -orawts even turns off discontinuity fixing. Note that if neither -ofps nor -oautofps is specified, VFR encoding is assumed and the time base is 24000fps. -oautofps sets -ofps to a guessed fps number from the input video. Note that not all codecs and not all formats support VFR encoding, and some which do have bugs when a target bitrate is specified - use -ofps or -oautofps to force CFR encoding in these cases. Of course, the options can be stored in a profile, like this .config/mpv/mpv.conf section:: [myencprofile] vf-add = scale=480:-2 ovc = libx264 ovcopts-add = preset=medium,tune=fastdecode ovcopts-add = crf=23 ovcopts-add = maxrate=1500k,bufsize=1000k,rc_init_occupancy=900k,refs=2 ovcopts-add = profile=baseline oac = aac oacopts-add = b=96k It's also possible to define default encoding options by putting them into the section named ``[encoding]``. (This behavior changed after mpv 0.3.x. In mpv 0.3.x, config options in the default section / no section were applied to encoding. This is not the case anymore.) One can then encode using this profile using the command:: mpv infile -o outfile.mp4 -profile myencprofile Some example profiles are provided in a file etc/encoding-profiles.conf; as for this, see below. Encoding examples ================= These are some examples of encoding targets this code has been used and tested for. Typical MPEG-4 Part 2 ("ASP", "DivX") encoding, AVI container:: mpv infile -o outfile.avi \ -ofps 25 \ -ovc mpeg4 -ovcopts qscale=4 \ -oac libmp3lame -oacopts ab=128k Note: AVI does not support variable frame rate, so -ofps must be used. The frame rate should ideally match the input (25 for PAL, 24000/1001 or 30000/1001 for NTSC) Typical MPEG-4 Part 10 ("AVC", "H.264") encoding, Matroska (MKV) container:: mpv infile -o outfile.mkv \ -ovc libx264 -ovcopts preset=medium,crf=23,profile=baseline \ -oac libvorbis -oacopts qscale=3 Typical MPEG-4 Part 10 ("AVC", "H.264") encoding, MPEG-4 (MP4) container:: mpv infile -o outfile.mp4 \ -ovc libx264 -ovcopts preset=medium,crf=23,profile=baseline \ -oac aac -oacopts ab=128k Typical VP8 encoding, WebM (restricted Matroska) container:: mpv infile -o outfile.mkv \ -of webm \ -ovc libvpx -ovcopts qmin=6,b=1000000k \ -oac libvorbis -oacopts qscale=3 Device targets ============== As the options for various devices can get complex, profiles can be used. An example profile file for encoding is provided in etc/encoding-profiles.conf in the source tree. This file is installed and loaded by default (if libavfilter is enabled at compilation). If you want to modify it, you can replace and it with your own copy by doing:: mkdir -p ~/.mpv cp /etc/mpv/encoding-profiles.conf ~/.mpv/encoding-profiles.conf Refer to the top of that file for more comments - in a nutshell, the following options are added by it:: -profile enc-to-dvdpal DVD-Video PAL, use dvdauthor -v pal+4:3 -a ac3+en -profile enc-to-dvdntsc DVD-Video NTSC, use dvdauthor -v ntsc+4:3 -a ac3+en -profile enc-to-bb-9000 MP4 for Blackberry Bold 9000 -profile enc-to-nok-6300 3GP for Nokia 6300 -profile enc-to-psp MP4 for PlayStation Portable -profile enc-to-iphone MP4 for iPhone -profile enc-to-iphone-4 MP4 for iPhone 4 (double res) -profile enc-to-iphone-5 MP4 for iPhone 5 (even larger res) You can encode using these with a command line like:: mpv infile -o outfile.mp4 -profile enc-to-bb-9000 Of course, you are free to override options set by these profiles by specifying them after the -profile option. What works ========== * Encoding at variable frame rate (default) * Encoding at constant frame rate using -ofps framerate -oharddup * 2-pass encoding (specify flags=+pass1 in the first pass's -ovcopts, specify flags=+pass2 in the second pass) * Hardcoding subtitles using vobsub, ass or srt subtitle rendering (just configure mpv for the subtitles as usual) * Hardcoding any other mpv OSD (e.g. time codes, using -osdlevel 3 and -vf expand=::::1) * Encoding directly from a DVD, network stream, webcam, or any other source mpv supports * Using x264 presets/tunings/profiles (by using profile=, tune=, preset= in the -ovcopts) * Deinterlacing/Inverse Telecine with any of mpv's filters for that * Audio file converting: mpv -o outfile.mp3 infile.flac -no-video -oac libmp3lame -oacopts ab=320k What does not work yet ====================== * 3-pass encoding (ensuring constant total size and bitrate constraints while having VBR audio; mencoder calls this "frameno") * Direct stream copy mpv-0.23.0/DOCS/interface-changes.rst000066400000000000000000000401531302774270600172410ustar00rootroot00000000000000Introduction ============ mpv provides access to its internals via the following means: - options - commands - properties - events All of these are important for interfacing both with end users and API users (which include Lua scripts, libmpv, and the JSON IPC). As such, they constitute a large part of the user interface and APIs. This document lists changes to them. New changes are added to the top. Interface changes ================= :: --- mpv 0.23.0 --- - remove deprecated vf_vdpaurb (use "--hwdec=vdpau-copy" instead) - the following properties now have new semantics: - "demuxer" (use "current-demuxer") - "fps" (use "container-fps") - "idle" (use "idle-active") - "cache" (use "cache-percent") - "audio-samplerate" (use "audio-params/samplerate") - "audio-channels" (use "audio-params/channel-count") - "audio-format" (use "audio-codec-name") (the properties equivalent to the old semantics are in parentheses) - remove deprecated --vo and --ao sub-options (like --vo=opengl:...), and replace them with global options. A somewhat complete list can be found here: https://github.com/mpv-player/mpv/wiki/Option-replacement-list#mpv-0210 - remove --vo-defaults and --ao-defaults as well - remove deprecated global sub-options (like -demuxer-rawaudio format=...), use flat options (like --demuxer-rawaudio-format=...) - the --sub-codepage option changes in incompatible ways: - detector-selection and fallback syntax is deprecated - enca/libguess are removed and deprecated (behaves as if they hadn't been compiled-in) - --sub-codepage= does not force the codepage anymore (this requires different and new syntax) - remove --fs-black-out-screens option for macOS - change how spdif codecs are selected. You can't enable spdif passthrough with --ad anymore. This was deprecated; use --audio-spdif instead. - deprecate the "family" selection with --ad/--vd forcing/excluding codecs with "+", "-", "-" is deprecated as well - explicitly mark --ad-spdif-dtshd as deprecated (it was done so a long time ago, but it didn't complain when using the option) --- mpv 0.22.0 --- - the "audio-device-list" property now sets empty device description to the device name as a fallback - add --hidpi-window-scale option for macOS - add audiounit audio output for iOS - make --start-time work with --rebase-start-time=no - add --opengl-early-flush=auto mode - add --hwdec=vdpau-copy, deprecate vf_vdpaurb - add tct video output for true-color and 256-color terminals --- mpv 0.21.0 --- - unlike in older versions, setting options at runtime will now take effect immediately (see for example issue #3281). On the other hand, it will also do runtime verification and reject option changes that do not work (example: setting the "vf" option to a filter during playback, which fails to initialize - the option value will remain at its old value). In general, "set name value" should be mostly equivalent to "set options/name value" in cases where the "name" property is not deprecated and "options/name" exists - deviations from this are either bugs, or documented as caveats in the "Inconsistencies between options and properties" manpage section. - deprecate _all_ --vo and --ao suboptions. Generally, all suboptions are replaced by global options, which do exactly the same. For example, "--vo=opengl:scale=nearest" turns into "--scale=nearest". In some cases, the global option is prefixed, e.g. "--vo=opengl:pbo" turns into "--opengl-pbo". Most of the exact replacements are documented here: https://github.com/mpv-player/mpv/wiki/Option-replacement-list - remove --vo=opengl-hq. Set --profile=opengl-hq instead. Note that this profile does not force the VO. This means if you use the --vo option to set another VO, it won't work. But this also means it can be used with opengl-cb. - remove the --vo=opengl "pre-shaders", "post-shaders" and "scale-shader" sub-options: they were deprecated in favor of "user-shaders" - deprecate --vo-defaults (no replacement) - remove the vo-cmdline command. You can set OpenGL renderer options directly via properties instead. - deprecate the device/sink options on all AOs. Use --audio-device instead. - deprecate "--ao=wasapi:exclusive" and "--ao=coreaudio:exclusive", use --audio-exclusive instead. - subtle changes in how "--no-..." options are treated mean that they are not accessible under "options/..." anymore (instead, these are resolved at parsing time). This does not affect options which start with "--no-", but do not use the mechanism for negation options. (Also see client API change for API version 1.23.) - rename the following properties - "demuxer" -> "current-demuxer" - "fps" -> "container-fps" - "idle" -> "idle-active" - "cache" -> "cache-percent" the old names are deprecated and will change behavior in mpv 0.23.0. - remove deprecated "hwdec-active" and "hwdec-detected" properties - deprecate the ao and vo auto-profiles (they never made any sense) - deprecate "--vo=direct3d_shaders" - use "--vo=direct3d" instead. Change "--vo=direct3d" to always use shaders by default. - deprecate --playlist-pos option, renamed to --playlist-start - deprecate the --chapter option, as it is redundant with --start/--end, and conflicts with the semantics of the "chapter" property - rename --sub-text-* to --sub-* and --ass-* to --sub-ass-* (old options deprecated) - incompatible change to cdda:// protocol options: the part after cdda:// now always sets the device, not the span or speed to be played. No separating extra "/" is needed. The hidden --cdda-device options is also deleted (it was redundant with the documented --cdrom-device). - deprecate --vo=rpi. It will be removed in mpv 0.23.0. Its functionality was folded into --vo=opengl, which now uses RPI hardware decoding by treating it as a hardware overlay (without applying GL filtering). Also to be changed in 0.23.0: the --fs flag will be reset to "no" by default (like on the other platforms). - deprecate --mute=auto (informally has been since 0.18.1) - deprecate "resume" and "suspend" IPC commands. They will be completely removed in 0.23.0. - deprecate mp.suspend(), mp.resume(), mp.resume_all() Lua scripting commands, as well as setting mp.use_suspend. They will be completely removed in 0.23.0. - the "seek" command's absolute seek mode will now interpret negative seek times as relative from the end of the file (and clamps seeks that still go before 0) - add almost all options to the property list, meaning you can change options without adding "options/" to the property name (a new section has been added to the manpage describing some conflicting behavior between options and properties) - implement changing sub-speed during playback - make many previously fixed options changeable at runtime (for example --terminal, --osc, --ytdl, can all be enable/disabled after mpv_initialize() - this can be extended to other still fixed options on user requests) --- mpv 0.20.0 --- - add --image-display-duration option - this also means that image duration is not influenced by --mf-fps anymore in the general case (this is an incompatible change) --- mpv 0.19.0 --- - deprecate "balance" option/property (no replacement) --- mpv 0.18.1 --- - deprecate --heartbeat-cmd - remove --softvol=no capability: - deprecate --softvol, it now does nothing - --volume, --mute, and the corresponding properties now always control softvol, and behave as expected without surprises (e.g. you can set them normally while no audio is initialized) - rename --softvol-max to --volume-max (deprecated alias is added) - the --volume-restore-data option and property are removed without replacement. They were _always_ internal, and used for watch-later resume/restore. Now --volume/--mute are saved directly instead. - the previous point means resuming files with older watch-later configs will print an error about missing --volume-restore-data (which you can ignore), and will not restore the previous value - as a consequence, volume controls will no longer control PulseAudio per-application value, or use the system mixer's per-application volume processing - system or per-application volume can still be controlled with the ao-volume and ao-mute properties (there are no command line options) --- mpv 0.18.0 --- - now ab-loops are active even if one of the "ab-loop-a"/"-b" properties is unset ("no"), in which case the start of the file is used if the A loop point is unset, and the end of the file for an unset B loop point - deprecate --sub-ass=no option by --ass-style-override=strip (also needs --embeddedfonts=no) - add "hwdec-interop" and "hwdec-current" properties - deprecated "hwdec-active" and "hwdec-detected" properties (to be removed in mpv 0.20.0) - choice option/property values that are "yes" or "no" will now be returned as booleans when using the mpv_node functions in the client API, the "native" property accessors in Lua, and the JSON API. They can be set as such as well. - the VO opengl fbo-format sub-option does not accept "rgb" or "rgba" anymore - all VO opengl prescalers have been removed (replaced by user scripts) --- mpv 0.17.0 --- - deprecate "track-list/N/audio-channels" property (use "track-list/N/demux-channel-count" instead) - remove write access to "stream-pos", and change semantics for read access - Lua scripts now don't suspend mpv by default while script code is run - add "cache-speed" property - rename --input-unix-socket to --input-ipc-server, and make it work on Windows too - change the exact behavior of the "video-zoom" property - --video-unscaled no longer disables --video-zoom and --video-aspect To force the old behavior, set --video-zoom=0 and --video-aspect=0 --- mpv 0.16.0 --- - change --audio-channels default to stereo (use --audio-channels=auto to get the old default) - add --audio-normalize-downmix - change the default downmix behavior (--audio-normalize-downmix=yes to get the old default) - VO opengl custom shaders must now use "sample_pixel" as function name, instead of "sample" - change VO opengl scaler-resizes-only default to enabled - add VO opengl "interpolation-threshold" suboption (introduces new default behavior, which can change e.g. ``--video-sync=display-vdrop`` to the worse, but is usually what you want) - make "volume" and "mute" properties changeable even if no audio output is active (this gives not-ideal behavior if --softvol=no is used) - add "volume-max" and "mixer-active" properties - ignore --input-cursor option for events injected by input commands like "mouse", "keydown", etc. --- mpv 0.15.0 --- - change "yadif" video filter defaults --- mpv 0.14.0 --- - vo_opengl interpolation now requires --video-sync=display-... to be set - change some vo_opengl defaults (including changing tscale) - add "vsync-ratio", "estimated-display-fps" properties - add --rebase-start-time option This is a breaking change to start time handling. Instead of making start time handling an aspect of different options and properties (like "time-pos" vs. "playback-time"), make it dependent on the new option. For compatibility, the "time-start" property now always returns 0, so code which attempted to handle rebasing manually will not break. --- mpv 0.13.0 --- - remove VO opengl-cb frame queue suboptions (no replacement) --- mpv 0.12.0 --- - remove --use-text-osd (useless; fontconfig isn't a requirement anymore, and text rendering is also lazily initialized) - some time properties (at least "playback-time", "time-pos", "time-remaining", "playtime-remaining") now are unavailable if the time is unknown, instead of just assuming that the internal playback position is 0 - add --audio-fallback-to-null option - replace vf_format outputlevels suboption with "video-output-levels" global property/option; also remove "colormatrix-output-range" property - vo_opengl: remove sharpen3/sharpen5 scale filters, add sharpen sub-option --- mpv 0.11.0 --- - add "af-metadata" property --- mpv 0.10.0 --- - add --video-aspect-method option - add --playlist-pos option - add --video-sync* options "display-sync-active" property "vo-missed-frame-count" property "audio-speed-correction" and "video-speed-correction" properties - remove --demuxer-readahead-packets and --demuxer-readahead-bytes add --demuxer-max-packets and --demuxer-max-bytes (the new options are not replacement and have very different semantics) - change "video-aspect" property: always settable, even if no video is running; always return the override - if no override is set, return the video's aspect ratio - remove disc-nav (DVD, BD) related properties and commands - add "option-info//set-locally" property - add --cache-backbuffer; change --cache-default default to 75MB the new total cache size is the sum of backbuffer and the cache size specified by --cache-default or --cache - add ``track-list/N/audio-channels`` property - change --screenshot-tag-colorspace default value - add --stretch-image-subs-to-screen - add "playlist/N/title" property - add --video-stereo-mode=no to disable auto-conversions - add --force-seekable, and change default seekability in some cases - add vf yadif/vavpp/vdpaupp interlaced-only suboptions Also, the option is enabled by default (Except vf_yadif, which has it enabled only if it's inserted by the deinterlace property.) - add --hwdec-preload - add ao coreaudio exclusive suboption - add ``track-list/N/forced`` property - add audio-params/channel-count and ``audio-params-out/channel-count props. - add af volume replaygain-fallback suboption - add video-params/stereo-in property - add "keypress", "keydown", and "keyup" commands - deprecate --ad-spdif-dtshd and enabling passthrough via --ad add --audio-spdif as replacement - remove "get_property" command - remove --slave-broken - add vo opengl custom shader suboptions (source-shader, scale-shader, pre-shaders, post-shaders) - completely change how the hwdec properties work: - "hwdec" now reflects the --hwdec option - "hwdec-detected" does partially what the old "hwdec" property did (and also, "detected-hwdec" is removed) - "hwdec-active" is added - add protocol-list property - deprecate audio-samplerate and audio-channels properties (audio-params sub-properties are the replacement) - add audio-params and audio-out-params properties - deprecate "audio-format" property, replaced with "audio-codec-name" - deprecate --media-title, replaced with --force-media-title - deprecate "length" property, replaced with "duration" - change volume property: - the value 100 is now always "unchanged volume" - with softvol, the range is 0 to --softvol-max, without it is 0-100 - the minimum value of --softvol-max is raised to 100 - remove vo opengl npot suboption - add relative seeking by percentage to "seek" command - add playlist_shuffle command - add --force-window=immediate - add ao coreaudio change-physical-format suboption - remove vo opengl icc-cache suboption, add icc-cache-dir suboption - add --screenshot-directory - add --screenshot-high-bit-depth - add --screenshot-jpeg-source-chroma - default action for "rescan_external_files" command changes --- mpv 0.9.0 --- mpv-0.23.0/DOCS/man/000077500000000000000000000000001302774270600137115ustar00rootroot00000000000000mpv-0.23.0/DOCS/man/af.rst000066400000000000000000000444021302774270600150350ustar00rootroot00000000000000AUDIO FILTERS ============= Audio filters allow you to modify the audio stream and its properties. The syntax is: ``--af=`` Setup a chain of audio filters. .. 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. You can also set defaults for each filter. The defaults are applied before the normal filter parameters. ``--af-defaults=`` Set defaults for each filter. Audio filters are managed in lists. There are a few commands to manage the filter list: ``--af-add=`` Appends the filters given as arguments to the filter list. ``--af-pre=`` Prepends the filters given as arguments to the filter list. ``--af-del=`` Deletes the filters at the given indexes. Index numbers start at 0, negative numbers address the end of the list (-1 is the last). ``--af-clr`` Completely empties the filter list. Available filters are: ``lavrresample[=option1:option2:...]`` This filter uses libavresample (or libswresample, depending on the build) to change sample rate, sample format, or channel layout of the audio stream. This filter is automatically enabled if the audio output does not support the audio configuration of the file being played. It supports only the following sample formats: u8, s16, s32, float. ``filter-size=`` Length of the filter with respect to the lower sampling rate. (default: 16) ``phase-shift=`` Log2 of the number of polyphase entries. (..., 10->1024, 11->2048, 12->4096, ...) (default: 10->1024) ``cutoff=`` Cutoff frequency (0.0-1.0), default set depending upon filter length. ``linear`` If set then filters will be linearly interpolated between polyphase entries. (default: no) ``no-detach`` Do not detach if input and output audio format/rate/channels match. (If you just want to set defaults for this filter that will be used even by automatically inserted lavrresample instances, you should prefer setting them with ``--af-defaults=lavrresample:...``.) ``normalize=`` Whether to normalize when remixing channel layouts (default: auto). ``auto`` uses the value set by ``--audio-normalize-downmix``. ``o=`` Set AVOptions on the SwrContext or AVAudioResampleContext. These should be documented by FFmpeg or Libav. ``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. ``equalizer=g1:g2:g3:...:g10`` 10 octave band graphic equalizer, implemented using 10 IIR band-pass filters. This means that it works regardless of what type of audio is being played back. The center frequencies for the 10 bands are: === ========== No. frequency === ========== 0 31.25 Hz 1 62.50 Hz 2 125.00 Hz 3 250.00 Hz 4 500.00 Hz 5 1.00 kHz 6 2.00 kHz 7 4.00 kHz 8 8.00 kHz 9 16.00 kHz === ========== If the sample rate of the sound being played is lower than the center frequency for a frequency band, then that band will be disabled. A known bug with this filter is that the characteristics for the uppermost band are not completely symmetric if the sample rate is close to the center frequency of that band. This problem can be worked around by upsampling the sound using a resampling filter before it reaches this filter. ``:::...:`` floating point numbers representing the gain in dB for each frequency band (-12-12) .. admonition:: Example ``mpv --af=equalizer=11:11:10:5:0:-12:0:5:12:12 media.avi`` Would amplify the sound in the upper and lower frequency region while canceling it almost completely around 1 kHz. ``channels=nch[:routes]`` Can be used for adding, removing, routing and copying audio channels. If only ```` is given, the default routing is used. It works as follows: If the number of output channels is greater than the number of input channels, empty channels are inserted (except when mixing from mono to stereo; then the mono channel is duplicated). If the number of output channels is less than the number of input channels, the exceeding channels are truncated. ```` number of output channels (1-8) ```` List of ``,`` separated routes, in the form ``from1-to1,from2-to2,...``. Each pair defines where to route each channel. There can be at most 8 routes. Without this argument, the default routing is used. Since ``,`` is also used to separate filters, you must quote this argument with ``[...]`` or similar. .. admonition:: Examples ``mpv --af=channels=4:[0-1,1-0,2-2,3-3] media.avi`` Would change the number of channels to 4 and set up 4 routes that swap channel 0 and channel 1 and leave channel 2 and 3 intact. Observe that if media containing two channels were played back, channels 2 and 3 would contain silence but 0 and 1 would still be swapped. ``mpv --af=channels=6:[0-0,0-1,0-2,0-3] media.avi`` Would change the number of channels to 6 and set up 4 routes that copy channel 0 to channels 0 to 3. Channel 4 and 5 will contain silence. .. note:: You should probably not use this filter. If you want to change the output channel layout, try the ``format`` filter, which can make mpv automatically up- and downmix standard channel layouts. ``format=format:srate:channels:out-format: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. ``volume[=[:...]]`` Implements software volume control. Use this filter with caution since it can reduce the signal to noise ratio of the sound. In most cases it is best to use the *Master* volume control of your sound card or the volume knob on your amplifier. *NOTE*: This filter is not reentrant and can therefore only be enabled once for every audio stream. ```` Sets the desired gain in dB for all channels in the stream from -200 dB to +60 dB, where -200 dB mutes the sound completely and +60 dB equals a gain of 1000 (default: 0). ``replaygain-track`` Adjust volume gain according to the track-gain replaygain value stored in the file metadata. ``replaygain-album`` Like replaygain-track, but using the album-gain value instead. ``replaygain-preamp`` Pre-amplification gain in dB to apply to the selected replaygain gain (default: 0). ``replaygain-clip=yes|no`` Prevent clipping caused by replaygain by automatically lowering the gain (default). Use ``replaygain-clip=no`` to disable this. ``replaygain-fallback`` Gain in dB to apply if the file has no replay gain tags. This option is always applied if the replaygain logic is somehow inactive. If this is applied, no other replaygain options are applied. ``softclip`` Turns soft clipping on. Soft-clipping can make the sound more smooth if very high volume levels are used. Enable this option if the dynamic range of the loudspeakers is very low. *WARNING*: This feature creates distortion and should be considered a last resort. ``s16`` Force S16 sample format if set. Lower quality, but might be faster in some situations. ``detach`` Remove the filter if the volume is not changed at audio filter config time. Useful with replaygain: if the current file has no replaygain tags, then the filter will be removed if this option is enabled. (If ``--softvol=yes`` is used and the player volume controls are used during playback, a different volume filter will be inserted.) .. admonition:: Example ``mpv --af=volume=10.1 media.avi`` Would amplify the sound by 10.1 dB and hard-clip if the sound level is too high. ``pan=n:[]`` Mixes channels arbitrarily. Basically a combination of the volume and the channels filter that can be used to down-mix many channels to only a few, e.g. stereo to mono, or vary the "width" of the center speaker in a surround sound system. This filter is hard to use, and will require some tinkering before the desired result is obtained. The number of options for this filter depends on the number of output channels. An example how to downmix a six-channel file to two channels with this filter can be found in the examples section near the end. ```` Number of output channels (1-8). ```` A list of values ``[L00,L01,L02,...,L10,L11,L12,...,Ln0,Ln1,Ln2,...]``, where each element ``Lij`` means how much of input channel i is mixed into output channel j (range 0-1). So in principle you first have n numbers saying what to do with the first input channel, then n numbers that act on the second input channel etc. If you do not specify any numbers for some input channels, 0 is assumed. Note that the values are separated by ``,``, which is already used by the option parser to separate filters. This is why you must quote the value list with ``[...]`` or similar. .. admonition:: Examples ``mpv --af=pan=1:[0.5,0.5] media.avi`` Would downmix from stereo to mono. ``mpv --af=pan=3:[1,0,0.5,0,1,0.5] media.avi`` Would give 3 channel output leaving channels 0 and 1 intact, and mix channels 0 and 1 into output channel 2 (which could be sent to a subwoofer for example). .. note:: If you just want to force remixing to a certain output channel layout, it is easier to use the ``format`` filter. For example, ``mpv '--af=format=channels=5.1' '--audio-channels=5.1'`` would always force remixing audio to 5.1 and output it like this. This filter supports the following ``af-command`` commands: ``set-matrix`` Set the ```` argument dynamically. This can be used to change the mixing matrix at runtime, without reinitializing the entire filter chain. ``drc[=method:target]`` Applies dynamic range compression. This maximizes the volume by compressing the audio signal's dynamic range. (Formerly called ``volnorm``.) ```` Sets the used method. 1 Use a single sample to smooth the variations via the standard weighted mean over past samples (default). 2 Use several samples to smooth the variations via the standard weighted mean over past samples. ```` Sets the target amplitude as a fraction of the maximum for the sample type (default: 0.25). .. note:: This filter can cause distortion with audio signals that have a very large dynamic range. ``scaletempo[=option1:option2:...]`` Scales audio tempo without altering pitch, optionally synced to playback speed (default). 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=`` Percentage 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. ``rubberband`` High quality pitch correction with librubberband. This can be used in place of ``scaletempo``, 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. ```` Sets the pitch scaling factor. Frequencies are multiplied by this value. 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: http://breakfastquay.com/rubberband/code-doc/classRubberBand_1_1RubberBandStretcher.html (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``. ``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. mpv-0.23.0/DOCS/man/ao.rst000066400000000000000000000260221302774270600150440ustar00rootroot00000000000000AUDIO 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. .. note:: See ``--ao=help`` for a list of compiled-in audio output drivers. The driver ``--ao=alsa`` is preferred. ``--ao=pulse`` is preferred on systems where PulseAudio is used. On BSD systems, ``--ao=oss`` or ``--ao=sndio`` may work (the latter being experimental). Available audio output drivers are: ``alsa`` (Linux only) ALSA audio output driver See `ALSA audio output options`_ for options specific to this AO. .. warning:: To get multichannel/surround audio, use ``--audio-channels=auto``. The default for this option is ``auto-safe``, which makes this audio otuput 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 The following global options are supported by this audio output: ``--oss-device`` Sets the audio output device (default: ``/dev/dsp``). Deprecated, use ``--audio-device``. ``--oss-mixer-device`` Sets the audio mixer device (default: ``/dev/mixer``). ``--oss-mixer-channel`` Sets the audio mixer channel (default: ``pcm``). Other valid values include **vol, pcm, line**. For a complete list of options look for ``SOUND_DEVICE_NAMES`` in ``/usr/include/linux/soundcard.h``. ``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`` (Mac OS X only) Native Mac OS X 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-exclusive`` Deprecated, use ``--audio-exclusive``. Use exclusive mode access. This merely redirects to ``coreaudio_exclusive``, but should be preferred over using that AO directly. ``coreaudio_exclusive`` (Mac OS X only) Native Mac OS X audio output driver using direct device access and exclusive mode (bypasses the sound server). ``openal`` Experimental OpenAL audio output driver .. note:: This driver is not very useful. Playing multi-channel audio with it is slow. ``pulse`` PulseAudio audio output driver The following global options are supported by this audio output: ``--pulse-host=``, ``--pulse-sink=`` Specify the host and optionally output sink to use. An empty string uses a local connection, "localhost" uses network transfer (most likely not what you want). Deprecated, use ``--audio-device``. ``--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. Default: 250. ``--pulse-latency-hacks=`` Enable hacks to workaround PulseAudio timing bugs (default: no). 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 used to be required to get good behavior on old PulseAudio versions). If you have stuttering video when using pulse, try to enable this option. (Or try to update PulseAudio.) ``sdl`` SDL 1.2+ audio output driver. Should work on any platform supported by SDL 1.2, 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. ``--sdl-bufcnt=`` Sets the number of extra audio buffers in mpv. Usually needs not be changed. ``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. ``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. ``rsound`` Audio output to an RSound daemon .. note:: Completely useless, unless you intend to run RSound. Not to be confused with RoarAudio, which is something completely different. The following global options are supported by this audio output: ``--rsound-host=`` Set the address of the server (default: localhost). Can be either a network hostname for TCP connections or a Unix domain socket path starting with '/'. ``--rsound-port=`` Set the TCP port used for connecting to the server (default: 12345). Not used if connecting to a Unix domain socket. These options are deprecated. If anyone cares enough, their functionality can be added back using ``--audio-device``. ``sndio`` Audio output to the OpenBSD sndio sound system .. note:: Experimental. There are known bugs and issues. (Note: only supports mono, stereo, 4.0, 5.1 and 7.1 channel layouts.) The following global options are supported by this audio output: ``--ao-sndio-device=`` sndio device to use (default: ``$AUDIODEVICE``, resp. ``snd0``). Deprecated, use ``--audio-device``. ``wasapi`` Audio output to the Windows Audio Session API. The following global options are supported by this audio output: ``--ao-wasapi-exclusive`` Deprecated, use ``--audio-exclusive``. Requests exclusive, direct hardware access. By definition prevents sound playback of any other program until mpv exits. ``--ao-wasapi-device=`` Deprecated, use ``--audio-device``. Uses the requested endpoint instead of the system's default audio endpoint. Both an ordinal number (0,1,2,...) and the GUID String are valid; the GUID string is guaranteed to not change unless the driver is uninstalled. Also supports searching active devices by human-readable name. If more than one device matches the name, refuses loading it. mpv-0.23.0/DOCS/man/changes.rst000066400000000000000000000014151302774270600160540ustar00rootroot00000000000000CHANGELOG ========= 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 files ``client-api-changes.rst`` and ``interface-changes.rst`` in the ``DOCS`` sub directoryon the git repository, which document API and user interface changes (the latter usually documents breaking changes only, rather than additions). * 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.) mpv-0.23.0/DOCS/man/encode.rst000066400000000000000000000132531302774270600157040ustar00rootroot00000000000000ENCODING ======== 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``). This can be a comma separated list of possible formats to try. 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. Options are managed in lists. There are a few commands to manage the options list. ``--ofopts-add=`` Appends the options given as arguments to the options list. ``--ofopts-pre=`` Prepends the options given as arguments to the options list. ``--ofopts-del=`` Deletes the options at the given indexes. Index numbers start at 0, negative numbers address the end of the list (-1 is the last). ``--ofopts-clr`` Completely empties the options list. ``--ofps=`` Specifies the output format time base (default: 24000). Low values like 25 limit video fps by dropping frames. ``--oautofps`` Sets the output format time base to the guessed frame rate of the input video (simulates MEncoder behavior, useful for AVI; may cause frame drops). Note that not all codecs and not all formats support VFR encoding, and some which do have bugs when a target bitrate is specified - use ``--ofps`` or ``--oautofps`` to force CFR encoding in these cases. ``--omaxfps=`` Specifies the minimum distance of adjacent frames (default: 0, which means unset). Content of lower frame rate is not readjusted to this frame rate; content of higher frame rate is decimated to this frame rate. ``--oharddup`` If set, the frame rate given by ``--ofps`` is attained not by skipping time codes, but by duplicating frames (constant frame rate mode). ``--oneverdrop`` If set, frames are never dropped. Instead, time codes of video are readjusted to always increase. This may cause AV desync, though; to work around this, use a high-fps time base using ``--ofps`` and absolutely avoid ``--oautofps``. ``--oac=`` Specifies the output audio codec. This can be a comma separated list of possible codecs to try. See ``--oac=help`` for a full list of supported codecs. ``--oaoffset=`` Shifts audio data by the given time (in seconds) by adding/removing samples at the start. ``--oacopts=`` Specifies the output audio codec options for libavcodec. See ``--oacopts=help`` for a full list of supported options. .. admonition:: Example "``--oac=libmp3lame --oacopts=b=128000``" selects 128 kbps MP3 encoding. Options are managed in lists. There are a few commands to manage the options list. ``--oacopts-add=`` Appends the options given as arguments to the options list. ``--oacopts-pre=`` Prepends the options given as arguments to the options list. ``--oacopts-del=`` Deletes the options at the given indexes. Index numbers start at 0, negative numbers address the end of the list (-1 is the last). ``--oacopts-clr`` Completely empties the options list. ``--oafirst`` Force the audio stream to become the first stream in the output. By default, the order is unspecified. ``--ovc=`` Specifies the output video codec. This can be a comma separated list of possible codecs to try. See ``--ovc=help`` for a full list of supported codecs. ``--ovoffset=`` Shifts video data by the given time (in seconds) by shifting the pts values. ``--ovcopts `` Specifies the output video codec options for libavcodec. See --ovcopts=help for a full list of supported options. .. admonition:: Examples ``"--ovc=mpeg4 --ovcopts=qscale=5"`` selects constant quantizer scale 5 for MPEG-4 encoding. ``"--ovc=libx264 --ovcopts=crf=23"`` selects VBR quality factor 23 for H.264 encoding. Options are managed in lists. There are a few commands to manage the options list. ``--ovcopts-add=`` Appends the options given as arguments to the options list. ``--ovcopts-pre=`` Prepends the options given as arguments to the options list. ``--ovcopts-del=`` Deletes the options at the given indexes. Index numbers start at 0, negative numbers address the end of the list (-1 is the last). ``--ovcopts-clr`` Completely empties the options list. ``--ovfirst`` Force the video stream to become the first stream in the output. By default, the order is unspecified. ``--ocopyts`` Copies input pts to the output video (not supported by some output container formats, e.g. AVI). Discontinuities are still fixed. By default, audio pts are set to playback time and video pts are synchronized to match audio pts, as some output formats do not support anything else. ``--orawts`` Copies input pts to the output video (not supported by some output container formats, e.g. AVI). In this mode, discontinuities are not fixed and all pts are passed through as-is. Never seek backwards or use multiple input files in this mode! ``--no-ometadata`` Turns off copying of metadata from input files to output files when encoding (which is enabled by default). mpv-0.23.0/DOCS/man/input.rst000066400000000000000000002622241302774270600156120ustar00rootroot00000000000000COMMAND INTERFACE ================= The mpv core can be controlled with commands and properties. A number of ways to interact with the player use them: key bindings (``input.conf``), OSD (showing information with properties), JSON IPC, the client API (``libmpv``), and the classic slave mode. 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. The 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 A list of special keys can be obtained with ``mpv --input-keylist`` In general, keys can be combined with ``Shift``, ``Ctrl`` and ``Alt``:: ctrl+q quit **mpv** can be started in input test mode, which displays key bindings and the commands they're bound to on the OSD, instead of executing the commands:: mpv --input-test --force-window --idle (Only closing the window will make **mpv** exit, pressing normal keys will merely display the binding, even if mapped to quit.) General Input Command Syntax ---------------------------- ``[Shift+][Ctrl+][Alt+][Meta+] [{
}] [] ()* [; ]`` Note that by default, the right Alt key can be used to create special characters, and thus does not register as a modifier. The option ``--no-input-right-alt-gr`` changes this behavior. Newlines always start a new binding. ``#`` starts a comment (outside of quoted string arguments). To bind commands to the ``#`` key, ``SHARP`` can be used. ```` is either the literal character the key produces (ASCII or Unicode character), or a symbolic name (as printed by ``--input-keylist``). ``
`` (braced with ``{`` and ``}``) is the input section for this command. Arguments are separated by whitespace. This applies even to string arguments. For this reason, string arguments should be quoted with ``"``. Inside quotes, C-style escaping can be used. You can bind multiple commands to one key. For example: | a show-text "command 1" ; show-text "command 2" It's also possible to bind a command to a sequence of keys: | a-b-c show-text "command run after a, b, c have been pressed" (This is not shown in the general command syntax.) If ``a`` or ``a-b`` or ``b`` are already bound, this will run the first command that matches, and the multi-key command will never be called. Intermediate keys can be remapped to ``ignore`` in order to avoid this issue. The maximum number of (non-modifier) keys for combinations is currently 4. List of Input Commands ---------------------- ``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 [relative|absolute|absolute-percent|relative-percent|exact|keyframes]`` Change the playback position. By default, seeks by a relative amount of seconds. The second argument consists of flags controlling the seek mode: 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). Multiple flags can be combined, e.g.: ``absolute+keyframes``. By default, ``keyframes`` is used for relative seeks, and ``exact`` is used for absolute seeks. Before mpv 0.9, the ``keyframes`` and ``exact`` flags had to be passed as 3rd parameter (essentially using a space instead of ``+``). The 3rd parameter is still parsed, but is considered deprecated. ``revert-seek [mode]`` Undoes the ``seek`` command, and some other commands that seek (but not necessarily all of them). Calling this command once will jump to the playback position before the seek. Calling it a second time undoes the ``revert-seek`` command itself. This only works within a single file. The first argument is optional, and can change the behavior: mark Mark the current time position. The next normal ``revert-seek`` command will seek back to this point, no matter how many seeks happened since last time. Using it without any arguments gives you the default behavior. ``frame-step`` Play one frame, then pause. Does nothing with audio-only playback. ``frame-back-step`` Go back by one frame, then pause. Note that this can be very slow (it tries to be precise, not fast), and sometimes fails to behave as expected. How well this works depends on whether precise seeking works correctly (e.g. see the ``--hr-seek-demuxer-offset`` option). Video filters or other video post-processing that modifies timing of frames (e.g. deinterlacing) should usually work, but might make backstepping silently behave incorrectly in corner cases. Using ``--hr-seek-framedrop=no`` should help, although it might make precise seeking slower. This does not work with audio-only playback. ``set ""`` Set the given property to the given value. ``add []`` Add the given value to the property. On overflow or underflow, clamp the property to the maximum. If ```` is omitted, assume ``1``. ``cycle [up|down]`` Cycle the given property. ``up`` and ``down`` set the cycle direction. On overflow, set the property back to the minimum, on underflow set it to the maximum. If ``up`` or ``down`` is omitted, assume ``up``. ``multiply `` Multiplies the value of a property with the numeric factor. ``screenshot [subtitles|video|window|- [single|each-frame]]`` Take a screenshot. First argument: (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.