libde265 - open h.265 codec implementation

WebAssembly build README

Notes:

• WebAssembly SIMD is enabled, but not all instructions used by libde265 are supported, some are simulated using other instructions.
• This library is compute-intensive, it should be ran in a worker to prevent blocking main event loop.
• When using Vite, add this package to optimizeDeps.exclude to workaround its broken dependency "optimizer".

Unsupported:

• Multithreading (because my use case doesn't allow SharedArrayBuffer)
• Logging

Usage:

Check an example project at https://github.com/yume-chan/libde265-example

import initialize from "@yume-chan/libde265";

const Module = await initialize();

const Decoder = new Module.Decoder();
// Or with ES resource management
// using Decoder = new Module.Decoder();

// Your data handler
function onData(data: Uint8Array, pts: bigint) {
    // If needs to restart decoding (skipping frames, seeking, etc.)
    Decoder.reset();

    // `pts` is not used for decoding
    // only passthrough to `image.pts`
    // for you to identify frames
    Decoder.pushData(chunk, pts);
    // Or if `data` is one NAL unit
    // Decoder.pushNal(chunk, pts);

    // Optional, if you know NAL boundary
    Decoder.pushEndOfNal();

    // Optional, if you know frame boundary
    Decoder.pushEndOfFrame();

    // If input stream ends
    Decoder.flushData();

    let more = true;
    // Loop if `chunk` may contain multiple frames
    while (more) {
        const result = Decoder.decode();
        more = result.more;

        if (!Module.isOk(result.error)) {
            // Needs more data
            if (result.error === Module.Error.ERROR_WAITING_FOR_INPUT_DATA) {
                return;
            }

            // Other non-recoverable errors
            console.error(result.error, Module.getErrorText(result.error));
            controller.error();
            return;
        }

        // Read next decoded frame
        const image = Decoder.getNextPicture();
        if (!image) {
            continue;
        }

        // Get data for each planes
        // 0,1,2 for Y,Cb,Cr
        const y = image.getImagePlane(0);
        const u = image.getImagePlane(1);
        const v = image.getImagePlane(2);

        // Draw frame yourself...

        // Cleanup the image, otherwise `Decoder.decode` will return `ERROR_IMAGE_BUFFER_FULL`
        image.delete();
    }
}

// Cleanup if not using resource management (`using`)
Decoder.delete();

Build:

docker run --rm -v $(pwd):$(pwd) -w $(pwd) -it docker.io/emscripten/emsdk bash build.sh

or

podman run --rm -v $(pwd):$(pwd) --userns=keep-id -w $(pwd) -it docker.io/emscripten/emsdk bash build.sh

Then check the build/wasm folder.

Original README below

libde265 is an open source implementation of the h.265 video codec. It is written from scratch and has a plain C API to enable a simple integration into other software.

libde265 supports WPP and tile-based multithreading and includes SSE optimizations. The decoder includes all features of the Main profile and correctly decodes almost all conformance streams (see [wiki page]).

A list of supported features are available in the wiki.

For latest news check our website at http://www.libde265.org

The library comes with two example programs:

• dec265, a simple player for raw h.265 bitstreams. It serves nicely as an example program how to use libde265.

• sherlock265, a Qt-based video player with the additional capability to overlay some graphical representations of the h.265 bitstream (like CU-trees, intra-prediction modes).

Example bitstreams can be found, e.g., at this site: ftp://ftp.kw.bbc.co.uk/hevc/hm-10.1-anchors/bitstreams/ra_main/

Approximate performance for WPP, non-tiles streams (measured using the timehevc tool from the GStreamer plugin). The tool plays a Matroska movie to the GStreamer fakesink and measures the average framerate.

| Resolution | avg. fps | CPU usage | | ----------------- | -------- | --------- | | 720p | 284 fps | 39 % | | 1080p | 150 fps | 45 % | | 4K | 36 fps | 56 % |

Environment:

• Intel(R) Core(TM) i7-2700K CPU @ 3.50GHz (4 physical CPU cores)
• Ubuntu 12.04, 64bit
• GStreamer 0.10.36

Building

libde265 uses the CMake build system. Please do not use to deprecated autotools scripts. To compile libde265, run

mkdir build
cd build
cmake ..
make

libde265 has no dependencies on other libraries, but both optional example programs have dependencies on:

• SDL2 (optional for dec265's YUV overlay output),

• Qt (required for sherlock265),

• libswscale (required for sherlock265 if libvideogfx is not available).

• libvideogfx (required for sherlock265 if libswscale is not available, optional for dec265).

Libvideogfx can be obtained from http://www.dirk-farin.net/software/libvideogfx/index.html or http://github.com/farindk/libvideogfx

You can disable building of the example programs by running ./configure with

Additional logging information can be turned on and off using these ./configure flags:

Build using cmake

cmake scripts to build libde265 and the sample scripts dec265 and enc265 are included and can be compiled using these commands:

mkdir build
cd build
cmake ..
make

See the cmake documentation for further information on using cmake on other platforms.

Building using vcpkg

You can build and install libde265 using the vcpkg dependency manager:

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

The libde265 port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository.

Prebuilt binaries

Binary packages can be obtained from this launchpad site.

Software using libde265

Libde265 has been integrated into these applications:

• libheif source

• gstreamer plugin, source, binary packages.

• VLC plugin source, binary packages.

• Windows DirectShow filters, https://github.com/strukturag/LAVFilters/releases

• ffmpeg fork, https://github.com/farindk/ffmpeg

• ffmpeg decoder source

• libde265.js JavaScript decoder source, demo.

Packaging status

License

The library libde265 is distributed under the terms of the GNU Lesser General Public License. The sample applications are distributed under the terms of the MIT license.

See COPYING for more details.

The short video clip in the 'testdata' directory is from the movie 'Girl Shy', which is in the public domain.

Copyright (c) 2013-2014 Struktur AG Copyright (c) 2013-2025 Dirk Farin Contact: Dirk Farin [email protected]