diff --git a/audio/6.0/IStreamOutEventCallback.hal b/audio/6.0/IStreamOutEventCallback.hal index de17d735de..9c8871306e 100644 --- a/audio/6.0/IStreamOutEventCallback.hal +++ b/audio/6.0/IStreamOutEventCallback.hal @@ -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 + * + * Datum = { + * (type_size_t) Type (the type index from type_as_value.) + * (datum_size_t) Size (size of the Payload) + * (byte string) Payload + * } + * + * The data is specified in native endian order. + * Since the size of the Payload is always present, unknown types may be skipped. + * + * Payload + * [ sizeof(Primitive_Value) in raw bytes ] + * + * Example of Payload of 123: + * Payload + * [ value of 123 ] = 0x7b 0x00 0x00 0x00 123 + * + * Payload + * [ (index_size_t) length, not including zero terminator.] + * [ (length) raw bytes ] + * + * Example of Payload of std::string("hi"): + * [ (index_size_t) length ] = 0x02 0x00 0x00 0x00 2 strlen("hi") + * [ raw bytes "hi" ] = 0x68 0x69 "hi" + * + * Payload + * [ (index_size_t) entries ] + * [ raw bytes (entry 1) Key (Payload) + * Value (Datum) + * ... (until #entries) ] + * + * Example of Payload of {{"hello", "world"}, + * {"value", (int32_t)1000}}; + * [ (index_size_t) #entries ] = 0x02 0x00 0x00 0x00 2 entries + * Key (Payload) + * [ 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 + * [ (index_size_t) length ] = 0x05 0x00 0x00 0x00 5 strlen("world") + * [ raw bytes "world" ] = 0x77 0x6f 0x72 0x6c 0x64 "world" + * Key (Payload) + * [ 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 + * [ raw bytes 1000 ] = 0xe8 0x03 0x00 0x00 1000 + * + * The contents of audioMetadata is a Payload. + * 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 audioMetadata); }; diff --git a/current.txt b/current.txt index 4bdaba48bc..84a1a0d969 100644 --- a/current.txt +++ b/current.txt @@ -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