Opus Decoder (Run)

This article explains how you can use TTranscoder::run to decode an Opus audio file (in OGG container) to uncompressed PCM WAV.

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

Source Audio

For source we use the Everybody-TBB.opus file from the AVBlocks Assets repository. After downloading and unzipping you will find Everybody-TBB.opus in the aud subdirectory.

Code

This code takes an Opus file and decodes it to uncompressed LPCM WAV file.

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 Output Socket

The output socket defines where and how the decoded audio data will be written. In this case, we’re configuring it to output a WAV file with LPCM (Linear Pulse Code Modulation) format. The socket represents the output destination, while the pin represents the specific audio stream within that destination. The TAudioStreamInfo object specifies the audio format parameters - you can customize the number of channels or sampling rate with its channels and sampleRate methods.

// Create output socket with WAV format and LPCM audio
TMediaSocket outputSocket = TMediaSocket()
    .file(opt.outputFile)
    .streamType(StreamType::WAVE)
    .addPin(TMediaPin()
        .streamInfo(TAudioStreamInfo()
            .streamType(StreamType::LPCM)));

Configure Transcoder and Decode

This is the main decoding function that ties everything together. First, we create an input socket that points to the Opus file we want to decode. Then we create the output socket. The transcoder is the core component that performs the actual decoding - it takes the compressed Opus data from the input and converts it to uncompressed LPCM 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.

bool decode(const Options& opt)
{
    try {
        // Delete output file if it exists
        deleteFile(opt.outputFile.c_str());

        // Create input socket from file.
        TMediaSocket inputSocket = TMediaSocket().file(opt.inputFile);

        // Create output socket with WAV format and LPCM audio
        TMediaSocket outputSocket = TMediaSocket()
            .file(opt.outputFile)
            .streamType(StreamType::WAVE)
            .addPin(TMediaPin()
                .streamInfo(TAudioStreamInfo()
                    .streamType(StreamType::LPCM)));

        // Create and run transcoder
        TTranscoder()
            .allowDemoMode(true)
            .addInput(inputSocket)
            .addOutput(outputSocket)
            .open()
            .run()
            .close();

        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 Opus 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 {
        // Delete output file if it exists
        deleteFile(opt.outputFile.c_str());

        // Create input socket from file.
        TMediaSocket inputSocket = TMediaSocket().file(opt.inputFile);

        // Create output socket with WAV format and LPCM audio
        TMediaSocket outputSocket = TMediaSocket()
            .file(opt.outputFile)
            .streamType(StreamType::WAVE)
            .addPin(TMediaPin()
                .streamInfo(TAudioStreamInfo()
                    .streamType(StreamType::LPCM)));

        // Create and run transcoder
        TTranscoder()
            .allowDemoMode(true)
            .addInput(inputSocket)
            .addOutput(outputSocket)
            .open()
            .run()
            .close();

        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_opus_file example for details.

Command Line

./dec_opus_file --input <opus file> --output <wav file>

Examples

List options:

./bin/x64/dec_opus_file --help

dec_opus_file --input <opus file> --output <wav file>
  -h,    --help
  -i,    --input    input Opus file
  -o,    --output   output WAV file

The following example decodes input file ./assets/aud/Everybody-TBB.opus into output file Everybody-TBB.wav:

mkdir -p ./output/dec_opus_file

./bin/x64/dec_opus_file \
  --input ./assets/aud/Everybody-TBB.opus \
  --output ./output/dec_opus_file/Everybody-TBB.wav