AAC ADTS Decoder (Run)

This article explains how you can use Transcoder.run to decode an AAC (Advanced Audio Coding) ADTS (Audio Data Transport Stream) elementary stream.

The code snippets in this article are from the dec_aac_adts_file sample.

Source Audio

For source we use the Hydrate-Kenny_Beltrey.adts.aac file from the AVBlocks Assets repository. After downloading and unzipping you will find Hydrate-Kenny_Beltrey.adts.aac in the aud subdirectory.

Code

This code takes an AAC ADTS 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 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.

Library.initialize()

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

result = decode(input_file, output_file)

Library.shutdown()

sys.exit(0 if result else 2)

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 AudioStreamInfo object specifies the audio format parameters - you can customize the number of channels or sampling rate by uncommenting the relevant lines.

def create_output_socket(output_file: str) -> MediaSocket:
    """Create output socket for WAV file."""
    socket = MediaSocket()
    socket.file = output_file
    socket.stream_type = StreamType.WAVE

    pin = MediaPin()
    socket.pins.add(pin)

    asi = AudioStreamInfo()
    pin.stream_info = asi

    asi.stream_type = StreamType.LPCM

    # You can change the number of channels
    # asi.channels = 1
    # or the sampling rate
    # asi.sample_rate = 44100

    return socket

Configure Transcoder and Decode

This is the main decoding function that ties everything together. First, we create a MediaInfo object and open it against the AAC ADTS file to detect the input stream format, then build the matching input socket with MediaSocket.from_media_info. Then we create the output socket using our helper method. The transcoder is the core component that performs the actual decoding - it takes the compressed AAC data from the input and converts it to uncompressed LPCM data for the output.

The allow_demo_mode = True setting 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.

def decode(input_file: str, output_file: str) -> bool:
    """Decode AAC ADTS file to WAV."""
    # 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)

    # Open input file with MediaInfo
    media_info = MediaInfo()
    media_info.inputs[0].file = input_file

    if not media_info.open():
        print_error("MediaInfo.open()", media_info.error)
        return False

    in_socket = MediaSocket.from_media_info(media_info)
    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)

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

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

        transcoder.close()
        print_error("Transcoder close", transcoder.error)

    return True

Complete Python Code

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

"""
Decode AAC ADTS file to WAV.

This sample decodes an AAC ADTS audio file to a WAV file using AVBlocks.
"""

import os
import sys
import click

from avblocks import (
    Library, Transcoder, MediaInfo, 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 WAV file."""
    socket = MediaSocket()
    socket.file = output_file
    socket.stream_type = StreamType.WAVE

    pin = MediaPin()
    socket.pins.add(pin)

    asi = AudioStreamInfo()
    pin.stream_info = asi

    asi.stream_type = StreamType.LPCM

    # You can change the number of channels
    # asi.channels = 1
    # or the sampling rate
    # asi.sample_rate = 44100

    return socket


def decode(input_file: str, output_file: str) -> bool:
    """Decode AAC ADTS file to WAV."""
    # 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)

    # Open input file with MediaInfo
    media_info = MediaInfo()
    media_info.inputs[0].file = input_file

    if not media_info.open():
        print_error("MediaInfo.open()", media_info.error)
        return False

    in_socket = MediaSocket.from_media_info(media_info)
    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)

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

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

        transcoder.close()
        print_error("Transcoder close", transcoder.error)

    return True


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

    # 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/Hydrate-Kenny_Beltrey.adts.aac")
        if not output_file:
            output_file = os.path.join(script_dir, "../../output/dec_aac_adts_file/Hydrate-Kenny_Beltrey.wav")

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

    # Validate options
    print(f"--input: {input_file}")
    print(f"--output: {output_file}")

    Library.initialize()

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

    result = decode(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

dec-aac-adts-file --input <aac file> --output <wav file>

Examples

List options:

dec-aac-adts-file --help
Usage: dec-aac-adts-file [OPTIONS]

  Decode AAC ADTS file to WAV.

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

Decode the input file ./assets/aud/Hydrate-Kenny_Beltrey.adts.aac into output file ./output/dec_aac_adts_file/Hydrate-Kenny_Beltrey.wav:

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

dec-aac-adts-file \
    --input ./assets/aud/Hydrate-Kenny_Beltrey.adts.aac \
    --output ./output/dec_aac_adts_file/Hydrate-Kenny_Beltrey.wav

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

dec-aac-adts-file `
    --input ./assets/aud/Hydrate-Kenny_Beltrey.adts.aac `
    --output ./output/dec_aac_adts_file/Hydrate-Kenny_Beltrey.wav