iamf/cli/proto/audio_frame.proto - platform/external/iamf_tools - Git at Google

 // Copyright (c) 2023, Alliance for Open Media. All rights reserved
 //
 // This source code is subject to the terms of the BSD 3-Clause Clear License
 // and the Alliance for Open Media Patent License 1.0. If the BSD 3-Clause Clear
 // License was not distributed with this source code in the LICENSE file, you
 // can obtain it at www.aomedia.org/license/software-license/bsd-3-c-c. If the
 // Alliance for Open Media Patent License 1.0 was not distributed with this
 // source code in the PATENTS file, you can obtain it at
 // www.aomedia.org/license/patent.

 syntax = "proto2";

 package iamf_tools_cli_proto;

 enum ChannelLabel {
   CHANNEL_LABEL_INVALID = 0;
   reserved 1;  // Reserved for potential "omitted" label.
   // Mono channels.
   CHANNEL_LABEL_MONO = 2;
   // Stereo or binaural channels.
   CHANNEL_LABEL_L_2 = 3;
   CHANNEL_LABEL_R_2 = 4;
   // Centre channel common to several layouts (e.g. 3.1.2, 5.x.y, 7.x.y).
   CHANNEL_LABEL_CENTRE = 6;
   // LFE channel common to several layouts (e.g. 3.1.2, 5.1.y, 7.1.y, 9.1.6).
   CHANNEL_LABEL_LFE = 7;
   // 3.1.2 surround channels.
   CHANNEL_LABEL_L_3 = 8;
   CHANNEL_LABEL_R_3 = 9;
   CHANNEL_LABEL_LTF_3 = 10;
   CHANNEL_LABEL_RTF_3 = 11;
   // 5.x.y surround channels.
   CHANNEL_LABEL_L_5 = 14;
   CHANNEL_LABEL_R_5 = 15;
   CHANNEL_LABEL_LS_5 = 16;
   CHANNEL_LABEL_RS_5 = 17;
   // Common channels between 5.1.2 and 7.1.2.
   CHANNEL_LABEL_LTF_2 = 22;
   CHANNEL_LABEL_RTF_2 = 23;
   // Common channels between 5.1.4 and 7.1.4.
   CHANNEL_LABEL_LTF_4 = 26;
   CHANNEL_LABEL_RTF_4 = 27;
   CHANNEL_LABEL_LTB_4 = 28;
   CHANNEL_LABEL_RTB_4 = 29;
   // 7.x.y surround channels.
   CHANNEL_LABEL_L_7 = 32;
   CHANNEL_LABEL_R_7 = 33;
   CHANNEL_LABEL_LSS_7 = 34;
   CHANNEL_LABEL_RSS_7 = 35;
   CHANNEL_LABEL_LRS_7 = 36;
   CHANNEL_LABEL_RRS_7 = 37;
   // 9.1.6 surround channels.
   CHANNEL_LABEL_FLC = 42;
   CHANNEL_LABEL_FC = 43;
   CHANNEL_LABEL_FRC = 44;
   CHANNEL_LABEL_FL = 45;
   CHANNEL_LABEL_FR = 46;
   CHANNEL_LABEL_SI_L = 47;
   CHANNEL_LABEL_SI_R = 48;
   CHANNEL_LABEL_BL = 49;
   CHANNEL_LABEL_BR = 50;
   CHANNEL_LABEL_TP_FL = 51;
   CHANNEL_LABEL_TP_FR = 52;
   CHANNEL_LABEL_TP_SI_L = 53;
   CHANNEL_LABEL_TP_SI_R = 54;
   CHANNEL_LABEL_TP_BL = 55;
   CHANNEL_LABEL_TP_BR = 56;
   // Reserved for possible use of demixed labels.
   reserved 5, 12, 13, 18 to 21, 24, 25, 30, 31, 38 to 41;
   // Reserved for channel-based labels.
   reserved 57 to 999;

   CHANNEL_LABEL_A_0 = 1000;
   CHANNEL_LABEL_A_1 = 1001;
   CHANNEL_LABEL_A_2 = 1002;
   CHANNEL_LABEL_A_3 = 1003;
   CHANNEL_LABEL_A_4 = 1004;
   CHANNEL_LABEL_A_5 = 1005;
   CHANNEL_LABEL_A_6 = 1006;
   CHANNEL_LABEL_A_7 = 1007;
   CHANNEL_LABEL_A_8 = 1008;
   CHANNEL_LABEL_A_9 = 1009;
   CHANNEL_LABEL_A_10 = 1010;
   CHANNEL_LABEL_A_11 = 1011;
   CHANNEL_LABEL_A_12 = 1012;
   CHANNEL_LABEL_A_13 = 1013;
   CHANNEL_LABEL_A_14 = 1014;
   CHANNEL_LABEL_A_15 = 1015;
   CHANNEL_LABEL_A_16 = 1016;
   CHANNEL_LABEL_A_17 = 1017;
   CHANNEL_LABEL_A_18 = 1018;
   CHANNEL_LABEL_A_19 = 1019;
   CHANNEL_LABEL_A_20 = 1020;
   CHANNEL_LABEL_A_21 = 1021;
   CHANNEL_LABEL_A_22 = 1022;
   CHANNEL_LABEL_A_23 = 1023;
   CHANNEL_LABEL_A_24 = 1024;
   reserved 1025 to 1224;  // Reserved for future ambisonics channels.

   // Next ID: 57 (channel-based) or 1025 (ambisonics).
 }

 message ChannelMetadata {
   // Used to map the index of the channel in an ADM or WAV file. Ignored when
   // data comes from other sources.
   optional uint32 channel_id = 1;

   // The IAMF-based channel label.
   optional ChannelLabel channel_label = 2;
 }

 message AudioFrameObuMetadata {
   reserved 2, 3;

   optional string wav_filename = 1;

   // Controls whether the number of samples required to pad the final frame are
   // automatically added to the `samples_to_trim_at_end` value.
   //
   // When `true` `samples_to_trim_at_end` matches `num_samples_to_trim_at_end`
   // in the OBU header. If the actual value is too small to account for padding,
   // then encoding will fail. This is useful to closely represent the value in
   // the OBU (rarely needed).
   //
   // When `false` `num_samples_to_trim_at_end` will be incremented by the
   // amount of required padding and may not match the OBU header value. This is
   // useful to closely represent the trimming applied to the original audio
   // content (typically recommended).
   //
   // Typically the recommended settings are:
   //   - samples_to_trim_at_end_includes_padding: false
   //   - samples_to_trim_at_end: 0
   // These settings will automatically insert the correct padding to create a
   // valid final frame and avoid trimming the original audio content.
   optional bool samples_to_trim_at_end_includes_padding = 9 [default = true];
   optional uint32 samples_to_trim_at_end = 4;

   // Controls whether the number of samples required by codec delay for the
   // initial first frames are automatically added to the
   // `samples_to_trim_at_start` value.
   //
   // When `true` `samples_to_trim_at_start` relates directly to
   // `samples_to_trim_at_start`s in the initial OBU header. If the actual
   // value is too small to account for codec delay, then encoding will fail.
   // This is useful to closely represent the values in the initial OBUs (rarely
   // needed).
   //
   // When `false` `samples_to_trim_at_start` will be incremented by the
   // amount of required for the codec delay and may not match the OBU header
   // value. This is useful to closely represent the trimming applied to the
   // original audio content (typically recommended).
   //
   // Typically the recommended settings are:
   //   - samples_to_trim_at_start_includes_codec_delay: false
   //   - samples_to_trim_at_start: 0
   // These settings will automatically insert the correct codec delay to create
   // a valid final frame and avoid trimming the original audio content.
   optional bool samples_to_trim_at_start_includes_codec_delay = 10
       [default = true];
   optional uint32 samples_to_trim_at_start = 5;

   // ID of the audio element whose substreams will be provided/mixed
   // from the channels in this WAV file.
   optional uint32 audio_element_id = 6;

   // Channels used in this WAV file, in the order as described in [ITU2051-3]
   // for loudspeaker layouts or ACN order for ambisonics. May be fewer than
   // the total number of channels in the WAV file if only a subset is to be
   // used.
   repeated uint32 channel_ids = 7 [packed = true, deprecated = true];

   // Channel Labels, e.g. "L2", "Ls5". For ambisonics, use "A{ACN number}",
   // e.g. "A0", "A13". Must be of the same length as `channel_ids`.
   repeated string channel_labels = 8 [deprecated = true];

   // Prefer `channel_metadata` over `channel_ids` and `channel_labels`.
   repeated ChannelMetadata channel_metadatas = 11;

   // Next ID: 12
 }
	// Copyright (c) 2023, Alliance for Open Media. All rights reserved
	//
	// This source code is subject to the terms of the BSD 3-Clause Clear License
	// and the Alliance for Open Media Patent License 1.0. If the BSD 3-Clause Clear
	// License was not distributed with this source code in the LICENSE file, you
	// can obtain it at www.aomedia.org/license/software-license/bsd-3-c-c. If the
	// Alliance for Open Media Patent License 1.0 was not distributed with this
	// source code in the PATENTS file, you can obtain it at
	// www.aomedia.org/license/patent.

	syntax = "proto2";

	package iamf_tools_cli_proto;

	enum ChannelLabel {
	CHANNEL_LABEL_INVALID = 0;
	reserved 1; // Reserved for potential "omitted" label.
	// Mono channels.
	CHANNEL_LABEL_MONO = 2;
	// Stereo or binaural channels.
	CHANNEL_LABEL_L_2 = 3;
	CHANNEL_LABEL_R_2 = 4;
	// Centre channel common to several layouts (e.g. 3.1.2, 5.x.y, 7.x.y).
	CHANNEL_LABEL_CENTRE = 6;
	// LFE channel common to several layouts (e.g. 3.1.2, 5.1.y, 7.1.y, 9.1.6).
	CHANNEL_LABEL_LFE = 7;
	// 3.1.2 surround channels.
	CHANNEL_LABEL_L_3 = 8;
	CHANNEL_LABEL_R_3 = 9;
	CHANNEL_LABEL_LTF_3 = 10;
	CHANNEL_LABEL_RTF_3 = 11;
	// 5.x.y surround channels.
	CHANNEL_LABEL_L_5 = 14;
	CHANNEL_LABEL_R_5 = 15;
	CHANNEL_LABEL_LS_5 = 16;
	CHANNEL_LABEL_RS_5 = 17;
	// Common channels between 5.1.2 and 7.1.2.
	CHANNEL_LABEL_LTF_2 = 22;
	CHANNEL_LABEL_RTF_2 = 23;
	// Common channels between 5.1.4 and 7.1.4.
	CHANNEL_LABEL_LTF_4 = 26;
	CHANNEL_LABEL_RTF_4 = 27;
	CHANNEL_LABEL_LTB_4 = 28;
	CHANNEL_LABEL_RTB_4 = 29;
	// 7.x.y surround channels.
	CHANNEL_LABEL_L_7 = 32;
	CHANNEL_LABEL_R_7 = 33;
	CHANNEL_LABEL_LSS_7 = 34;
	CHANNEL_LABEL_RSS_7 = 35;
	CHANNEL_LABEL_LRS_7 = 36;
	CHANNEL_LABEL_RRS_7 = 37;
	// 9.1.6 surround channels.
	CHANNEL_LABEL_FLC = 42;
	CHANNEL_LABEL_FC = 43;
	CHANNEL_LABEL_FRC = 44;
	CHANNEL_LABEL_FL = 45;
	CHANNEL_LABEL_FR = 46;
	CHANNEL_LABEL_SI_L = 47;
	CHANNEL_LABEL_SI_R = 48;
	CHANNEL_LABEL_BL = 49;
	CHANNEL_LABEL_BR = 50;
	CHANNEL_LABEL_TP_FL = 51;
	CHANNEL_LABEL_TP_FR = 52;
	CHANNEL_LABEL_TP_SI_L = 53;
	CHANNEL_LABEL_TP_SI_R = 54;
	CHANNEL_LABEL_TP_BL = 55;
	CHANNEL_LABEL_TP_BR = 56;
	// Reserved for possible use of demixed labels.
	reserved 5, 12, 13, 18 to 21, 24, 25, 30, 31, 38 to 41;
	// Reserved for channel-based labels.
	reserved 57 to 999;

	CHANNEL_LABEL_A_0 = 1000;
	CHANNEL_LABEL_A_1 = 1001;
	CHANNEL_LABEL_A_2 = 1002;
	CHANNEL_LABEL_A_3 = 1003;
	CHANNEL_LABEL_A_4 = 1004;
	CHANNEL_LABEL_A_5 = 1005;
	CHANNEL_LABEL_A_6 = 1006;
	CHANNEL_LABEL_A_7 = 1007;
	CHANNEL_LABEL_A_8 = 1008;
	CHANNEL_LABEL_A_9 = 1009;
	CHANNEL_LABEL_A_10 = 1010;
	CHANNEL_LABEL_A_11 = 1011;
	CHANNEL_LABEL_A_12 = 1012;
	CHANNEL_LABEL_A_13 = 1013;
	CHANNEL_LABEL_A_14 = 1014;
	CHANNEL_LABEL_A_15 = 1015;
	CHANNEL_LABEL_A_16 = 1016;
	CHANNEL_LABEL_A_17 = 1017;
	CHANNEL_LABEL_A_18 = 1018;
	CHANNEL_LABEL_A_19 = 1019;
	CHANNEL_LABEL_A_20 = 1020;
	CHANNEL_LABEL_A_21 = 1021;
	CHANNEL_LABEL_A_22 = 1022;
	CHANNEL_LABEL_A_23 = 1023;
	CHANNEL_LABEL_A_24 = 1024;
	reserved 1025 to 1224; // Reserved for future ambisonics channels.

	// Next ID: 57 (channel-based) or 1025 (ambisonics).
	}

	message ChannelMetadata {
	// Used to map the index of the channel in an ADM or WAV file. Ignored when
	// data comes from other sources.
	optional uint32 channel_id = 1;

	// The IAMF-based channel label.
	optional ChannelLabel channel_label = 2;
	}

	message AudioFrameObuMetadata {
	reserved 2, 3;

	optional string wav_filename = 1;

	// Controls whether the number of samples required to pad the final frame are
	// automatically added to the `samples_to_trim_at_end` value.
	//
	// When `true` `samples_to_trim_at_end` matches `num_samples_to_trim_at_end`
	// in the OBU header. If the actual value is too small to account for padding,
	// then encoding will fail. This is useful to closely represent the value in
	// the OBU (rarely needed).
	//
	// When `false` `num_samples_to_trim_at_end` will be incremented by the
	// amount of required padding and may not match the OBU header value. This is
	// useful to closely represent the trimming applied to the original audio
	// content (typically recommended).
	//
	// Typically the recommended settings are:
	// - samples_to_trim_at_end_includes_padding: false
	// - samples_to_trim_at_end: 0
	// These settings will automatically insert the correct padding to create a
	// valid final frame and avoid trimming the original audio content.
	optional bool samples_to_trim_at_end_includes_padding = 9 [default = true];
	optional uint32 samples_to_trim_at_end = 4;

	// Controls whether the number of samples required by codec delay for the
	// initial first frames are automatically added to the
	// `samples_to_trim_at_start` value.
	//
	// When `true` `samples_to_trim_at_start` relates directly to
	// `samples_to_trim_at_start`s in the initial OBU header. If the actual
	// value is too small to account for codec delay, then encoding will fail.
	// This is useful to closely represent the values in the initial OBUs (rarely
	// needed).
	//
	// When `false` `samples_to_trim_at_start` will be incremented by the
	// amount of required for the codec delay and may not match the OBU header
	// value. This is useful to closely represent the trimming applied to the
	// original audio content (typically recommended).
	//
	// Typically the recommended settings are:
	// - samples_to_trim_at_start_includes_codec_delay: false
	// - samples_to_trim_at_start: 0
	// These settings will automatically insert the correct codec delay to create
	// a valid final frame and avoid trimming the original audio content.
	optional bool samples_to_trim_at_start_includes_codec_delay = 10
	[default = true];
	optional uint32 samples_to_trim_at_start = 5;

	// ID of the audio element whose substreams will be provided/mixed
	// from the channels in this WAV file.
	optional uint32 audio_element_id = 6;

	// Channels used in this WAV file, in the order as described in [ITU2051-3]
	// for loudspeaker layouts or ACN order for ambisonics. May be fewer than
	// the total number of channels in the WAV file if only a subset is to be
	// used.
	repeated uint32 channel_ids = 7 [packed = true, deprecated = true];

	// Channel Labels, e.g. "L2", "Ls5". For ambisonics, use "A{ACN number}",
	// e.g. "A0", "A13". Must be of the same length as `channel_ids`.
	repeated string channel_labels = 8 [deprecated = true];

	// Prefer `channel_metadata` over `channel_ids` and `channel_labels`.
	repeated ChannelMetadata channel_metadatas = 11;

	// Next ID: 12
	}