README.md

Contents

1. ADM to IAMF Conversion Tool
2. Building the library
   • Prerequisites
   • Build the binary
   • Run the binary
3. License

ADM to IAMF Conversion Tool

This is a C++ implementation of a tool to extract metadata and audio from an ADM-BWF file (conformant to Recommendation ITU-R BS.2076-2).

Information is extracted and written to a UserMetadata proto file and a set of wav file(s). These files can be consumed by the iamf-tools encoder to produce an Immersive Audio Model and Formats (IAMF) file.

Most users do not need to use this tool directly. ADM conversion is available through various command line flags in encoder_main.

Folder Structure

The description of each directory is as follows:

• adm - Components related to parsing an ADM-BWF file.
  • tests - Tests for files under adm.
• app - An example application which uses the conversion tool.
  • tests - Tests for files under app.
• iamf - Components related to transforming ADM into user metadata suitable for the iamf-tools encoder.
  • tests - Tests for files under iamf.

Building the library

Prerequisites

See docs/build_instructions.md for further details.

• Bazelisk: iamf-tools uses the Bazel build system, via bazelisk. See Bazelisk installation instructions. For further information on Bazel, see Getting started.
• CMake: required to build some dependencies. See CMake's Download page to install.
• Clang 13+ or GCC 10+ for Linux-like systems or MSVC for Windows.

Build the binary

bazelisk build -c opt //iamf/cli/adm_to_user_metadata/app:adm_to_user_metadata_main

Run the binary

Running bazelisk build creates the binary file adm_to_user_metadata_main. The input format required to run the binary is as below:

 ./adm_to_user_metadata_main <options>

options:
  --adm_filename (required) - ADM wav file to process.
  --importance_threshold (optional) - Used to reject objects whose importance is below the given threshold of range 0 to 10 (default 0).
  --frame_duration_ms (optional) - Target frame duration in ms. The actual output may be slightly lower due to rounding. (default 10).
  --write_binary_proto (optional) - Whether to write the output as a binary proto or a textproto (default true)
  --output_file_path (optional) - Path to write output files to. (default current directory)


  Example:
    - ./adm_to_user_metadata_main --adm_filename input.wav
    - ./adm_to_user_metadata_main --write_binary_proto=false --adm_filename input.wav
    - ./adm_to_user_metadata_main --frame_duration_ms=20 --adm_filename input.wav
    - ./adm_to_user_metadata_main --importance_threshold=4 --adm_filename input.wav

Conversion details

• IA Sequence Header OBU: a base profile sequence header is always generated.
• Codec Config OBU: an LPCM codec config is created with sample rate and bit-depth determined based on the input file. number_of_samples_per_frame is determined based on the --frame_duration_ms flag.
• Audio Element OBUs:
  • When audio elements are a type directly representable in IAMF, they are created based on ADM audioObjects.
  • When audio elements aren't directly representable in IAMF, they may be folded to third-order ambisonics. See the “Warning” at the end of this section.
  • Some types directly representable in IAMF include {stereo, 5.1, 7.1.4, third_order_ambisonics}. One type that is not representable directly in IAMF includes objects.
  • Low importance objects are filtered out based on the --importance_threshold flag.
• Mix Presentation OBUs: mix presentations are generated based on ADM audioProgrammes.

[!WARNING]

Some ADM conversions are a work in progress and are experimental (b/392958726).

License

Released under the BSD 3-Clause Clear License. See LICENSE for details.