|
Name |
|
Date |
Size |
#Lines |
LOC |
| .. | | - | - |
| adm/ | | 04-Jul-2025 | - | 3,325 | 2,439 |
| app/ | | 04-Jul-2025 | - | 506 | 366 |
| iamf/ | | 04-Jul-2025 | - | 2,214 | 1,568 |
| README.md | D | 04-Jul-2025 | 4.3 KiB | 111 | 84 |
README.md
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