strukturag/libde265: A C++ HEVC Decoder with a Plain C API

libde265's HEVC decoding scope

libde265 addresses the narrow but substantial problem of decoding H.265 or HEVC video inside another software product. It is a codec library rather than a complete video player. The README describes a plain C API intended to simplify integration into applications written in other languages. That boundary matters. A media application may still need container demuxing, audio handling, colour management, display, seeking and playback synchronization, none of which are described as features of libde265 itself.

The implementation is written from scratch in C++. Its decoder includes all features of the Main profile. It also supports Main 10 and Range Extensions, including bit depths from 8 to 16 bits independently for luma and chroma. The documented chroma formats are 4:2:0, 4:2:2, 4:4:4 and monochrome. This gives an integrator more control than a decoder limited to one common 8-bit format, although it also places more responsibility on the surrounding application for interpreting the output correctly.

The project is aimed at software developers who need HEVC decoding as a component. The listed integrations include libheif, a GStreamer plugin, VLC plugins, Windows DirectShow filters and ffmpeg-related decoder code. Those integrations show intended integration paths, but they do not guarantee identical feature sets or compatibility across every deployment.

SIMD, WPP and tile processing

The decoder uses WPP and tile-based multithreading, and the README identifies SSE, AVX2 and AVX-512 optimizations. These mechanisms matter because HEVC decoding contains repetitive pixel and prediction operations where CPU-specific implementations can reduce decoding overhead. The project documentation also explains that optimized non-Debug builds hide internal symbols while retaining the public API. That is a deliberate library boundary: applications can call the public interface without depending on internal symbols.

The main limitation is that performance depends on the processor, stream structure and build configuration. The README publishes approximate measurements for WPP, non-tile streams using the `timehevc` tool from the GStreamer plugin. Those figures were collected on Ubuntu 12.04 with a 3.50 GHz Intel Core i7-2700K and GStreamer 0.10.36. The table reports 284 fps at 720p, 150 fps at 1080p and 36 fps at 4K. The documentation does not establish that the same results apply to a different CPU, operating system, thread configuration or modern compiler.

WPP and tiles also do not guarantee identical behaviour for every stream. The README says the decoder supports these features and reports almost complete conformance-stream decoding, but it does not document a fallback policy, stream-level error recovery interface or exact handling of malformed streams. Applications that receive damaged network video should not treat the conformance statement as a complete error-handling specification.

Building the decoder with CMake

The documented build path uses CMake and does not require other libraries for libde265 itself. The example applications have optional or conditional dependencies. SDL2 can provide YUV overlay output for `dec265`, while `sherlock265` requires Qt. `sherlock265` also needs `libswscale` unless `libvideogfx` is available. `libvideogfx` is listed as the alternative for the latter case and as optional support for `dec265`.

From a checkout of the repository, the following commands create a build directory, configure the project and compile it. The README presents these commands as the basic build procedure. The output should include the library and, unless disabled, the example programs described later in the documentation.

mkdir build
cd build
cmake ..
make

Applications that do not need either example program can turn them off during configuration. The README gives these exact CMake options.

-DENABLE_DECODER=off
-DENABLE_SHERLOCK265=off

For library distributions, visibility is another build choice. An optimized decoder-only build hides all symbols except the public API. If an application or internal tooling needs all symbols exported, the documented setting is `-DFORCE_FULL_VISIBILITY=on`. This setting can enlarge the shared library and affects symbol exposure, so it should be selected deliberately rather than treated as a performance flag.

Installing through vcpkg and using dec265

The README documents a vcpkg installation route. This is useful for projects that already use Microsoft vcpkg and want dependency acquisition handled by an existing package workflow. The documented commands clone vcpkg, bootstrap its command-line tool, integrate installation and install the `libde265` port.

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh
./vcpkg integrate install
./vcpkg install libde265

The README says the port is maintained by Microsoft team members and community contributors. If the version is out of date, it directs users to create an issue or pull request in the vcpkg repository. That maintenance statement applies to the vcpkg port, not necessarily to every downstream binary package.

For a first real build use, the repository provides `dec265`, described as a simple player for raw H.265 bitstreams and also as an example of how to use libde265. The README does not provide a complete `dec265` command line or argument example, so it would be inaccurate to invent an invocation or claim a particular output format. The confirmed first step is to build `dec265` with the default CMake configuration, then consult the executable's platform documentation before supplying a local bitstream. `sherlock265` is a Qt-based visual inspection player that can overlay representations such as CU trees and intra-prediction modes, but it is not a minimal dependency-free starting point.

libde265 compared with an ffmpeg-based decoder

libde265 and the ffmpeg decoder listed in the README address overlapping needs through different integration boundaries. libde265 is a codec-focused library with a plain C API. An application can use it as a relatively direct HEVC decoding component, then handle its own application-level media pipeline. The README points to `libde265-ffmpeg` as a decoder source and describes an ffmpeg fork, which indicates another route through ffmpeg's broader media framework.

The practical difference is not that one project necessarily decodes more HEVC streams. The README does not provide a feature-by-feature comparison of libde265 against ffmpeg. It does show that ffmpeg is a wider media ecosystem, while libde265 exposes a focused library and example programs. A team already standardized on ffmpeg may prefer the ffmpeg integration to avoid adding a separate codec library. A team needing direct control over the HEVC decoder interface, supported pixel formats or decoder internals may find libde265's narrower API more appropriate. Neither choice removes the need to inspect the actual stream format and expected error behaviour.

Licensing, maintenance and upgrade implications

The library is distributed under the terms of the GNU Lesser General Public License, while the sample applications are distributed under the MIT license. The README points to `COPYING` for details and identifies the short `testdata` video as a public-domain clip. This split creates an important packaging distinction: an application should not assume that the licence of `dec265` or `sherlock265` is the same as the licence of the library.

The repository is not archived, and its last push was on 2026-09-29. The listed recent releases include v1.1.3 on 2026-09-14, v1.1.2 on 2026-09-02 and v1.1.1 on 2026-06-03. The release descriptions mention high bit depth and Range Extensions, security and bug fixes, and speed improvements. The repository layout includes `SECURITY.md`, `ChangeLog`, `NEWS`, test data, fuzzing and development tools, which indicates more than a minimal decoder wrapper.

An upgrade can therefore involve checking codec compatibility, API changes, build options, dependency changes and security notes. The README does not document a formal upgrade procedure or compatibility policy. Reviewing `COPYING`, `ChangeLog`, `NEWS` and `SECURITY.md` is the concrete next step for a deployment that already links libde265.

Editorial conclusion

Choose libde265 when an application needs a direct HEVC decoding library and can manage its C API, build system and custom licence terms. Do not assume it is a complete media player or a replacement for container, audio and playback infrastructure. Verify the required profile, pixel format, threading path, platform dependencies and the exact `COPYING` obligations before adoption.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. strukturag/libde265 on GitHub