# libplacebo: mpv's GPU video rendering pulled out into a tiered C library

> libplacebo is the rendering core of mpv rebuilt as an independent C library, aimed at player and browser projects that want colour-managed GPU video output without taking on libmpv. It is well specified and recently pushed, but its hardware floors and its API tiers are decisions you have to accept before you adopt it.

**haasn/libplacebo** — Official mirror of libplacebo

- Repository: https://github.com/haasn/libplacebo
- Website: http://libplacebo.org/
- Stars: 798 · Forks: 136
- Language: C
- License: LGPL-2.1
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/haasn-libplacebo

## Why mpv's renderer became a standalone C library

libplacebo is, in the project's own words, the core rendering algorithms and ideas of mpv rewritten as an independent library. The repository you would clone from haasn is labelled the official mirror of libplacebo, with C as its primary language and http://libplacebo.org/ as its homepage. The upstream history section lists three goals: cleaning up mpv's internal rendering abstraction API so that it could be reused by other projects as a general high level, backend agnostic graphics API wrapper; providing a standard library of useful GPU accelerated image processing primitives based on GLSL, so that projects such as media players or browsers could use them without incurring a heavy dependency on libmpv; and rewriting the core parts of mpv's GPU accelerated video renderer on top of redesigned abstractions.

That origin explains the shape of the whole thing. This is not a media player, and it does not demux, decode, or handle audio. It is a rendering backend that other projects embed. Every judgement about it depends on that boundary: what it replaces is somebody else's video output stage, and what it demands of you is a frame bridge of your own.

## Tier 0 holds the plumbing: caching, colourspace maths, filter kernels

The public API is split into components whose headers and documentation sit inside src/include/libplacebo, and the split is organised into tiers that represent levels of abstraction inside the library. Higher tiers depend on lower ones. Tier 0 is described as logging and raw math primitives, and it is where the reusable machinery lives.

cache.h is the caching subsystem, used for large or computationally heavy binary blobs such as compiled shaders and 3DLUTs. colorspace.h holds enums and structs for describing colour spaces plus helpers for computing colour space transformation matrices. log.h is the logging subsystem. common.h collects miscellaneous utility types and macros shared among subsystems and is usually not included directly. config.h defines macros describing how the library was built, including version strings and compiled in features and dependencies, which can be useful for feature tests. dither.h generates noise and dithering matrices. filters.h contains reusable reconstruction filter kernels for scaling, together with the structs needed to define a kernel for the upscaling routines. tone_mapping.h collects the tone mapping functions used for conversions between HDR and SDR content.

## Choosing a tier means choosing how much of the pipeline you keep

The API overview is explicit that which tier you use depends on how much power and control you want over the actual rendering. The low level tiers are described as more suitable for big projects that need strong control over the entire rendering pipeline, while the high level tiers are more suitable for smaller or simpler projects that want libplacebo to take care of everything.

The stated design aim is a high level of abstraction that takes away the messy details of GPU programming, colour spaces, obscure subsampling modes and image metadata manipulation. The two function names the documentation picks out as examples of expert level functionality packed into easy to use calls are:

```c
pl_frame_from_avframe
pl_render_image
```

Read as a pipeline, that pair says convert a decoded frame into libplacebo's own frame type, then render it. If your project starts from an FFmpeg style AVFrame, the first call is your entry point and the second is your output path. If you need to intervene between decode and display, you are heading for the lower tiers instead, and that is the choice worth making deliberately.

## Colour management and HDR tone mapping are the real payload

The feature list is where the library goes well beyond what a player needs. Upscaling and downscaling are described as high quality and optimised, with polar filters such as Jinc, anti aliasing, anti ringing and gamma correct scaling. Tone mapping is dynamic rather than a fixed curve, with real time measurement of the scene histogram, scene change detection, dynamic exposure control, perceptual gamut stretching and contrast recovery.

Dolby Vision HDR has native support, including Profile 5 conversion to HDR/PQ or SDR, reading DV side data, and reshaping. The colour management engine is described as colorimetrically accurate, with soft gamut mapping, ICC profiles, accurate ITU-R BT.1886 emulation, black point compensation, and custom 3DLUTs in .cube form. Around those sit high performance film grain synthesis for AV1 and H.274, which lets a player move that part of decoding from the CPU to the GPU, tunable and fast debanding and deinterlacing shaders, and high quality gamma correct dithering including error diffusion modes.

## Custom shaders extend the pipeline instead of replacing it

The shader system is described as pluggable and extensible, with its own documentation site for custom shaders. The README names popular user shaders such as RAVU, FSRCNNX and Anime4K as things that can be included in that range, and points at the mpv wiki page on user scripts for information about how user shaders are wired up in a player.

The distinction is worth stating plainly, because it is where integrators get confused. A custom shader in libplacebo is a stage inside a pipeline that already has a colour engine, an upscaler and a tone mapper around it. It is not an alternative renderer that takes a decoded frame and produces a picture on its own. The upside is that you inherit the colour correctness of the surrounding stages. The cost is that the extension mechanism is documented off repository, so anyone adopting it needs to read the project website and the mpv wiki page in addition to the source tree.

## Building from this mirror: build files present, build steps absent

This mirror's top level holds meson.build and meson_options.txt for the build system, a compile directory, demos/, docs/, tools/, win32/ and 3rdparty/, alongside .gitlab-ci.yml, RELEASING.md, gcovr.cfg and mkdocs.yml. The README gives no install command and no build command, so there is nothing here that can be copied into a terminal as a first real use. The project directs readers to its website for further documentation including an introduction to the API, and the homepage is http://libplacebo.org/.

The practical first step is the included demo. The README points at a demo program with source at demos/plplay.c, and the screenshots it shows are captures of that demo with its settings panels open, describing features of the libplacebo rendering code that are adjustable dynamically during video playback. That demo is the fastest way to see which of the tuning knobs you actually want before committing an application to the API.

## Where libplacebo is the wrong tool

The stated hardware floors are the first constraint: Vulkan core version 1.2, OpenGL with GLSL version 130 or greater (GL 3.0 and up, or GL ES 3.0 and up), and Direct3D feature level 9_1 or higher, with Vulkan support including MoltenVK. Systems with none of those three paths are out of scope.

The second constraint is scope. libplacebo renders video. It does not decode, demux, play, or handle audio, so a project wanting any of those still needs another component. The third is the cost of the abstraction: where the alternative is to use mpv's own GPU renderer through libmpv, libplacebo gives you a standalone library with tiers and headers, and you take on writing the bridge between your decoded frames and pl_frame_from_avframe yourself. For teams already shipping an FFmpeg based pipeline the trade is different: libplacebo is provided as a Vulkan based video filter in the FFmpeg project, so that route delivers the colour and HDR work only where a Vulkan output path is in play, while VLC takes it on as an optional Vulkan based video output path rather than as its default renderer.

## LGPL-2.1 and the shape of the release numbers

The mirror carries the LGPL-2.1 licence, and that is what governs redistribution of the library when you ship it inside a player, a browser build or a filter. Whether a specific distribution model satisfies those obligations is a question for your own legal review, not something this article can settle.

On maintenance, the mirror is not archived and the last push was on 2026-10-22, so commits are landing now rather than in a slow drift. The tagged releases visible in the mirror are v7.360.1 from 2026-03-13, v7.360.0 from 2026-02-11 and v7.351.0 from 2025-05-21. The presence of RELEASING.md and a.gitlab-ci.yml at the top level indicates that release and continuous integration steps are documented and automated in the repository. For a library consumed as a dependency, those numbers are the versions you would pin against, so check them when you pick a revision rather than tracking master.

## Conclusion

libplacebo fits teams building a media player, a browser video path, or an FFmpeg-style filter that need correct colour and HDR handling on the GPU, and who can meet the Vulkan, OpenGL or Direct3D 11 floor and are willing to write the frame bridge. It does not fit projects that want a player, an audio path, or a working renderer out of the box. Before adopting it, check the tier list under src/include/libplacebo against the control you actually need, read the shader documentation at http://libplacebo.org/ since the custom shader system is documented off repository, and confirm your licence obligations for LGPL-2.1 redistribution with your own legal review.

## FAQ

### What hardware does libplacebo need to run?

The stated minimums are Vulkan core version 1.2, OpenGL with GLSL version 130 or greater (GL 3.0 or up, GL ES 3.0 or up), and Direct3D feature level 9_1 or higher. Vulkan support includes MoltenVK, so Apple platforms are covered through that path.

### How is libplacebo related to mpv?

libplacebo is the core rendering algorithms and ideas of mpv rewritten as an independent library, so that the rendering layer can be reused by other projects. Projects such as media players or browsers can use its GPU accelerated image processing primitives without taking on a heavy dependency on libmpv.

### Can I use libplacebo with VLC or FFmpeg?

Yes. It has been adopted by VLC as their optional Vulkan based video output path, and it is provided as a Vulkan based video filter in the FFmpeg project, so in both cases the colour and HDR features arrive through a Vulkan route rather than as a default renderer.

### How do I build libplacebo from this repository?

The repository ships meson.build, meson_options.txt, a compile directory, demos/, docs/, tools/ and win32/, but the README gives no install or build commands. The project points to its website at http://libplacebo.org/ for documentation and an introduction to the API, and demos/plplay.c is the included demo program.

## Sources

- [haasn/libplacebo on GitHub](https://github.com/haasn/libplacebo)
- [License: LGPL-2.1](https://github.com/haasn/libplacebo/blob/master/LICENSE)
- [Project website](http://libplacebo.org/)
- [README](https://github.com/haasn/libplacebo/blob/master/README.md)
- [Releases](https://github.com/haasn/libplacebo/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/haasn-libplacebo