README.md
1# Textproto templates
2
3The textproto templates correspond to the following audio layouts.
4
5| Input layout | Codec | File name |
6| ----------------------------- | ----- | --------------------------------- |
7| Stereo | PCM | stereo_pcm24bit.textproto |
8| Stereo | Opus | stereo_opus.textproto |
9| 5.1 | PCM | 5dot1_pcm24bit.textproto |
10| 5.1 | Opus | 5dot1_opus.textproto |
11| 5.1.2 | PCM | 5dot1dot2_pcm24bit.textproto |
12| 5.1.2 | Opus | 5dot1dot2_opus.textproto |
13| 7.1.4 | PCM | 7dot1dot4_pcm24bit.textproto |
14| 7.1.4 | Opus | 7dot1dot4_opus.textproto |
15| 1st order Ambisonics | PCM | 1OA_pcm24bit.textproto |
16| 1st order Ambisonics | Opus | 1OA_opus.textproto |
17| 3rd order Ambisonics | PCM | 3OA_pcm24bit.textproto |
18| 3rd order Ambisonics | Opus | 3OA_opus.textproto |
19| 1st order Ambisonics + Stereo | PCM | 1OA_and_stereo_pcm24bit.textproto |
20| 1st order Ambisonics + Stereo | Opus | 1OA_and_stereo_opus.textproto |
21| 3rd order Ambisonics + Stereo | PCM | 3OA_and_stereo_pcm24bit.textproto |
22| 3rd order Ambisonics + Stereo | Opus | 3OA_and_stereo_opus.textproto |
23
24## Customizing the templates
25
26Set the following fields in the textproto template.
27
28- `wav_filename`
29
30 Set this to the input wav filename, without the path to it. For example, if
31 the wav file is located at `/path/to/input.wav`, set
32
33 ```
34 wav_filename: input.wav
35 ```
36
37- `file_name_prefix`
38
39 Set this to the desired output filename. The generated .iamf file will be
40 named `file_name_prefix.iamf`.
41
42- `loudness`
43
44 Measure the loudness of the input audio, including the stereo downmix, and
45 store these values in the following loudness fields. IAMF decoders and
46 renderers can use this loudness metadata to normalize the output audio.
47
48 - `loudness.integrated_loudness`
49
50 This is the [ITU-R BS.1770-4](https://www.itu.int/rec/R-REC-BS.1770)
51 integrated loudness, specified in LKFS. Convert the loudness value to
52 the correct `int16` value to use here as `integrated_loudness =
53 integrated_loudness_in_lkfs * 256`.
54
55 - `loudness.digital_peak`
56
57 This is the digital (sampled) peak value of the audio signal, specified
58 in dBFS. Convert the peak value to the correct `int16` value to use here
59 as `digital_peak = digital_peak_in_dBFS * 256`.
60
61Optionally, modify other fields in the textproto template as necessary.
62
63- `channel_metadatas`
64
65 Use custom `channel_ids` when the input wav file is in a different order. By
66 default they are configured for wav files using
67 [ITU-2051-3](https://www.itu.int/rec/R-REC-BS.2051) order.
68
69- `headphones_rendering_mode`
70
71 Choose one of `HEADPHONES_RENDERING_MODE_BINAURAL` or `HEADPHONES_RENDERING_MODE_STEREO`.
72
73 This informs the renderer if the audio element should be binauralized or downmixed to stereo.
74
75- `element_mix_gain.default_mix_gain`
76
77 This is the gain that will be applied to an audio element before it is summed with all other audio elements.
78
79 It is denoted in dB and Q7.8 format, and then converted to `int16`. Convert a desired gain to the correct `int16` value to use here as `default_mix_gain = gain_in_db * 256`.
80
81- `output_mix_gain.default_mix_gain`
82
83 This is the gain that will be applied to the summed audio elements.
84
85 It is denoted in dB and Q7.8 format, and then converted to `int16`. Convert a desired gain to the correct `int16` value to use here as `default_mix_gain = gain_in_db * 256`.
86
87
88The following are available for PCM textprotos only.
89
90- `decoder_config_lpcm.sample_size`
91
92 Input PCM bit-depth. Allowed values are 16, 24, 32.
93
94- `decoder_config_lpcm.sample_rate`
95
96 Input and output sample rate. Allowed values are 16000, 32000, 44100, 48000, 96000.
97
98 All `parameter_rate` values must additionally be updated to match `sample_rate`.
99
100
101The following are available for Opus textprotos only.
102
103- `opus_encoder_metadata.target_bitrate_per_channel`
104
105 Target bitrate per channel, in bits per second.
106
107- `opus_encoder_metadata.coupling_rate_adjustment`
108
109 Some channels are coupled and coded as stereo pairs, e.g., L/R. This field adjusts the total target bitrate of the coupled channels to be `target_bitrate_per_channel * 2 * coupling_rate_adjustment`. Its default value is 1.0.
110