diff options
Diffstat (limited to 'DOCS')
46 files changed, 3890 insertions, 1978 deletions
diff --git a/DOCS/client-api-changes.rst b/DOCS/client-api-changes.rst index 308ce44b4b..e48cda4fa0 100644 --- a/DOCS/client-api-changes.rst +++ b/DOCS/client-api-changes.rst @@ -32,6 +32,23 @@ API changes :: + --- mpv 0.38.0 --- + 2.3 - partially revert the changes from API version 1.27, remove libmpv as + the default VO and move it to the bottom of the auto-probing order. + This restores the prior behavior on all platforms other than macOS, + but still auto selects libmpv/cocoa-cb on macOS if it was built with + support for cocoa-cb. + --- mpv 0.37.0 --- + 2.2 - add mpv_time_ns() + --- mpv 0.36.0 --- + 2.1 - add mpv_del_property() + --- mpv 0.35.0 --- + 2.0 - remove headers/functions of the obsolete opengl_cb API + - remove mpv_opengl_init_params.extra_exts field + - remove deprecated mpv_detach_destroy. Use mpv_destroy instead. + - remove obsolete mpv_suspend and mpv_resume + - remove deprecated SCRIPT_INPUT_DISPATCH, PAUSE and UNPAUSE, TRACKS_CHANGED + TRACK_SWITCHED, METADATA_UPDATE, CHAPTER_CHANGE events --- mpv 0.33.0 --- 1.109 - add MPV_RENDER_API_TYPE_SW and related (software rendering API) - inactivate the opengl_cb API (always fails to initialize now) @@ -54,7 +71,6 @@ API changes It is a good idea to write better wrappers for your use, though. --- mpv 0.31.0 --- 1.107 - Deprecate MPV_EVENT_TICK - --- mpv 0.30.0 --- 1.106 - Add cancel_fn to mpv_stream_cb_info 1.105 - Fix deadlock problems with MPV_RENDER_PARAM_ADVANCED_CONTROL and if @@ -72,7 +88,6 @@ API changes - add mpv_abort_async_command() 1.102 - rename struct mpv_opengl_drm_osd_size to mpv_opengl_drm_draw_surface_size - rename MPV_RENDER_PARAM_DRM_OSD_SIZE to MPV_RENDER_PARAM_DRM_DRAW_SURFACE_SIZE - --- mpv 0.29.0 --- 1.101 - add MPV_RENDER_PARAM_ADVANCED_CONTROL and related API - add MPV_RENDER_PARAM_NEXT_FRAME_INFO and related symbols @@ -264,7 +279,7 @@ API changes - 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 + - macOS: the "coreaudio" AO spdif code is split into a separate AO --- mpv 0.4.0 --- 1.0 - the API is declared stable diff --git a/DOCS/compatibility.rst b/DOCS/compatibility.rst index 3d6ec2cdfc..aeef8fc7ca 100644 --- a/DOCS/compatibility.rst +++ b/DOCS/compatibility.rst @@ -29,7 +29,16 @@ 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. -All incompatible changes to this must be declared in interface-changes.rst. +Certain options and commands may have documented default values. These default +values are considered a part of the API since scripts may already rely on these +documented behaviors. Changing these defaults are considered incompatible +changes and must be documented. Undocumented default values do not subject to +this requirement, and it is recommended to discourage such usage in the related +documentations if there is a need to frequently change such defaults. + +All incompatible changes to this must be declared in interface-changes.rst, +which include the types of changes, the impact of these changes, and suggested +actions to address such impact so that the incompatibility is alleviated. (This may also list compatible additions, but it's not a requirement.) Degrees of importance and compatibility preservation @@ -49,8 +58,17 @@ functionality still works, and a replacement is available (if technically reasonable). For example, a feature deprecated in mpv 0.30.0 may be removed in mpv 0.32.0. Minor releases do not count towards this. +Under extraordinary circumstances, such as missed incompatible changes that are +already included in a release, critical security fixes, or a severe shortage of +developer time to address the known incompatible changes, important/often used +parts may be broken immediately, but the change must be extensively documented: +all of the related documentations (including manpage, interface-changes.rst, +etc., retrospectively modified if applicable) must clearly state the following: +the fact that the change is a breaking change; the version when the breaking +change happened; and the reason, impact, and suggested remedy actions. + Less useful parts can be broken immediately, but must come with some sort of -removal warning- +removal warning. Parts for debugging and testing may be removed any time, potentially even without any sort of documentation. diff --git a/DOCS/compile-windows.md b/DOCS/compile-windows.md index 2fd011978a..c4310b594e 100644 --- a/DOCS/compile-windows.md +++ b/DOCS/compile-windows.md @@ -1,213 +1,253 @@ -Compiling 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 +# Compiling for Windows + +Compiling for Windows is supported using GNU-like compilers (GCC/Clang). Clang +is compatible with both the ``w64-windows-gnu`` [MinGW-w64](https://www.mingw-w64.org/) +and ``pc-windows-msvc`` [Windows SDK](https://developer.microsoft.com/windows/downloads/windows-sdk) +targets. It supports the production of both 32-bit and 64-bit binaries and is +suitable for building on Windows as well as cross-compiling from Linux and Cygwin. + +Although it is possible to build a complete MinGW-w64 toolchain yourself, there +are build environments and scripts available to simplify the process, such as +MSYS2 on Windows or a packaged toolchain provided by your favorite Linux +distribution. Note that MinGW-w64 environments included in Linux distributions +can vary in versions. As a general guideline, mpv only supports the MinGW-w64 +toolchain version included in the latest Ubuntu LTS release. + +mpv employs Meson for building, and the process is the same as any standard Meson +compilation. + +For the most up-to-date reference on build scripts, you can refer to +[build.yml](https://github.com/mpv-player/mpv/blob/master/.github/workflows/build.yml), +which builds and tests all supported configurations: ``MinGW-w64``, ``Windows SDK``, +and ``MSYS2`` builds. + +## Cross-compilation + +When cross-compiling, it is recommended to use a Meson ``--cross-file`` to set up the +cross-compiling environment. For a basic example, please refer to +[Cross-compilation](https://mesonbuild.com/Cross-compilation.html). + +Alternatively, consider using [mpv-winbuild-cmake](https://github.com/shinchiro/mpv-winbuild-cmake), +which bootstraps a MinGW-w64 toolchain and builds mpv along with its dependencies. + +### Example with Meson + +1. Create ``cross-file.txt`` with definitions for your toolchain and target platform. + Refer to [x86_64-w64-mingw32.txt](https://mesonbuild.com/Cross-compilation.html) + as a directly usable example. + - **Important**: Beware of pkg-config usage. By default, it uses build machine + files for dependency detection, even when ``--cross-file`` is used. It must + be configured correctly. Refer to ``pkg_config_libdir`` and ``sys_root`` + in the [documentation](https://mesonbuild.com/Cross-compilation.html#defining-the-environment) + for proper setup. **In this example pkg-config is not used/required.** +2. Initialize subprojects. This step is optional; other methods are also + available to provide the necessary dependencies. + + ``` bash + # Update the subprojects database from Meson's WrapDB. + meson wrap update-db + + # Explicitly download wraps as nested projects may have older versions of them. + meson wrap install expat + meson wrap install harfbuzz + meson wrap install libpng + meson wrap install zlib + + # Add wraps for mpv's required dependencies + mkdir -p subprojects + + cat <<EOF > subprojects/libplacebo.wrap + [wrap-git] + url = https://github.com/haasn/libplacebo + revision = master + depth = 1 + clone-recursive = true + EOF + + cat <<EOF > subprojects/libass.wrap + [wrap-git] + revision = master + url = https://github.com/libass/libass + depth = 1 + EOF + + # For FFmpeg, use Meson's build system port; alternatively, you can compile + # the upstream version yourself. See https://trac.ffmpeg.org/wiki/CompilationGuide + cat <<EOF > subprojects/ffmpeg.wrap + [wrap-git] + url = https://gitlab.freedesktop.org/gstreamer/meson-ports/ffmpeg.git + revision = meson-6.1 + depth = 1 + [provide] + libavcodec = libavcodec_dep + libavdevice = libavdevice_dep + libavfilter = libavfilter_dep + libavformat = libavformat_dep + libavutil = libavutil_dep + libswresample = libswresample_dep + libswscale = libswscale_dep + EOF + ``` + +3. Build + + ``` bash + meson setup -Ddefault_library=static -Dprefer_static=true \ + -Dc_link_args='-static' -Dcpp_link_args='-static' \ + --cross-file cross-file.txt build + + ninja -C build mpv.exe mpv.com + ``` + + This will produce fully portabiel, statically linked, ``mpv.exe`` and ``mpv.com`` + binaries. + +#### Building libmpv + +- To also build ``libmpv``, execute the following commands: + + ``` bash + # For a static library + meson configure build -Dlibmpv=true -Ddefault_library=static + ninja -C build libmpv.a + + # For a shared library + meson configure build -Dlibmpv=true -Ddefault_library=shared + ninja -C build libmpv-2.dll + ``` + +- Depending on the use case, you might want to use ``-Dgpl=false`` and review + similar options for subprojects. +- If any of Meson's subprojects are not linked statically, you might need to + specify options like the following example for ffmpeg: + ``-Dffmpeg:default_library=static``. + +#### Enabling more mpv features + +The process above produces a basic mpv build. You can enable additional features. +Check the Meson +[WrapDB packages](https://mesonbuild.com/Wrapdb-projects.html) for available +dependencies or by providing them through other means. + +Enhancing mpv with more features is as simple as adding more arguments to the +Meson setup command, for example: + +``` bash +-Dlua=enabled -Djavascript=enabled -Dlcms2=enabled -Dlibplacebo:lcms=enabled ``` -[MXE](http://mxe.cc) makes it very easy to bootstrap a complete MingGW-w64 -environment from a Linux machine. See a working example below. +they will be automatically downloaded and built by Meson. -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. +## Native Compilation with Clang (Windows SDK Build) -Example with MXE ----------------- +1. Install [Build Tools for Visual Studio](https://visualstudio.microsoft.com/downloads/#build-tools-for-visual-studio-2022) + or the full [Visual Studio](https://visualstudio.microsoft.com/downloads/#visual-studio-community-2022): + - From the installer, select the necessary components: + - Clang compiler for Windows + - Windows SDK +2. Install Meson, as outlined in [Getting Meson](https://mesonbuild.com/Getting-meson.html): + - **Important**: At the time of writing, there is an issue in Meson with + escaping response files. -```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 luajit - -# 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 -============================= + See: [mesonbuild/meson#8981](https://github.com/mesonbuild/meson/issues/8981) + and [mesonbuild/meson#11715](https://github.com/mesonbuild/meson/pull/11715) -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. + If you wish to install a fixed version, follow the steps outlined + [here](https://github.com/mpv-player/mpv/blob/481e498427fc34956ad24b94157553908f5cd638/.github/workflows/build.yml#L132-L135). +3. Set environment variables or use the ``--native-file`` option in Meson. -To build 64-bit mpv on Windows: + ``` powershell + $env:CC = "clang" + $env:CXX = "clang++" + $env:CC_LD = 'lld' + $env:CXX_LD = 'lld' + $env:WINDRES = 'llvm-rc' + ``` -Installing MSYS2 ----------------- +4. Execute [build-win32.ps1](https://github.com/mpv-player/mpv/blob/master/ci/build-win32.ps1): + - This script utilizes the Meson subprojects system to build mpv and its + dependencies. Refer to the script for more details. -1. Download an installer from https://msys2.github.io/ +This process will produce a fully static ``mpv.exe`` and ``mpv.com``, as well as +a static ``libmpv.a``. - Both the i686 and the x86_64 version of MSYS2 can build 32-bit and 64-bit - mpv binaries when running on a 64-bit version of Windows, but the x86_64 - version is preferred since the larger address space makes it less prone to - fork() errors. +## Native Compilation with MSYS2 -2. Start a MinGW-w64 shell (``mingw64.exe``). **Note:** This is different from - the MSYS2 shell that is started from the final installation dialog. You must - close that shell and open a new one. +For Windows developers seeking a quick setup, MSYS2 is an effective tool for +compiling mpv natively on a Windows machine. The MSYS2 repositories provide +binary packages for most of mpv's dependencies, simplifying the process to +primarily involve building mpv itself. - For a 32-bit build, use ``mingw32.exe``. +### Installing MSYS2 -Updating MSYS2 --------------- +1. Follow the installation steps from [MSYS2](https://www.msys2.org/). +2. Initiate one of the [Environments](https://www.msys2.org/docs/environments/), + with the CLANG64 (``clang64.exe``) being the recommended option. + **Note:** This environment is distinct from the MSYS2 shell that opens + automatically after the final installation dialog. You must close that + initial shell and open a new one for the appropriate environment. -To prevent errors during post-install, the MSYS2 core runtime must be updated -separately. +### Updating MSYS2 -```bash -# Check for core updates. If instructed, close the shell window and reopen it -# before continuing. -pacman -Syu +For guidance on updating MSYS2, please refer to the official documentation: +[Updating MSYS2](https://www.msys2.org/docs/updating/). -# Update everything else -pacman -Su -``` +### Installing mpv Dependencies -Installing mpv dependencies ---------------------------- +``` bash +# Install pacboy +pacman -S pactoys -```bash # Install MSYS2 build dependencies and a MinGW-w64 compiler -pacman -S git python $MINGW_PACKAGE_PREFIX-{pkg-config,gcc} +pacboy -S git {python,pkgconf,cc,meson}:p -# Install the most important MinGW-w64 dependencies. libass and lcms2 are also -# pulled in as dependencies of ffmpeg. -pacman -S $MINGW_PACKAGE_PREFIX-{ffmpeg,libjpeg-turbo,lua51} +# Install key dependencies. libass and lcms2 are also included as dependencies +# of ffmpeg. +pacboy -S {ffmpeg,libjpeg-turbo,libplacebo,luajit}:p ``` -Building mpv ------------- +### Building mpv -Clone the latest mpv from git and install waf. **Note:** ``/usr/bin/python3`` -is invoked directly here, since an MSYS2 version of Python is required. +To compile and install mpv, execute the following commands. +The binaries will be installed in the directory ``/$MSYSTEM_PREFIX/bin``. ```bash -git clone https://github.com/mpv-player/mpv.git && cd mpv -/usr/bin/python3 bootstrap.py -``` - -Finally, compile and install mpv. Binaries will be installed to -``/mingw64/bin`` or ``/mingw32/bin``. - -```bash -/usr/bin/python3 waf configure CC=gcc.exe --check-c-compiler=gcc --prefix=$MSYSTEM_PREFIX -/usr/bin/python3 waf install -``` +# Set up the build directory with the desired configuration +meson setup build -Dlibmpv=true --prefix=$MSYSTEM_PREFIX -Or, compile and install both libmpv and mpv: +# Compile +meson compile -C build -```bash -/usr/bin/python3 waf configure CC=gcc.exe --check-c-compiler=gcc --enable-libmpv-shared --prefix=$MSYSTEM_PREFIX -/usr/bin/python3 waf install +# Optionally, install the compiled binaries +meson install -C build ``` -Linking libmpv with MSVC programs ---------------------------------- +## Running mpv -mpv/libmpv cannot be built with Visual Studio (Microsoft is too incompetent to -support C99/C11 properly and/or hates open source and Linux too much to -seriously do it). But you can build C++ programs in Visual Studio and link them -with a libmpv built with MinGW. +Depending on your build configuration, ``mpv.exe`` may rely on external +libraries. To create a portable package, you will need to include these +dependencies as well. The quickest way to determine which libraries are needed +is to run ``mpv.exe`` and note any error messages that list the required ``.dll`` +files. You can find these libraries in the sysroot used for compilation, such as +``/clang64/bin/`` in MSYS2. -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: +## Linking libmpv with MSVC Programs -```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. +Building mpv/libmpv directly with the MSVC compiler (cl.exe) is not supported +due to differences in compiler flags. Our build system is designed specifically +for GNU-like compiler drivers. However, you can still build programs in +Visual Studio and link them with libmpv. -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 +If the toolchain used generates a ``.lib`` file, it will be ready for use. +Otherwise, you will need to create an import library for the mpv DLL with the +following command: ```bash -pacman -S winpty -winpty mpv.com ToS-4k-1920.mov +lib /name:mpv-2.dll /out:mpv.lib /MACHINE:X64 ``` -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: +Ensure that the string in the ``/name:`` parameter matches the filename of the +DLL, as this is the filename that the MSVC linker will reference. -https://mpv.srsfckn.biz/d3dcompiler.7z +**Note:** Static linking is only feasible with matching compilers. For instance, +if you build with Clang in Visual Studio, static linking is possible. diff --git a/DOCS/contribute.md b/DOCS/contribute.md index 48307d9658..4d2af4ea4e 100644 --- a/DOCS/contribute.md +++ b/DOCS/contribute.md @@ -5,13 +5,13 @@ General ------- The main contact for mpv development is IRC, specifically #mpv -and #mpv-devel on Libera.chat. Github is used for code review and +and #mpv-devel on Libera.chat. GitHub is used for code review and long term discussions. Sending patches --------------- -- Make a github pull request, or send a link to a plaintext patch created with +- Make a GitHub pull request, or send a link to a plaintext patch created with ``git format-patch``. - Plain diffs posted as pastebins are not acceptable! (Especially if the http link returns HTML.) They only cause extra work for everyone, because they lack @@ -68,6 +68,11 @@ Write good commit messages 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``. + + Sample prefixes: ``vo_gpu: ...``, ``command: ...``, ``DOCS/input: ...``, + ``TOOLS/osxbundle: ...``, ``osc.lua: ...``, etc. You can always check the git + log for commits which modify specific files to see which prefixes are used. + - The first word after the ``:`` is lower case. - Don't end the subject line with a ``.``. - Put an empty line between the subject line and the commit message. @@ -106,13 +111,13 @@ Always squash fixup commits when making changes to pull requests - If you make fixup commits to your pull request, you should generally squash them with "git rebase -i". We prefer to have pull requests in a merge ready state. -- We don't squash-merge (nor do we use github's feature that does this) because +- We don't squash-merge (nor do we use GitHub's feature that does this) because pull requests with multiple commits are perfectly legitimate, and the only thing that makes sense in non-trivial cases. - With complex pull requests, it *may* make sense to keep them separate, but they should be clearly marked as such. Reviewing commits is generally easier with fixups squashed. -- Reviewers are encouraged to look at individual commits instead of github's +- Reviewers are encouraged to look at individual commits instead of GitHub's "changes from all commits" view (which just encourages bad git and review practices). @@ -126,16 +131,28 @@ Touching user-visible parts may require updating the mpv docs - Changes to command line options (addition/modification/removal) must be documented in options.rst. - Changes to input properties or input commands must be documented in input.rst. -- All incompatible changes to the user interface (options, properties, commands) - must be documented with a small note in interface-changes.rst. (Additions may - be documented there as well, but this isn't required.) - Changes to the libmpv API must be reflected in the libmpv's headers doxygen, and in client-api-changes.rst. +Interface change policy +----------------------- + +- All incompatible changes to the user interface (options, properties, commands) + must be documented by making a new text file with a txt extension containing a + small note in the DOCS/interface-changes directory. +- The name of the file should be brief and related to the commit that makes the + change. +- Grouping multiple related changes in the same file is also OK. Just be sure to + put each separate change on a different line. +- Documenting additions in DOCS/interface-changes is optional but encouraged. +- interface-changes.rst is never directly updated except when making new major + releases. +- See DOCS/interface-changes/example.txt for an example. + Code formatting --------------- -mpv uses C99 with K&R formatting, with some exceptions. +mpv uses C11 with K&R formatting, with some exceptions. - Use the K&R indent style. - Use 4 spaces of indentation, never use tabs (except in Makefiles). @@ -148,9 +165,9 @@ mpv uses C99 with K&R formatting, with some exceptions. some_function(a, b, c); } ``` -- Break lines |