AVC / H.264 Annex B Decoder (Run)

This article explains how you can use TTranscoder::run to decode an AVC / H.264 Annex B elementary stream to a raw YUV video file.

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

Source Video

For source we use the foreman_qcif.h264 file from the AVBlocks Assets repository. After downloading and unzipping you will find foreman_qcif.h264 in the vid subdirectory.

Code

This code takes a compressed H.264 Annex B 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 TLibrary constructor initializes the library and loads the necessary codecs. The TLibrary destructor shuts the library down and releases any allocated memory, so the library is terminated when the TLibrary object goes out of scope at the end of main.

int main(int argc, char* argv[])
{
    Options opt;
    switch(prepareOptions(opt, argc, argv))
    {
        case Command: return 0;
        case Error:   return 1;
        case Parsed:  break;
    }

    TLibrary library;
    return decode(opt) ? 0 : 1;
}

Configure Input Socket

The input socket defines the source H.264 Annex B elementary stream. The socket is created from the input file only. AVBlocks reads the stream headers and automatically detects the video parameters, including resolution, frame rate, and codec settings, when the transcoder is opened.

TMediaSocket()
    .file(opt.inputFile)

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.

TMediaSocket()
    .file(opt.outputFile)
    .streamType(StreamType::UncompressedVideo)
    .addPin(
        TMediaPin()
            .streamInfo(TVideoStreamInfo()
                .streamType(StreamType::UncompressedVideo)
                .colorFormat(ColorFormat::YUV420)
            )
    )

Configure Transcoder and Decode

This is the main decoding function that ties everything together. The input and output sockets are created inline, as shown above. The transcoder is the core component that performs the actual decoding - it takes the compressed H.264 data from the input and converts it to uncompressed YUV data for the output.

The allowDemoMode(true) call allows the transcoder to work even without a valid license (useful for testing, but not recommended for production). We then 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. If any step fails, a TAVBlocksException is thrown. The catch blocks print the error and return false.

bool decode(const Options& opt)
{
    try {
        deleteFile(opt.outputFile.c_str());

        TTranscoder()
            .allowDemoMode(true)
            .addInput(
                TMediaSocket()
                    .file(opt.inputFile)
            )
            .addOutput(
                TMediaSocket()
                    .file(opt.outputFile)
                    .streamType(StreamType::UncompressedVideo)
                    .addPin(
                        TMediaPin()
                            .streamInfo(TVideoStreamInfo()
                                .streamType(StreamType::UncompressedVideo)
                                .colorFormat(ColorFormat::YUV420)
                            )
                    )
            )
            .open()
            .run()
            .close();

        std::println("Output: {}", opt.outputFile);
        return true;

    } catch (const TAVBlocksException& ex) {
        std::println(stderr, "AVBlocks error: {}", ex.what());
        return false;
    } catch (const std::exception& ex) {
        std::println(stderr, "Error: {}", ex.what());
        return false;
    }
}

Complete C++ Code

Here’s the complete working example that demonstrates H.264 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 <primo/avblocks/avb++.h>

#include <print>

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

using namespace primo::codecs;
using namespace primo::avblocks::modern;

bool decode(const Options& opt)
{
    try {
        deleteFile(opt.outputFile.c_str());

        TTranscoder()
            .allowDemoMode(true)
            .addInput(
                TMediaSocket()
                    .file(opt.inputFile)
            )
            .addOutput(
                TMediaSocket()
                    .file(opt.outputFile)
                    .streamType(StreamType::UncompressedVideo)
                    .addPin(
                        TMediaPin()
                            .streamInfo(TVideoStreamInfo()
                                .streamType(StreamType::UncompressedVideo)
                                .colorFormat(ColorFormat::YUV420)
                            )
                    )
            )
            .open()
            .run()
            .close();

        std::println("Output: {}", opt.outputFile);
        return true;

    } catch (const TAVBlocksException& ex) {
        std::println(stderr, "AVBlocks error: {}", ex.what());
        return false;
    } catch (const std::exception& ex) {
        std::println(stderr, "Error: {}", ex.what());
        return false;
    }
}

int main(int argc, char* argv[])
{
    Options opt;
    switch(prepareOptions(opt, argc, argv))
    {
        case Command: return 0;
        case Error:   return 1;
        case Parsed:  break;
    }

    TLibrary library;
    return decode(opt) ? 0 : 1;
}

How to Run

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

Command Line

./dec_avc_file --input <file.h264> --output <file.yuv>

Examples

List options:

./bin/x64/dec_avc_file --help
Usage: dec_avc_file -i <h264 file> -o <yuv file>
  -h,    --help
         --input    H264 input file.
         --output   YUV output file.

The following example decodes input file ./assets/vid/foreman_qcif.h264 into output file foreman_qcif.yuv:

mkdir -p ./output/dec_avc_file

./bin/x64/dec_avc_file \
    --input ./assets/vid/foreman_qcif.h264 \
    --output ./output/dec_avc_file/foreman_qcif.yuv