HEVC / H.265 Annex B Decoder (Run)

This article explains how you can use Transcoder::run to decode a HEVC / H.265 Annex B elementary stream to a raw YUV video file.

The code snippets in this article are from the dec_hevc_file macOS sample.

Linux and Windows samples are also available:

• dec_hevc_file (Linux)

• dec_hevc_file (Windows)

Source Video

For source we use a HEVC-encoded video file. After downloading and unzipping the AVBlocks Assets archive, you can find HEVC test files in the vid subdirectory.

Code

This code takes a compressed HEVC elementary stream file and decodes it to raw YUV video format.

Initialize AVBlocks

The first step in any AVBlocks application is to initialize the library. This must be done before using any other AVBlocks functionality. The Library::initialize() method sets up the internal state and loads necessary codecs. Always remember to call Library::shutdown() at the end of your program to properly clean up resources and release any allocated memory.

int main(int argc, char* argv[])
{
    Options opt;
    
    switch(prepareOptions(opt, argc, argv))
    {
        case Command: return 0;
        case Error:	return 1;
        case Parsed: break;
    }
    
    Library::initialize();
    
    bool decodeResult = decodeHevcFile(opt);
    
    Library::shutdown();
    
    return decodeResult ? 0 : 1;
}

Configure Input Socket

The input socket defines the source HEVC elementary stream. We use MediaInfo to automatically detect the video parameters from the input file. This is more convenient than manually specifying parameters, as MediaInfo reads the stream headers and extracts all necessary information about the encoded video, including resolution, frame rate, and codec settings.

bool decodeHevcFile(Options& opt)
{
    // transcoder will fail if output exists (by design)
    deleteFile(primo::ustring(opt.outputFile));
    
    auto mediaInfo = primo::make_ref(Library::createMediaInfo());
    mediaInfo->inputs()->at(0)->setFile(primo::ustring(opt.inputFile));
    
    if(!mediaInfo->open())
    {
        printError("MediaInfo open:", mediaInfo->error());
        return false;
    }
    
    // create input socket
    auto inputSocket = primo::make_ref(Library::createMediaSocket(mediaInfo.get()));
    
    // ...existing code...
}

Configure Output Socket

The output socket defines where and how the decoded raw YUV video data will be written. We configure it to output an uncompressed YUV 4:2:0 video file. The socket represents the output destination, while the pin represents the specific video stream within that destination. By setting ColorFormat::YUV420, we ensure the output uses the standard YUV 4:2:0 planar format, which is the most common format for raw video and provides a good balance between quality and file size.

primo::ref<MediaSocket> createOutputSocket(Options& opt)
{
    auto socket = primo::make_ref(Library::createMediaSocket());
    socket->setFile(primo::ustring(opt.outputFile));
    socket->setStreamType(StreamType::UncompressedVideo);
    
    auto pin = primo::make_ref(Library::createMediaPin());
    socket->pins()->add(pin.get());
    
    auto vsi = primo::make_ref(Library::createVideoStreamInfo());
    pin->setStreamInfo(vsi.get());
    
    vsi->setStreamType(StreamType::UncompressedVideo);
    vsi->setColorFormat(ColorFormat::YUV420);
    
    return socket;
}

Configure and Run Transcoder

This section shows how to set up the transcoder with the input and output sockets, then run the decoding operation. The setAllowDemoMode(true) call allows the transcoder to work even without a valid license (useful for testing, but not recommended for production). We add our input and output sockets to the transcoder, open it to prepare for processing, run the actual transcoding operation, and finally close it to clean up.

    // create output socket
    auto outputSocket = createOutputSocket(opt);
    
    // create transcoder
    auto transcoder = primo::make_ref(Library::createTranscoder());
    transcoder->setAllowDemoMode(true);
    transcoder->inputs()->add(inputSocket.get());
    transcoder->outputs()->add(outputSocket.get());
    
    if(!transcoder->open())
    {
        printError("Transcoder open", transcoder->error());
        return false;
    }
    
    if(!transcoder->run())
    {
        printError("Transcoder run", transcoder->error());
        return false;
    }
    
    transcoder->close();
    
    cout << "Output: " << opt.outputFile << endl;
    
    return true;

Complete C++ Code

Here’s the complete working example that demonstrates HEVC/H.265 decoding using AVBlocks. This code combines all the previous snippets into a functional program that can be compiled and run. The main function handles command-line argument parsing, initializes AVBlocks, performs the decoding operation, and properly shuts down the library before exiting.

#include <cstdio>
#include <memory.h>

#include <iostream>
#include <iomanip>
#include <fstream>
#include <string>

#include <primo/avblocks/avb.h>

#include <primo/platform/reference++.h>
#include <primo/platform/error_facility.h>
#include <primo/platform/ustring.h>

#include "util.h"
#include "options.h"

using namespace primo::codecs;
using namespace primo::avblocks;
using namespace std;

primo::ref<MediaSocket> createOutputSocket(Options& opt)
{
    auto socket = primo::make_ref(Library::createMediaSocket());
    socket->setFile(primo::ustring(opt.outputFile));
    socket->setStreamType(StreamType::UncompressedVideo);
    
    auto pin = primo::make_ref(Library::createMediaPin());
    socket->pins()->add(pin.get());
    
    auto vsi = primo::make_ref(Library::createVideoStreamInfo());
    pin->setStreamInfo(vsi.get());
    
    vsi->setStreamType(StreamType::UncompressedVideo);
    vsi->setColorFormat(ColorFormat::YUV420);
    
    return socket;
}

bool decodeHevcFile(Options& opt)
{
    // transcoder will fail if output exists (by design)
    deleteFile(primo::ustring(opt.outputFile));
    
    auto mediaInfo = primo::make_ref(Library::createMediaInfo());
    mediaInfo->inputs()->at(0)->setFile(primo::ustring(opt.inputFile));
    
    if(!mediaInfo->open())
    {
        printError("MediaInfo open:", mediaInfo->error());
        return false;
    }
    
    // create input socket
    auto inputSocket = primo::make_ref(Library::createMediaSocket(mediaInfo.get()));
    
    // create output socket
    auto outputSocket = createOutputSocket(opt);
    
    // create transcoder
    auto transcoder = primo::make_ref(Library::createTranscoder());
    transcoder->setAllowDemoMode(true);
    transcoder->inputs()->add(inputSocket.get());
    transcoder->outputs()->add(outputSocket.get());
    
    if(!transcoder->open())
    {
        printError("Transcoder open", transcoder->error());
        return false;
    }
    
    if(!transcoder->run())
    {
        printError("Transcoder run", transcoder->error());
        return false;
    }
    
    transcoder->close();
    
    cout << "Output: " << opt.outputFile << endl;
    
    return true;
}

int main(int argc, char* argv[])
{
    Options opt;
    
    switch(prepareOptions(opt, argc, argv))
    {
        case Command: return 0;
        case Error:	return 1;
        case Parsed: break;
    }
    
    Library::initialize();
    
    bool decodeResult = decodeHevcFile(opt);
    
    Library::shutdown();
    
    return decodeResult ? 0 : 1;
}

How to Run

See the build instructions for macOS and the dec_hevc_file example for details.

Command Line

./dec_hevc_file --input <hevc file> --output <yuv file>

Examples

List options:

./bin/x64/dec_hevc_file --help

Usage: dec_hevc_file -i <hevc file> -o <yuv file>
  -h,    --help
         --input    HEVC input file.
         --output   YUV output file.

The following example decodes an HEVC input file into raw YUV output:

mkdir -p ./output/dec_hevc_file

./bin/x64/dec_hevc_file \
  --input ./assets/vid/input.hevc \
  --output ./output/dec_hevc_file/output.yuv