aomediacodec / iamf-tools

Tools to work with IAMF

iamf-tools

What is IAMF?

The Immersive Audio Model and Formats (IAMF) standard is defined by the Alliance for Open Media (AOM).

What is iamf-tools?

iamf-tools implements tools to help users process and work with the IAMF format. These tools can be used as a complement to the libiamf reference decoder.

Folder Structure

• <root> - Project-level files like the license, README (this file), and BUILD files.
• iamf/
  • common/ - Common utility files.
    • tests/ - Unit tests for files under common/.
  • cli/ - Files related to the command line interface (CLI) to generate and write an IA Sequence.
    • adm_to_user_metadata/ - Components to convert ADM files to proto files which can be used for input to the encoder.
    • codec/ - Files that encode or decode substreams with codec-specific libraries.
      • tests/ - Unit tests for files under codec/.
    • proto/ - Protocol buffers defining the data scheme for the input files under iamf/cli/testdata/ or user-created ones.
    • testdata/ - Sample input files to the encoder. See also Test Suite.
    • tests/ - Unit tests for files under iamf/cli/.
  • obu/ - Files relating to IAMF Open Bitstream Units (OBU)s.
    • decoder_config/ - Files relating codec-specific decoder configs.
      • tests/ - Unit tests for files under decoder_config/.
    • tests/ - Unit tests for files under obu/.
• external/ - Custom *.BUILD files for external dependencies.

Encoder

The encoder can be used to encode a standalone IAMF Sequence (.iamf) file based on an input proto file. See Test Suite for several example input files.

Prerequisites for building the encoder

• Bazel: iamf-tools uses the Bazel build system. See Bazel's Getting started page for installation instructions.
• CMake: required to build some dependencies. See CMake's Download page to install.

Building the encoder on Linux

Building the encoder binary:

bazel build -c opt //iamf/cli:encoder_main

Running built-in tests:

bazel test -c opt //iamf/...

Using the encoder with proto input

Run the encoder. Specify the input file with --user_metadata_filename.

Optional flags:

• --input_wav_directory controls the directory wav files are read from (default iamf/cli/testdata/).
• --output_iamf_directory controls the output directory of the IAMF files.
• --output_wav_directory controls the output directory of wav files.

Using the encoder:

bazel-bin/iamf/cli/encoder_main --user_metadata_filename=iamf/cli/testdata/test_000002.textproto --output_iamf_directory=.

If this example is successful the encoder will produce an output test_000002.iamf file in the current directory.

Using the encoder with ADM input

Run the encoder. Specify the input file with --adm_filename. See the adm_to_user_metadata README.md for details on the conversion.

Optional flags:

• --output_iamf_directory controls the output directory of the IAMF files.
• --output_wav_directory controls the output directory of wav files.
• --adm_importance_threshold controls the threshold below which ADM audioObjects are omitted (default 0).
• --adm_frame_duration_ms controls the frame size of the output IAMF in ms (default 10).

bazel-bin/iamf/cli/encoder_main --adm_filename=path/to/adm.wav --output_iamf_directory=.

Test suite

iamf/cli/testdata covers a wide variety of IAMF features. These samples can be used as encoder input. After encoding the resultant .iamf files can be used to assist in testing or debugging an IAMF-compliant decoder.

See the separate README.md for further documentation.

License

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

iamf-tools's Issues

Document additional prerequisites

iamf-tools uses c++ 20, and currently requires gcc 10+. On ubuntu, this requires focal (22.02) at a minimum.

Remove dependency on `libexpat1-dev`

Users may see errors about expat_config.h when trying to build. It would simplify the build process if this file was generated when building expat.

As a workaround in the meantime users should try installing libexpat1-dev to provide expat_config.h and then try the normal build process again.

Generate list of test report

It would be good to generate an HTML report listing all the tests (filename, human description, is valid or not...) maybe in the form of a table. That report could be generated automatically whenever a PR is merged and published on GitHub pages. That would offer a synthesis of what is tested.

Support native Windows build

Currently this project may not build on Windows/MSVC.

One issue was brought up in #5; it seems like bazelrc does not configure compiler flags in a portable way.

There may be more issues beyond that though.

Support Native MacOS Build

Currently this project may not build on MacOs / ARM.

Looks like the cause is missing ARM header files and missing include directories on some of the dependencies in Bazel. Updated the build script accordingly.

Opened a PR to fix here: #7

Let me know if you need anything else to review / merge.

Can't build the project with bazel

I keep getting errors about invalid numeric arguments in Windows:

PS D:\Code\IAMF\iamf-tools> bazel build -c opt //iamf/cli:encoder_main
INFO: Analyzed target //iamf/cli:encoder_main (1 packages loaded, 514 targets configured).
ERROR: C:/users/pc/_bazel_pc/t63pxre5/external/com_google_absl/absl/base/BUILD.bazel:60:11: Compiling absl/base/log_severity.cc failed: (Exit 2): cl.exe failed: error executing CppCompile command (from target @@com_google_absl//absl/base:log_severity) C:\Program Files (x86)\Microsoft Visual Studio\2022\BuildTools\VC\Tools\MSVC\14.39.33519\bin\HostX64\x64\cl.exe ... (remaining 1 argument skipped)
cl : Command line error D8021 : invalid numeric argument '/Wno-sign-compare'
Target //iamf/cli:encoder_main failed to build
Use --verbose_failures to see the command lines of failed build steps.