1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
/*
* Copyright (C) 2020 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package android.hardware.audio@6.0;
/**
* Asynchronous stream out event callback interface. The interface provides
* a way for the HAL to notify platform when there are changes, e.g. codec
* format change, from the lower layer.
*/
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.
*/
oneway onCodecFormatChanged(vec<uint8_t> audioMetadata);
};
|
