Merge "AudioMetadata: Add documentation" into rvc-dev (425e3652) · Commits · e / os / android_hardware_interfaces

audio/6.0/IStreamOutEventCallback.hal

+108 −3

Original line number	Diff line number	Diff line
		@@ -25,11 +25,116 @@ interface IStreamOutEventCallback {
		/**
		* Codec format changed.
		*
		* onCodecFormatChanged returns an AudioMetadata object in read-only ByteString format.
		* It represents the most recent codec format decoded by a HW audio decoder.
		*
		* Codec format is an optional message from HW audio decoders. It serves to
		* notify the application about the codec format and audio objects contained
		* within the compressed audio stream for control, informational,
		* and display purposes.
		*
		* audioMetadata ByteString is convertible to an AudioMetadata object through
		* both a C++ and a C API present in Metadata.h [1], or through a Java API present
		* in AudioMetadata.java [2].
		*
		* The ByteString format is a stable format used for parcelling (marshalling) across
		* JNI, AIDL, and HIDL interfaces. The test for R compatibility for native marshalling
		* is TEST(metadata_tests, compatibility_R) [3]. The test for R compatibility for JNI
		* marshalling is android.media.cts.AudioMetadataTest#testCompatibilityR [4].
		*
		* R (audio HAL 6.0) defined keys are as follows [2]:
		* "bitrate", int32
		* "channel-mask", int32
		* "mime", string
		* "sample-rate", int32
		* "bit-width", int32
		* "has-atmos", int32
		* "audio-encoding", int32
		*
		* Parceling Format:
		* All values are native endian order. [1]
		*
		* using type_size_t = uint32_t;
		* using index_size_t = uint32_t;
		* using datum_size_t = uint32_t;
		*
		* Permitted type indexes are
		* TYPE_NONE = 0, // Reserved
		* TYPE_INT32 = 1,
		* TYPE_INT64 = 2,
		* TYPE_FLOAT = 3,
		* TYPE_DOUBLE = 4,
		* TYPE_STRING = 5,
		* TYPE_DATA = 6, // A data table of <String, Datum>
		*
		* Datum = {
		* (type_size_t) Type (the type index from type_as_value<T>.)
		* (datum_size_t) Size (size of the Payload)
		* (byte string) Payload<Type>
		* }
		*
		* The data is specified in native endian order.
		* Since the size of the Payload is always present, unknown types may be skipped.
		*
		* Payload<Fixed-size Primitive_Value>
		* [ sizeof(Primitive_Value) in raw bytes ]
		*
		* Example of Payload<Int32> of 123:
		* Payload<Int32>
		* [ value of 123 ] = 0x7b 0x00 0x00 0x00 123
		*
		* Payload<String>
		* [ (index_size_t) length, not including zero terminator.]
		* [ (length) raw bytes ]
		*
		* Example of Payload<String> of std::string("hi"):
		* [ (index_size_t) length ] = 0x02 0x00 0x00 0x00 2 strlen("hi")
		* [ raw bytes "hi" ] = 0x68 0x69 "hi"
		*
		* Payload<Data>
		* [ (index_size_t) entries ]
		* [ raw bytes (entry 1) Key (Payload<String>)
		* Value (Datum)
		* ... (until #entries) ]
		*
		* Example of Payload<Data> of {{"hello", "world"},
		* {"value", (int32_t)1000}};
		* [ (index_size_t) #entries ] = 0x02 0x00 0x00 0x00 2 entries
		* Key (Payload<String>)
		* [ index_size_t length ] = 0x05 0x00 0x00 0x00 5 strlen("hello")
		* [ raw bytes "hello" ] = 0x68 0x65 0x6c 0x6c 0x6f "hello"
		* Value (Datum)
		* [ (type_size_t) type ] = 0x05 0x00 0x00 0x00 5 (TYPE_STRING)
		* [ (datum_size_t) size ] = 0x09 0x00 0x00 0x00 sizeof(index_size_t) +
		* strlen("world")
		* Payload<String>
		* [ (index_size_t) length ] = 0x05 0x00 0x00 0x00 5 strlen("world")
		* [ raw bytes "world" ] = 0x77 0x6f 0x72 0x6c 0x64 "world"
		* Key (Payload<String>)
		* [ index_size_t length ] = 0x05 0x00 0x00 0x00 5 strlen("value")
		* [ raw bytes "value" ] = 0x76 0x61 0x6c 0x75 0x65 "value"
		* Value (Datum)
		* [ (type_size_t) type ] = 0x01 0x00 0x00 0x00 1 (TYPE_INT32)
		* [ (datum_size_t) size ] = 0x04 0x00 0x00 0x00 4 sizeof(int32_t)
		* Payload<Int32>
		* [ raw bytes 1000 ] = 0xe8 0x03 0x00 0x00 1000
		*
		* The contents of audioMetadata is a Payload<Data>.
		* An implementation dependent detail is that the Keys are always
		* stored sorted, so the byte string representation generated is unique.
		*
		* Vendor keys are allowed for informational and debugging purposes.
		* Vendor keys should consist of the vendor company name followed
		* by a dot; for example, "vendorCompany.someVolume" [2].
		*
		* [1] system/media/audio_utils/include/audio_utils/Metadata.h
		* [2] frameworks/base/media/java/android/media/AudioMetadata.java
		* [3] system/media/audio_utils/tests/metadata_tests.cpp
		* [4] cts/tests/tests/media/src/android/media/cts/AudioMetadataTest.java
		*
		* @param audioMetadata is a buffer containing decoded format changes
		* reported by codec. The buffer contains data that can be transformed
		* to audio metadata, which is a C++ object based map. See
		* `system/media/audio_utils/include/audio_utils/Metadata.h` for
		* more details.
		* to audio metadata, which is a C++ object based map.
		*/
		oneway onCodecFormatChanged(vec<uint8_t> audioMetadata);
		};

current.txt

+1 −0

Original line number	Diff line number	Diff line
		@@ -619,6 +619,7 @@ fd1f1b29f26b42e886220f04a08086c00e5ade9d7b53f095438e578ab9d42a93 android.hardwar
		164826a380f4c1700183003f62d7532e367b67381c30ea44f946c0cf00008f85 android.hardware.audio@6.0::IStreamOut
		997fdaad7a9d17ee7e01feb7031a753e2365e72ad30b11d950e9183fabdf3844 android.hardware.audio@6.0::IStreamOutCallback
		e7ca0db9a1098210f327a9b152fa6afe6bf019c41e5264c64829d04d50c0a526 android.hardware.audio@6.0::IStreamOutEventCallback
		aa2211abd803e03d05ea11c18749db068f785fe026f8d99bce64bd764f63d194 android.hardware.audio@6.0::IStreamOutEventCallback # b/150175043
		822369cf4dc16a6f6b9622bcf86cbdc0b692dc82193fc15e967767175cbfdd8f android.hardware.audio@6.0::types
		bee662c62d997d8065e2bcb5c1e7a9578931f22ce28fd02c219fdb4d0630abf7 android.hardware.audio.common@6.0::types
		525bec6b44f1103869c269a128d51b8dccd73af5340ba863c8886c68357c7faf android.hardware.audio.effect@6.0::IAcousticEchoCancelerEffect