Vorbis Encoder (Run)

This article explains how you can use Transcoder.run to encode a WAV file to a Vorbis OGG file.

The code snippets in this article are from the enc_vorbis_file Python sample.

Linux and Windows samples are also available:

• enc_vorbis_file (Linux)

• enc_vorbis_file (Windows)

Source Audio

For source we use the equinox-48KHz.wav file from the AVBlocks Assets repository. After downloading and unzipping you will find equinox-48KHz.wav in the aud subdirectory.

Code

This code takes a WAV file and encodes it to Vorbis audio in an OGG container.

Initialize AVBlocks

The first step in any AVBlocks application is to initialize the library. This must be done before using any other AVBlocks functionality. Always call Library.shutdown() at the end of the program to clean up resources.

Library.initialize()

# Set license information. Without this AVBlocks runs in Demo mode.
# Library.set_license("<license-string>")

result = encode(input_file, output_file)

Library.shutdown()

sys.exit(0 if result else 2)

Configure Input Socket

The input socket points directly to the WAV input file.

# Create input socket
in_socket = MediaSocket()
in_socket.file = input_file

Configure Output Socket

The output socket writes an OGG container with a Vorbis audio stream.

def create_output_socket(output_file: str) -> MediaSocket:
    """Create output socket for Vorbis/OGG file."""
    # create stream info to describe the output audio stream
    asi = AudioStreamInfo()
    asi.stream_type = StreamType.Vorbis

    # The default bitrate is 128000. You can set it to 192000, 256000, etc.
    # asi.bitrate = 192000

    # Optionally set the sampling rate and the number of the channels, e.g. 44.1 Khz, Mono
    # asi.sample_rate = 44100
    # asi.channels = 1

    # create a pin using the stream info
    pin = MediaPin()
    pin.stream_info = asi

    # finally create a socket for the output container format which is OGG in this case
    socket = MediaSocket()
    socket.stream_type = StreamType.OGG
    socket.pins.add(pin)
    socket.file = output_file

    return socket

Configure and Run Transcoder

After creating the input and output sockets, the sample creates a transcoder, enables demo mode, adds the sockets, removes any existing output file, opens the transcoder, runs the encode, and closes it.

def encode(input_file: str, output_file: str) -> bool:
    """Encode WAV file to Vorbis/OGG."""
    # Transcoder will fail if output exists (by design)
    delete_file(output_file)

    # Create output directory if it doesn't exist
    output_dir = os.path.dirname(output_file)
    if output_dir and not os.path.exists(output_dir):
        os.makedirs(output_dir)

    # Create input socket
    in_socket = MediaSocket()
    in_socket.file = input_file

    # Create output socket
    out_socket = create_output_socket(output_file)

    # Create transcoder
    with Transcoder() as transcoder:
        transcoder.allow_demo_mode = True
        transcoder.inputs.add(in_socket)
        transcoder.outputs.add(out_socket)

        if not transcoder.open():
            print_error("Transcoder open", transcoder.error)
            return False

        if not transcoder.run():
            print_error("Transcoder run", transcoder.error)
            return False

        transcoder.close()

    return True

Complete Code

Here’s the complete working example that demonstrates Vorbis encoding using AVBlocks for Python.

"""
Encode WAV file to Vorbis/OGG.

This sample encodes a WAV audio file to Vorbis format in an OGG container using AVBlocks.
"""

import os
import sys
import click

from avblocks import (
    Library, Transcoder, MediaSocket, MediaPin,
    AudioStreamInfo, StreamType, ErrorFacility
)


def delete_file(filename: str):
    """Delete a file if it exists."""
    try:
        if os.path.exists(filename):
            os.remove(filename)
    except OSError:
        pass


def print_error(action: str, error) -> None:
    """Print error information."""
    if action:
        print(f"{action}: ", end="")

    if error.facility == ErrorFacility.Success:
        print("Success")
        return

    print(f"{error.message or ''}, facility:{error.facility} code:{error.code} hint:{error.hint or ''}")


def create_output_socket(output_file: str) -> MediaSocket:
    """Create output socket for Vorbis/OGG file."""
    # create stream info to describe the output audio stream
    asi = AudioStreamInfo()
    asi.stream_type = StreamType.Vorbis

    # The default bitrate is 128000. You can set it to 192000, 256000, etc.
    # asi.bitrate = 192000

    # Optionally set the sampling rate and the number of the channels, e.g. 44.1 Khz, Mono
    # asi.sample_rate = 44100
    # asi.channels = 1

    # create a pin using the stream info
    pin = MediaPin()
    pin.stream_info = asi

    # finally create a socket for the output container format which is OGG in this case
    socket = MediaSocket()
    socket.stream_type = StreamType.OGG
    socket.pins.add(pin)
    socket.file = output_file

    return socket


def encode(input_file: str, output_file: str) -> bool:
    """Encode WAV file to Vorbis/OGG."""
    # Transcoder will fail if output exists (by design)
    delete_file(output_file)

    # Create output directory if it doesn't exist
    output_dir = os.path.dirname(output_file)
    if output_dir and not os.path.exists(output_dir):
        os.makedirs(output_dir)

    # Create input socket
    in_socket = MediaSocket()
    in_socket.file = input_file

    # Create output socket
    out_socket = create_output_socket(output_file)

    # Create transcoder
    with Transcoder() as transcoder:
        transcoder.allow_demo_mode = True
        transcoder.inputs.add(in_socket)
        transcoder.outputs.add(out_socket)

        if not transcoder.open():
            print_error("Transcoder open", transcoder.error)
            return False

        if not transcoder.run():
            print_error("Transcoder run", transcoder.error)
            return False

        transcoder.close()

    return True


@click.command()
@click.option('-i', '--input', 'input_file',
              help='Input WAV file',
              type=click.Path(exists=True))
@click.option('-o', '--output', 'output_file',
              help='Output OGG file',
              type=click.Path())
def main(input_file: str, output_file: str):
    """Encode WAV file to Vorbis/OGG."""

    # Set default options if not provided
    if not input_file or not output_file:
        script_dir = os.path.dirname(os.path.abspath(__file__))

        if not input_file:
            input_file = os.path.join(script_dir, "../../assets/aud/equinox-48KHz.wav")
        if not output_file:
            output_file = os.path.join(script_dir, "../../output/enc_vorbis_file/equinox-48KHz.ogg")

        print("Using default options:")
        print(f"  --input {input_file}")
        print(f"  --output {output_file}")
        print()

    # Validate options
    print(f"Input file: {input_file}")
    print(f"Output file: {output_file}")

    Library.initialize()

    # Set license information. Without this AVBlocks runs in Demo mode.
    # Library.set_license("<license-string>")

    result = encode(input_file, output_file)

    Library.shutdown()

    sys.exit(0 if result else 2)


if __name__ == '__main__':
    main()

How to Run

See the Python sample for details. The samples are installed as command-line tools when you install the package from the repository root with uv pip install --editable . (see Installation).

Command Line

enc-vorbis-file --input <wav file> --output <ogg file>

Examples

List options:

enc-vorbis-file --help
Usage: enc-vorbis-file [OPTIONS]

  Encode WAV file to Vorbis/OGG.

Options:
  -i, --input PATH   Input WAV file
  -o, --output PATH  Output OGG file
  --help             Show this message and exit.

Encode the input file ./assets/aud/equinox-48KHz.wav into output file ./output/enc_vorbis_file/equinox-48KHz.ogg:

# Linux and macOS
mkdir -p ./output/enc_vorbis_file

enc-vorbis-file \
    --input ./assets/aud/equinox-48KHz.wav \
    --output ./output/enc_vorbis_file/equinox-48KHz.ogg

# Windows
New-Item -ItemType Directory -Force -Path ./output/enc_vorbis_file

enc-vorbis-file `
    --input ./assets/aud/equinox-48KHz.wav `
    --output ./output/enc_vorbis_file/equinox-48KHz.ogg