1# README.md 2 3## Contents 4 51. [ADM to IAMF Conversion Tool](#ADM-to-IAMF-Conversion-Tool) 62. [Building the library](#ADM-Building-the-LibraryTool) 7 - [Prerequisites](#Prerequisites) 8 - [Build the binary](#Build-the-binary) 9 - [Run the binary](#Run-the-binary) 103. [License](#License) 11 12# ADM to IAMF Conversion Tool 13 14This is a C++ implementation of a tool to extract metadata and audio from an 15ADM-BWF file (conformant to 16[Recommendation ITU-R BS.2076-2](https://www.itu.int/dms_pubrec/itu-r/rec/bs/R-REC-BS.2076-2-201910-I!!PDF-E.pdf)). 17 18Information is extracted and written to a `UserMetadata` proto file and a set of 19wav file(s). These files can be consumed by the `iamf-tools` encoder to produce 20an Immersive Audio Model and Formats (IAMF) file. 21 22Most users do not need to use this tool directly. ADM conversion is available 23through various command line flags in 24[encoder_main](../../../README.md##using-the-encoder-with-adm-bwf-input). 25 26## Folder Structure 27 28The description of each directory is as follows: 29 30* `adm` - Components related to parsing an ADM-BWF file. 31 * `tests` - Tests for files under `adm`. 32* `app` - An example application which uses the conversion tool. 33 * `tests` - Tests for files under `app`. 34* `iamf` - Components related to transforming ADM into user metadata suitable 35 for the `iamf-tools` encoder. 36 * `tests` - Tests for files under `iamf`. 37 38## Building the library 39 40### Prerequisites 41 42See [docs/build_instructions.md](../../../docs/build_instructions.md) for 43further details. 44 45- Bazelisk: `iamf-tools` uses the Bazel build system, via bazelisk. See 46 [Bazelisk installation instructions](https://bazel.build/install/bazelisk). 47 For further information on Bazel, see 48 [Getting started](https://bazel.build/start). 49- CMake: required to build some dependencies. See CMake's 50 [Download](https://cmake.org/download/) page to install. 51- Clang 13+ or GCC 10+ for Linux-like systems or MSVC for Windows. 52 53### Build the binary 54 55``` 56bazelisk build -c opt //iamf/cli/adm_to_user_metadata/app:adm_to_user_metadata_main 57``` 58 59### Run the binary 60 61Running `bazelisk build` creates the binary file `adm_to_user_metadata_main`. 62The input format required to run the binary is as below: 63 64``` 65 ./adm_to_user_metadata_main <options> 66 67options: 68 --adm_filename (required) - ADM wav file to process. 69 --importance_threshold (optional) - Used to reject objects whose importance is below the given threshold of range 0 to 10 (default 0). 70 --frame_duration_ms (optional) - Target frame duration in ms. The actual output may be slightly lower due to rounding. (default 10). 71 --write_binary_proto (optional) - Whether to write the output as a binary proto or a textproto (default true) 72 --output_file_path (optional) - Path to write output files to. (default current directory) 73 74 75 Example: 76 - ./adm_to_user_metadata_main --adm_filename input.wav 77 - ./adm_to_user_metadata_main --write_binary_proto=false --adm_filename input.wav 78 - ./adm_to_user_metadata_main --frame_duration_ms=20 --adm_filename input.wav 79 - ./adm_to_user_metadata_main --importance_threshold=4 --adm_filename input.wav 80``` 81 82### Conversion details 83 84- IA Sequence Header OBU: a base profile sequence header is always generated. 85- Codec Config OBU: an LPCM codec config is created with sample rate and 86 bit-depth determined based on the input file. `number_of_samples_per_frame` 87 is determined based on the `--frame_duration_ms` flag. 88- Audio Element OBUs: 89 - When audio elements are a type directly representable in IAMF, they are 90 created based on ADM `audioObjects`. 91 - When audio elements aren't directly representable in IAMF, they may be 92 folded to third-order ambisonics. See the "Warning" at the end of this 93 section. 94 - Some types directly representable in IAMF include {stereo, 5.1, 7.1.4, 95 third_order_ambisonics}. One type that is not representable directly in 96 IAMF includes objects. 97 - Low importance objects are filtered out based on the 98 `--importance_threshold` flag. 99- Mix Presentation OBUs: mix presentations are generated based on ADM 100 `audioProgramme`s. 101 102> [!WARNING] 103> 104> Some ADM conversions are a work in progress and are experimental 105> (b/392958726). 106 107## License 108 109Released under the BSD 3-Clause Clear License. See [LICENSE](LICENSE) for 110details. 111