Warn that some ADM conversions are experimental, and update stale REA…

…DME.

  - b/394088855: Pass over stale `README.md` and warn about b/392958726.
  - Reword rationale:
    - Reword ADM to IAMF conversion section. The tool doesn't "convert to IAMF"; protos and wav files are an `iamf-tools` interface, but not really IAMF.
    - Add a note that this is accessible at the top-level encoder. Unless a user cares about the intermediate output, they rarely will need `adm_to_user_metadata_main`.
    - b/392958726: Add a warning that some encoding are experimental.
    - Update example build command to work from any directory.
    - Update stale prerequisites.
    - Add a bit more detail about about which types of audio elements go through which paths.

PiperOrigin-RevId: 726144292

README.md

@@ -12,7 +12,6 @@ format. These tools can be used as a complement to the `libiamf`
 [reference decoder](https://github.com/AOMediaCodec/libiamf/) and other tools
 such as [ffmpeg](https://ffmpeg.org/).
 
-
 ### Encoding IAMF files
 
 There are multiple workflows for creating IAMF files, supporting different types
@@ -21,29 +20,25 @@ of inputs.
 ![IAMF encode workflows](docs/iamf-encode-workflows.svg "IAMF encode workflows")
 
 -   [Encode an ADM-BWF file to IAMF](#using-the-encoder-with-adm-bwf-input)
--   [Encode wav files to IAMF using the iamf-tools
-    encoder](#using-the-encoder-with-wav-files-and-proto-input)
--   [Encode wav files to IAMF using
-    ffmpeg](docs/external/encoding_with_external_tools.md#encode-wav-files-to-iamf-with-ffmpeg)
--   [Merge IAMF files and video into an mp4
-    file](docs/external/encoding_with_external_tools.md#merge-an-iamf-file-with-video-into-mp4-using-ffmpeg)
+-   [Encode wav files to IAMF using the iamf-tools encoder](#using-the-encoder-with-wav-files-and-proto-input)
+-   [Encode wav files to IAMF using ffmpeg](docs/external/encoding_with_external_tools.md#encode-wav-files-to-iamf-with-ffmpeg)
+-   [Merge IAMF files and video into an mp4 file](docs/external/encoding_with_external_tools.md#merge-an-iamf-file-with-video-into-mp4-using-ffmpeg)
 
 ### Decoding IAMF files
 
 The `libiamf` reference decoder is available at
 https://github.com/AOMediaCodec/libiamf/.
 
-###  Web Demo
+### Web Demo
 
 The [web demo](https://aomediacodec.github.io/iamf-tools/web_demo/) hosted in
 the GitHub Pages of this repo decodes and renders standalone IAMF files to
 stereo and binaural wav files for preview and comparison.
 
-
 ## Encoder
 
-The encoder can be used to encode a standalone IAMF Sequence (`.iamf`) file
-from a set of multichannel wav files or an ADM-BWF file.
+The encoder can be used to encode a standalone IAMF Sequence (`.iamf`) file from
+a set of multichannel wav files or an ADM-BWF file.
 
 ### Building the encoder
 
@@ -83,6 +78,11 @@ Run the encoder. Specify the input file with `--adm_filename`. See the
 `adm_to_user_metadata` [README.md](iamf/cli/adm_to_user_metadata) for details on
 the conversion.
 
+> [!WARNING]
+>
+> Some ADM conversions are a work in progress and are experimental
+> (b/392958726).
+
 Optional flags:
 
 -   `--output_iamf_directory` controls the output directory of the IAMF files.

iamf/cli/adm_to_user_metadata/README.md

@@ -11,13 +11,17 @@
 
 # ADM to IAMF Conversion Tool
 
-This is a C++ implementation of the tool to convert an ADM-BWF file (conformant
-to
-[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))
-to Immersive Audio Model and Formats (IAMF) textproto file and the associated
-set of wav file(s) to be used as inputs for an IAMF encoder. The tool does not
-handle the ADM-BWF files with <metadata/features> not supported by the IAMF
-specification [v1.0.0-errata](https://aomediacodec.github.io/iamf/v1.0.0-errata.html).
+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](https://www.itu.int/dms_pubrec/itu-r/rec/bs/R-REC-BS.2076-2-201910-I!!PDF-E.pdf)).
+
+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](../../../README.md##using-the-encoder-with-adm-bwf-input).
 
 ## Folder Structure
 
@@ -35,19 +39,27 @@ The description of each directory is as follows:
 
 ### Prerequisites
 
-1.  [Git](https://git-scm.com/).
-2.  [Bazel](https://bazel.build/start).
+See [docs/build_instructions.md](../../../docs/build_instructions.md) for
+further details.
+
+-   Bazelisk: `iamf-tools` uses the Bazel build system, via bazelisk. See
+    [Bazelisk installation instructions](https://bazel.build/install/bazelisk).
+    For further information on Bazel, see
+    [Getting started](https://bazel.build/start).
+-   CMake: required to build some dependencies. See CMake's
+    [Download](https://cmake.org/download/) page to install.
+-   Clang 13+ or GCC 10+ for Linux-like systems or MSVC for Windows.
 
 ### Build the binary
 
 ```
-bazelisk build -c opt app:adm_to_user_metadata_main
+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:
+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>
@@ -73,12 +85,25 @@ options:
 -   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: audio elements are created based on ADM `audioObjects`.
-    Low importance objects are filtered out based on the
-    `--importance_threshold` 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
     `audioProgramme`s.
 
+> [!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](LICENSE) for