libplacebo

libplacebo is, in a nutshell, the core rendering algorithms and ideas of mpv rewritten as an independent library. As of today, libplacebo contains a large assortment of video processing shaders, focusing on both quality and performance. These include features such as the following:

• High-quality, optimized upscaling and downscaling including support for polar filters (“Jinc”), anti-aliasing, anti-ringing and gamma correct scaling.
• Dynamic HDR tone mapping, including real-time measurement of scene histogram, scene change detection, dynamic exposure control, perceptual gamut stretching, contrast recovery and more.
• Native support for Dolby Vision HDR, including Profile 5 conversion to HDR/PQ or SDR, reading DV side data, and reshaping. (BL only, currently)
• A colorimetrically accurate color management engine with support for soft gamut mapping, ICC profiles, accurate ITU-R BT.1886 emulation, black point compensation, and custom 3DLUTs (.cube).
• A pluggable, extensible custom shader system. This can be used to arbitrarily extend the range of custom shaders to include popular user shaders like RAVU, FSRCNNX, or Anime4K. See the mpv wiki on user scripts for more information.
• High performance film grain synthesis for AV1 and H.274, allowing media players to offload this part of decoding from the CPU to the GPU.
• Tunable, fast debanding and deinterlacing shaders.
• High quality gamma-correct dithering, including error diffusion modes.

Every attempt was made to provide these features at a high level of abstraction, taking away all the messy details of GPU programming, color spaces, obscure subsampling modes, image metadata manipulation, and so on. Expert-level functionality is packed into easy-to-use functions like pl_frame_from_avframe and pl_render_image.

Hardware requirements

libplacebo currently supports Vulkan (including MoltenVK), OpenGL, and Direct3D 11. It currently has the following minimum hardware requirements:

• Vulkan: Core version 1.2
• OpenGL: GLSL version >= 130 (GL >= 3.0, GL ES >= 3.0)
• Direct3D: Feature level >= 9_1

For more documentation, including an introduction to the API, see the project website.

History

This project grew out of an interest to accomplish the following goals:

• Clean up mpv’s internal RA API and make it reusable for other projects, as a general high-level backend-agnostic graphics API wrapper.
• Provide a standard library of useful GPU-accelerated image processing primitives based on GLSL, so projects like media players or browsers can use them without incurring a heavy dependency on libmpv.
• Rewrite core parts of mpv’s GPU-accelerated video renderer on top of redesigned abstractions, in order to modernize it and allow supporting more features.

It has since been adopted by VLC as their optional Vulkan-based video output path, and is provided as a Vulkan-based video filter in the FFmpeg project.

Obtaining

When cloning libplacebo, make sure to provide the --recursive flag:

git clone --recursive https://code.videolan.org/videolan/libplacebo

Alternatively (on an existing clone):

git submodule update --init

Doing either of these pulls in a handful of bundled 3rdparty dependencies. Alternatively, they can be provided via the system.

Building from source

libplacebo is built using the meson build system. You can build the project using the following steps:

DIR=./build
meson $DIR
ninja -C$DIR

To rebuild the project on changes, re-run ninja -Cbuild. If you wish to install the build products to the configured prefix (typically /usr/local/), you can run ninja -Cbuild install. Note that this is normally ill-advised except for developers who know what they’re doing. Regular users should rely on distro packages.

Dependencies

In principle, libplacebo has no mandatory dependencies — only optional ones. However, to get a useful version of libplacebo, you most likely want to build with support for either opengl, vulkan or d3d11. libplacebo built without these can still be used (e.g. to generate GLSL shaders such as the ones used in VLC), but the usefulness is severely impacted since most components will be missing, impaired or otherwise not functional.

A full list of optional dependencies each feature requires:

• glslang: glslang + its related libraries (e.g. libSPIRV.so)
• lcms: liblcms2
• libdovi: libdovi
• opengl: glad2 (*)
• shaderc: libshaderc
• vulkan: libvulkan, python3-jinja2 (*)
• xxhash: libxxhash

(*) This dependency is bundled automatically when doing a recursive clone.

Authors

libplacebo was founded and primarily developed by Niklas Haas (@haasn), but it would not be possible without the contributions of others, especially support for windows.

License

libplacebo is currently available under the terms of the LGPLv2.1 (or later) license. However, it’s possible to release it under a more permissive license (e.g. BSD2) if a use case emerges. Please open an issue if you have a use case for a BSD2-licensed libplacebo.