Skip to content

Commit

Permalink
README: Add a summary of the encoding workflows available.
Browse files Browse the repository at this point in the history
- Refactor "What is iamf-tools" to include decoding and web demo as separate subsections.
- Clarify that the textproto serves as a config file for iamf-tools encoder.

PiperOrigin-RevId: 686551004
  • Loading branch information
felicialim committed Oct 16, 2024
1 parent 6ba1201 commit 52aba1a
Show file tree
Hide file tree
Showing 2 changed files with 44 additions and 12 deletions.
52 changes: 40 additions & 12 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,18 +9,52 @@ The [Immersive Audio Model and Formats](https://aomediacodec.github.io/iamf/)

`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](https://github.com/AOMediaCodec/libiamf/).
[reference decoder](https://github.com/AOMediaCodec/libiamf/) and other tools
such as [ffmpeg](https://ffmpeg.org/).

### Encoder

### Encoding IAMF files

There are multiple workflows for creating IAMF files, supporting different types
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)

### Decoding IAMF files

The `libiamf` reference decoder is available at
https://github.com/AOMediaCodec/libiamf/.

### 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
based on an ADM-BWF file or an input protocol buffer.
from a set of multichannel wav files or an ADM-BWF file.

#### Building the encoder
### Building the encoder

See [Build instructions](docs/build_instructions.md) to build from source.

#### Using the encoder with proto input
### Using the encoder with wav files and proto input

The `iamf-tools` encoder can be used to encode a set of multichannel wav files
into an IAMF file. An accompanying input textproto file serves as the
configuration file, specifying details such as channel layout, mix gains and
codec to use for the underlying audio elements.

Prepare up to two multichannel wav files and the input textproto file. See
[Textproto templates](iamf/cli/textproto_templates) for some example input
Expand All @@ -43,7 +77,7 @@ bazel-bin/iamf/cli/encoder_main --user_metadata_filename=iamf/cli/testdata/test_
If this example is successful the encoder will produce an output
`test_000002.iamf` file in the current directory.

#### Using the encoder with ADM-BWF input
### Using the encoder with ADM-BWF input

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
Expand All @@ -64,12 +98,6 @@ bazel-bin/iamf/cli/encoder_main --adm_filename=path/to/adm.wav --output_iamf_dir
The encoder will produce an output `.iamf` file in the output directory, where
the underlying audio streams are encoded with PCM.

## 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.

## License

Released under the BSD 3-Clause Clear License. See [LICENSE](LICENSE) for
Expand Down
Loading

0 comments on commit 52aba1a

Please sign in to comment.