summaryrefslogtreecommitdiffstats
path: root/DOCS
diff options
context:
space:
mode:
Diffstat (limited to 'DOCS')
-rw-r--r--DOCS/client-api-changes.rst30
-rw-r--r--DOCS/compatibility.rst24
-rw-r--r--DOCS/compile-windows.md429
-rw-r--r--DOCS/contribute.md70
-rw-r--r--DOCS/edl-mpv.rst20
-rw-r--r--DOCS/encoding.rst74
-rw-r--r--DOCS/interface-changes.rst386
-rw-r--r--DOCS/interface-changes/console-scale-with-window.rst1
-rw-r--r--DOCS/interface-changes/display-page-toggle.txt1
-rw-r--r--DOCS/interface-changes/example.txt1
-rw-r--r--DOCS/interface-changes/geometry-behavior.txt1
-rw-r--r--DOCS/interface-changes/load-console.txt1
-rw-r--r--DOCS/interface-changes/nvidia-true-hdr.txt1
-rw-r--r--DOCS/interface-changes/osc-buttons.txt4
-rw-r--r--DOCS/interface-changes/osd-bar-marker.txt2
-rw-r--r--DOCS/interface-changes/script-opt.txt1
-rw-r--r--DOCS/interface-changes/stats-sizes.rst1
-rw-r--r--DOCS/interface-changes/stats-term-clip.txt3
-rw-r--r--DOCS/interface-changes/term-clip-cc.txt1
-rw-r--r--DOCS/interface-changes/video-frame-info-timecode.txt1
-rw-r--r--DOCS/interface-changes/ytdl_hook-include.txt1
-rw-r--r--DOCS/man/af.rst70
-rw-r--r--DOCS/man/ao.rst150
-rw-r--r--DOCS/man/changes.rst3
-rw-r--r--DOCS/man/console.rst165
-rw-r--r--DOCS/man/encode.rst23
-rw-r--r--DOCS/man/input.rst1445
-rw-r--r--DOCS/man/ipc.rst17
-rw-r--r--DOCS/man/javascript.rst66
-rw-r--r--DOCS/man/libmpv.rst20
-rw-r--r--DOCS/man/lua.rst242
-rw-r--r--DOCS/man/mpv.rst680
-rw-r--r--DOCS/man/options.rst2950
-rw-r--r--DOCS/man/osc.rst303
-rw-r--r--DOCS/man/stats.rst157
-rw-r--r--DOCS/man/vf.rst151
-rw-r--r--DOCS/man/vo.rst463
-rw-r--r--DOCS/mplayer-changes.rst16
-rw-r--r--DOCS/release-policy.md74
-rw-r--r--DOCS/tech-overview.txt126
-rw-r--r--DOCS/waf-buildsystem.rst157
41 files changed, 5955 insertions, 2376 deletions
diff --git a/DOCS/client-api-changes.rst b/DOCS/client-api-changes.rst
index ade0234e79..8826b875d2 100644
--- a/DOCS/client-api-changes.rst
+++ b/DOCS/client-api-changes.rst
@@ -32,7 +32,32 @@ API changes
::
+ --- mpv 0.39.0 ---
+ 2.4 - mpv_render_param with the MPV_RENDER_PARAM_ICC_PROFILE argument no
+ longer has incorrect assumptions about memory allocation and can be
+ correctly used.
+ --- 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)
+ The opengl_cb API was deprecated over 2 years ago. Use the render API
+ instead.
1.108 - Deprecate MPV_EVENT_IDLE
- add mpv_event_start_file
- add the following fields to mpv_event_end_file: playlist_entry_id,
@@ -50,7 +75,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
@@ -68,7 +92,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
@@ -260,7 +283,6 @@ 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..9befbbb2a6 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.
@@ -108,7 +126,7 @@ CLI
Things such as default key bindings do not necessarily require compatibility.
However, the release notes should be extremely clear on changes to "important"
key bindings. Bindings which restore the old behavior should be added to
-restore-old-bindings.conf.
+restore-old-bindings.conf and restore-osc-bindings.conf.
Some option parsing is CLI-only and not available from libmpv or scripting. No
compatibility guarantees come with them. However, the rules which mpv uses to
diff --git a/DOCS/compile-windows.md b/DOCS/compile-windows.md
index 174a882316..4850796a5a 100644
--- a/DOCS/compile-windows.md
+++ b/DOCS/compile-windows.md
@@ -1,213 +1,262 @@
-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
-```
-
-[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/
-
- 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.
-
-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 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
+# 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-7.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
```
-Installing mpv dependencies
----------------------------
+they will be automatically downloaded and built by Meson.
+
+## Native Compilation with Clang (Windows SDK Build)
+
+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
+ - C++ CMake tools for Windows
+ - Windows SDK
+ - Activate the developer shell:
+ ```
+ & "<Visual Studio Path>\Common7\Tools\Launch-VsDevShell.ps1" -Arch amd64 -HostArch amd64 -SkipAutomaticLocation | Out-Null
+ ```
+2. Install Meson, as outlined in [Getting Meson](https://mesonbuild.com/Getting-meson.html):
+3. The following build script utilizes the Meson subprojects system to build mpv and its dependencies.
+ To make sure all dependency versions are up-to-date, update the subprojects database from Meson's WrapDB.
+ Also explicitly download several wraps as some nested projects may pull older versions of them.
+ ```
+ meson wrap update-db
+
+ meson wrap install expat
+ meson wrap install harfbuzz
+ meson wrap install libpng
+ meson wrap install zlib
+ ```
+4. Set environment variables or use the `--native-file` option in Meson.
+ ```powershell
+ $env:CC = 'clang'
+ $env:CXX = 'clang++'
+ $env:CC_LD = 'lld'
+ $env:CXX_LD = 'lld'
+ $env:WINDRES = 'llvm-rc'
+ ```
+ Note that some dependencies (e.g. LuaJIT) may require `sed` to configure. Fortunately, it is already bundled in
+ [Git for Windows](https://www.git-scm.com/download/win):
+ ```powershell
+ $env:PATH += ';<Git Path>\usr\bin'
+ ```
+5. Execute [ci\build-win32.ps1](https://github.com/mpv-player/mpv/blob/master/ci/build-win32.ps1). Refer to the script for more details.
+
+This process will produce a fully static ``mpv.exe`` and ``mpv.com``, as well as
+a static ``libmpv.a``.
+
+## Native Compilation with MSYS2
+
+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.
+
+### Installing 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.
+
+### Updating MSYS2
+
+For guidance on updating MSYS2, please refer to the official documentation:
+[Updating MSYS2](https://www.msys2.org/docs/updating/).
+
+### Installing mpv Dependencies
+
+``` bash
+# Install pacboy and git
+pacman -S pactoys git
-```bash
# Install MSYS2 build dependencies and a MinGW-w64 compiler
-pacman -S git python $MINGW_PACKAGE_PREFIX-{pkg-config,gcc}
+pacboy -S python pkgconf cc meson
-# 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 vulkan-headers
```
-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.
-
-```bash
-git clone https://github.com/mpv-player/mpv.git && cd mpv
-/usr/bin/python3 bootstrap.py
-```
+### Building mpv
-Finally, compile and install mpv. Binaries will be installed to
-``/mingw64/bin`` or ``/mingw32/bin``.
+To compile and install mpv, execute the following commands.
+The binaries will be installed in the directory ``/$MSYSTEM_PREFIX/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
----------------------------------
-
-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.
+## Running mpv
-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:
+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.
-```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.
+## Linking libmpv with MSVC Programs
-Static linking is not possible.
+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.
-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 e3d98f3da7..d0aa0ef6ae 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 Freenode. 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
@@ -42,7 +42,7 @@ Copyright of contributions
this. If the license of the code is not LGPLv2.1+, you must mention this.
- These license statements are legally binding.
- Don't use fake names (something that looks like an actual name, and may be
- someone else's name, but is not your legal name). Using a pseudonyms is
+ someone else's name, but is not your legal name). Using a pseudonym is
allowed if it can be used to identify or contact you, even if whatever
account you used to submit the patch dies.
- Do not add your name to the license header. This convention is not used by
@@ -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.
@@ -100,6 +105,22 @@ Split changes into multiple commits
as possible. Commits should form logical steps in development. The way you
split changes is important for code review and analyzing bugs.
+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
+ 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
+ "changes from all commits" view (which just encourages bad git and review
+ practices).
+
Touching user-visible parts may require updating the mpv docs
-------------------------------------------------------------
@@ -110,16 +131,31 @@ 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. The content of the file should begin with the type of the change