Evolution-x/hardware_interfaces
1
0
Fork 0
mirror of https://github.com/Evolution-X/hardware_interfaces synced 2026-02-01 11:36:00 +00:00
Code Issues Packages Projects Releases Wiki Activity

AudioMetadata: Add documentation

Browse Source 
Update comments only for IStreamOutEventCallback::onCodecFormatChanged

Test: compiles, this is a comment change only.
Bug: 150175043
Change-Id: I1895c737997fbf3cb509b4078b545658d11df198
This commit is contained in:
Andy Hung
2020-04-30 00:20:48 -07:00
parent 2023afbe66
commit e6b9c77789
2 changed files with 109 additions and 3 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
audio/6.0/IStreamOutEventCallback.hal
View File

@@ -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);
};

1
current.txt
View File

@@ -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