1 /* 2 * Copyright (C) 2020 The Android Open Source Project 3 * 4 * Licensed under the Apache License, Version 2.0 (the "License"); 5 * you may not use this file except in compliance with the License. 6 * You may obtain a copy of the License at 7 * 8 * http://www.apache.org/licenses/LICENSE-2.0 9 * 10 * Unless required by applicable law or agreed to in writing, software 11 * distributed under the License is distributed on an "AS IS" BASIS, 12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 13 * See the License for the specific language governing permissions and 14 * limitations under the License. 15 */ 16 17 #ifndef ANDROID_MEDIA_MEDIAMETRICSCONSTANTS_H 18 #define ANDROID_MEDIA_MEDIAMETRICSCONSTANTS_H 19 20 /* 21 * MediaMetrics Keys and Properties. 22 * 23 * C/C++ friendly constants that ensure 24 * 1) Compilation error on misspelling 25 * 2) Consistent behavior and documentation. 26 */ 27 28 /* 29 * Taxonomy of audio keys 30 * 31 * To build longer keys, we use compiler string concatenation of 32 * adjacent string literals. This is done in the translation phase 33 * of compilation to make a single string token. 34 */ 35 36 // Key Prefixes are used for MediaMetrics Item Keys and ends with a ".". 37 // They must be appended with another value to make a key. 38 #define AMEDIAMETRICS_KEY_PREFIX_AUDIO "audio." 39 40 // Device related key prefix. 41 #define AMEDIAMETRICS_KEY_PREFIX_AUDIO_DEVICE AMEDIAMETRICS_KEY_PREFIX_AUDIO "device." 42 43 // The AudioMmap key appends the "trackId" to the prefix. 44 // This is the AudioFlinger equivalent of the AAudio Stream. 45 // TODO: unify with AMEDIAMETRICS_KEY_PREFIX_AUDIO_STREAM 46 #define AMEDIAMETRICS_KEY_PREFIX_AUDIO_MMAP AMEDIAMETRICS_KEY_PREFIX_AUDIO "mmap." 47 48 // The AudioRecord key appends the "trackId" to the prefix. 49 #define AMEDIAMETRICS_KEY_PREFIX_AUDIO_RECORD AMEDIAMETRICS_KEY_PREFIX_AUDIO "record." 50 51 // The AudioStream key appends the "streamId" to the prefix. 52 #define AMEDIAMETRICS_KEY_PREFIX_AUDIO_STREAM AMEDIAMETRICS_KEY_PREFIX_AUDIO "stream." 53 54 // The AudioThread key appends the "threadId" to the prefix. 55 #define AMEDIAMETRICS_KEY_PREFIX_AUDIO_THREAD AMEDIAMETRICS_KEY_PREFIX_AUDIO "thread." 56 57 // The AudioTrack key appends the "trackId" to the prefix. 58 #define AMEDIAMETRICS_KEY_PREFIX_AUDIO_TRACK AMEDIAMETRICS_KEY_PREFIX_AUDIO "track." 59 60 // Keys are strings used for MediaMetrics Item Keys 61 #define AMEDIAMETRICS_KEY_AUDIO_FLINGER AMEDIAMETRICS_KEY_PREFIX_AUDIO "flinger" 62 #define AMEDIAMETRICS_KEY_AUDIO_POLICY AMEDIAMETRICS_KEY_PREFIX_AUDIO "policy" 63 64 // Error keys 65 #define AMEDIAMETRICS_KEY_AUDIO_TRACK_ERROR AMEDIAMETRICS_KEY_PREFIX_AUDIO_TRACK "error" 66 67 /* 68 * MediaMetrics Properties are unified space for consistency and readability. 69 */ 70 71 // Property prefixes may be applied before a property name to indicate a specific 72 // category to which it is associated. 73 #define AMEDIAMETRICS_PROP_PREFIX_EFFECTIVE "effective." 74 #define AMEDIAMETRICS_PROP_PREFIX_HAL "hal." 75 #define AMEDIAMETRICS_PROP_PREFIX_HAPTIC "haptic." 76 #define AMEDIAMETRICS_PROP_PREFIX_SERVER "server." 77 78 // Properties within mediametrics are string constants denoted by 79 // a macro name beginning with AMEDIAMETRICS_PROP_* 80 // 81 // For a property name like "auxEffectId" we write this as a single upper case word 82 // at the end of the macro name, such as AMEDIAMETRICS_PROP_AUXEFFECTID. 83 // 84 // Underscores after the AMEDIAMETRICS_PROP_* prefix indicate 85 // a "dot" in the property name. For example AMEDIAMETRICS_PROP_VOLUME_LEFT 86 // corresponds to "volume.left". 87 // 88 // The property names are camel case, typically a lowercase letter [a-z] 89 // followed by one or more characters in the range [a-zA-Z0-9_.]. 90 // Special symbols such as !@#$%^&*()[]{}<>,:;'"\/?|+-=~ are reserved. 91 // 92 // Properties within this header should include special suffixes like '#' 93 // directly in the string for brevity. Code outside of this header should 94 // use the macro constant for the special symbols for searchability. 95 96 // Any property that ends with a # will have duplicate values listed instead 97 // of suppressed in the Time Machine. 98 #define AMEDIAMETRICS_PROP_SUFFIX_CHAR_DUPLICATES_ALLOWED '#' 99 100 #define AMEDIAMETRICS_PROP_ALLOWUID "_allowUid" // int32_t, allow client uid to post 101 #define AMEDIAMETRICS_PROP_AUDIOMODE "audioMode" // string (audio.flinger) 102 #define AMEDIAMETRICS_PROP_AUXEFFECTID "auxEffectId" // int32 (AudioTrack) 103 #define AMEDIAMETRICS_PROP_BUFFERSIZEFRAMES "bufferSizeFrames" // int32 104 #define AMEDIAMETRICS_PROP_BUFFERCAPACITYFRAMES "bufferCapacityFrames" // int32 105 #define AMEDIAMETRICS_PROP_BURSTFRAMES "burstFrames" // int32 106 #define AMEDIAMETRICS_PROP_CALLERNAME "callerName" // string, eg. "aaudio" 107 #define AMEDIAMETRICS_PROP_CHANNELCOUNT "channelCount" // int32 108 #define AMEDIAMETRICS_PROP_CHANNELMASK "channelMask" // int32 109 #define AMEDIAMETRICS_PROP_CONTENTTYPE "contentType" // string attributes (AudioTrack) 110 #define AMEDIAMETRICS_PROP_CUMULATIVETIMENS "cumulativeTimeNs" // int64_t playback/record time 111 // since start 112 // DEVICE values are averaged since starting on device 113 #define AMEDIAMETRICS_PROP_DEVICELATENCYMS "deviceLatencyMs" // double - avg latency time 114 #define AMEDIAMETRICS_PROP_DEVICESTARTUPMS "deviceStartupMs" // double - avg startup time 115 #define AMEDIAMETRICS_PROP_DEVICETIMENS "deviceTimeNs" // int64_t playback/record time 116 #define AMEDIAMETRICS_PROP_DEVICEVOLUME "deviceVolume" // double - average device volume 117 118 #define AMEDIAMETRICS_PROP_DIRECTION "direction" // string AAudio input or output 119 #define AMEDIAMETRICS_PROP_DURATIONNS "durationNs" // int64 duration time span 120 #define AMEDIAMETRICS_PROP_ENCODING "encoding" // string value of format 121 122 #define AMEDIAMETRICS_PROP_EVENT "event#" // string value (often func name) 123 #define AMEDIAMETRICS_PROP_EXECUTIONTIMENS "executionTimeNs" // time to execute the event 124 125 // TODO: fix inconsistency in flags: AudioRecord / AudioTrack int32, AudioThread string 126 #define AMEDIAMETRICS_PROP_FLAGS "flags" 127 128 #define AMEDIAMETRICS_PROP_FRAMECOUNT "frameCount" // int32 129 #define AMEDIAMETRICS_PROP_INPUTDEVICES "inputDevices" // string value 130 #define AMEDIAMETRICS_PROP_INTERNALTRACKID "internalTrackId" // int32 131 #define AMEDIAMETRICS_PROP_INTERVALCOUNT "intervalCount" // int32 132 #define AMEDIAMETRICS_PROP_LATENCYMS "latencyMs" // double value 133 #define AMEDIAMETRICS_PROP_LOGSESSIONID "logSessionId" // hex string, "" none 134 #define AMEDIAMETRICS_PROP_NAME "name" // string value 135 #define AMEDIAMETRICS_PROP_ORIGINALFLAGS "originalFlags" // int32 136 #define AMEDIAMETRICS_PROP_OUTPUTDEVICES "outputDevices" // string value 137 #define AMEDIAMETRICS_PROP_PERFORMANCEMODE "performanceMode" // string value, "none", lowLatency" 138 #define AMEDIAMETRICS_PROP_PLAYBACK_PITCH "playback.pitch" // double value (AudioTrack) 139 #define AMEDIAMETRICS_PROP_PLAYBACK_SPEED "playback.speed" // double value (AudioTrack) 140 #define AMEDIAMETRICS_PROP_PLAYERIID "playerIId" // int32 (-1 invalid/unset IID) 141 #define AMEDIAMETRICS_PROP_ROUTEDDEVICEID "routedDeviceId" // int32 142 #define AMEDIAMETRICS_PROP_SAMPLERATE "sampleRate" // int32 143 #define AMEDIAMETRICS_PROP_SELECTEDDEVICEID "selectedDeviceId" // int32 144 #define AMEDIAMETRICS_PROP_SELECTEDMICDIRECTION "selectedMicDirection" // int32 145 #define AMEDIAMETRICS_PROP_SELECTEDMICFIELDDIRECTION "selectedMicFieldDimension" // double 146 #define AMEDIAMETRICS_PROP_SESSIONID "sessionId" // int32 147 #define AMEDIAMETRICS_PROP_SHARINGMODE "sharingMode" // string value, "exclusive", shared" 148 #define AMEDIAMETRICS_PROP_SOURCE "source" // string (AudioAttributes) 149 #define AMEDIAMETRICS_PROP_STARTTHRESHOLDFRAMES "startThresholdFrames" // int32 (AudioTrack) 150 #define AMEDIAMETRICS_PROP_STARTUPMS "startupMs" // double value 151 // State is "ACTIVE" or "STOPPED" for AudioRecord 152 #define AMEDIAMETRICS_PROP_STATE "state" // string 153 #define AMEDIAMETRICS_PROP_STATUS "status#" // int32 status_t 154 // AAudio uses their own status codes 155 // Supplemental information to the status code. 156 #define AMEDIAMETRICS_PROP_STATUSSUBCODE "statusSubCode" // int32, specific code 157 // used in conjunction with status. 158 #define AMEDIAMETRICS_PROP_STATUSMESSAGE "statusMessage" // string, supplemental info. 159 // Arbitrary information treated as 160 // informational, may be logcat msg, 161 // or an exception with stack trace. 162 // Treated as "debug" information. 163 164 #define AMEDIAMETRICS_PROP_STREAMTYPE "streamType" // string (AudioTrack) 165 #define AMEDIAMETRICS_PROP_THREADID "threadId" // int32 value io handle 166 #define AMEDIAMETRICS_PROP_THROTTLEMS "throttleMs" // double 167 #define AMEDIAMETRICS_PROP_TRACKID "trackId" // int32 port id of track/record 168 #define AMEDIAMETRICS_PROP_TRAITS "traits" // string 169 #define AMEDIAMETRICS_PROP_TYPE "type" // string (thread type) 170 #define AMEDIAMETRICS_PROP_UNDERRUN "underrun" // int32 171 #define AMEDIAMETRICS_PROP_UNDERRUNFRAMES "underrunFrames" // int64_t from Thread 172 #define AMEDIAMETRICS_PROP_USAGE "usage" // string attributes (ATrack) 173 #define AMEDIAMETRICS_PROP_VOICEVOLUME "voiceVolume" // double (audio.flinger) 174 #define AMEDIAMETRICS_PROP_VOLUME_LEFT "volume.left" // double (AudioTrack) 175 #define AMEDIAMETRICS_PROP_VOLUME_RIGHT "volume.right" // double (AudioTrack) 176 #define AMEDIAMETRICS_PROP_WHERE "where" // string value 177 // EncodingClient is the encoding format requested by the client 178 #define AMEDIAMETRICS_PROP_ENCODINGCLIENT "encodingClient" // string 179 // PerformanceModeActual is the actual selected performance mode, could be "none', "lowLatency" or 180 // "powerSaving" 181 #define AMEDIAMETRICS_PROP_PERFORMANCEMODEACTUAL "performanceModeActual" // string 182 #define AMEDIAMETRICS_PROP_FRAMESTRANSFERRED "framesTransferred" // int64_t, transferred frames 183 // string value, "exclusive", "shared". the actual selected sharing mode by the server 184 #define AMEDIAMETRICS_PROP_SHARINGMODEACTUAL "sharingModeActual" 185 186 // Timing values: millisecond values are suffixed with MS and the type is double 187 // nanosecond values are suffixed with NS and the type is int64. 188 189 // Values are strings accepted for a given property. 190 191 // An event is a general description, which often is a function name. 192 #define AMEDIAMETRICS_PROP_EVENT_VALUE_BEGINAUDIOINTERVALGROUP "beginAudioIntervalGroup" 193 #define AMEDIAMETRICS_PROP_EVENT_VALUE_CLOSE "close" 194 #define AMEDIAMETRICS_PROP_EVENT_VALUE_CREATE "create" 195 #define AMEDIAMETRICS_PROP_EVENT_VALUE_CREATEAUDIOPATCH "createAudioPatch" 196 #define AMEDIAMETRICS_PROP_EVENT_VALUE_CTOR "ctor" 197 #define AMEDIAMETRICS_PROP_EVENT_VALUE_DISCONNECT "disconnect" 198 #define AMEDIAMETRICS_PROP_EVENT_VALUE_DTOR "dtor" 199 #define AMEDIAMETRICS_PROP_EVENT_VALUE_ENDAAUDIOSTREAM "endAAudioStream" // AAudioStream 200 #define AMEDIAMETRICS_PROP_EVENT_VALUE_ENDAUDIOINTERVALGROUP "endAudioIntervalGroup" 201 #define AMEDIAMETRICS_PROP_EVENT_VALUE_FLUSH "flush" // AudioTrack 202 #define AMEDIAMETRICS_PROP_EVENT_VALUE_INVALIDATE "invalidate" // server track, record 203 #define AMEDIAMETRICS_PROP_EVENT_VALUE_OPEN "open" 204 #define AMEDIAMETRICS_PROP_EVENT_VALUE_PAUSE "pause" // AudioTrack 205 #define AMEDIAMETRICS_PROP_EVENT_VALUE_READPARAMETERS "readParameters" // Thread 206 #define AMEDIAMETRICS_PROP_EVENT_VALUE_RELEASE "release" 207 #define AMEDIAMETRICS_PROP_EVENT_VALUE_RESTORE "restore" 208 #define AMEDIAMETRICS_PROP_EVENT_VALUE_SETMODE "setMode" // AudioFlinger 209 #define AMEDIAMETRICS_PROP_EVENT_VALUE_SETBUFFERSIZE "setBufferSize" // AudioTrack 210 #define AMEDIAMETRICS_PROP_EVENT_VALUE_SETLOGSESSIONID "setLogSessionId" // AudioTrack, Record 211 #define AMEDIAMETRICS_PROP_EVENT_VALUE_SETPLAYBACKPARAM "setPlaybackParam" // AudioTrack 212 #define AMEDIAMETRICS_PROP_EVENT_VALUE_SETPLAYERIID "setPlayerIId" // AudioTrack 213 #define AMEDIAMETRICS_PROP_EVENT_VALUE_SETSTARTTHRESHOLD "setStartThreshold" // AudioTrack 214 #define AMEDIAMETRICS_PROP_EVENT_VALUE_SETVOICEVOLUME "setVoiceVolume" // AudioFlinger 215 #define AMEDIAMETRICS_PROP_EVENT_VALUE_SETVOLUME "setVolume" // AudioTrack 216 #define AMEDIAMETRICS_PROP_EVENT_VALUE_START "start" // AudioTrack, AudioRecord 217 #define AMEDIAMETRICS_PROP_EVENT_VALUE_STOP "stop" // AudioTrack, AudioRecord 218 #define AMEDIAMETRICS_PROP_EVENT_VALUE_UNDERRUN "underrun" // from Thread 219 220 // Possible values for AMEDIAMETRICS_PROP_CALLERNAME 221 // Check within the framework for these strings as this header file may not be explicitly 222 // included to avoid unnecessary cross-project dependencies. 223 #define AMEDIAMETRICS_PROP_CALLERNAME_VALUE_AAUDIO "aaudio" // Native AAudio 224 #define AMEDIAMETRICS_PROP_CALLERNAME_VALUE_JAVA "java" // Java API layer 225 #define AMEDIAMETRICS_PROP_CALLERNAME_VALUE_MEDIA "media" // libmedia 226 #define AMEDIAMETRICS_PROP_CALLERNAME_VALUE_OPENSLES "opensles" // Open SLES 227 #define AMEDIAMETRICS_PROP_CALLERNAME_VALUE_RTP "rtp" // RTP communication 228 #define AMEDIAMETRICS_PROP_CALLERNAME_VALUE_SOUNDPOOL "soundpool" // SoundPool 229 #define AMEDIAMETRICS_PROP_CALLERNAME_VALUE_TONEGENERATOR "tonegenerator" // dial tones 230 #define AMEDIAMETRICS_PROP_CALLERNAME_VALUE_UNKNOWN "unknown" // callerName not set 231 232 // MediaMetrics errors are expected to cover the following sources: 233 // https://docs.oracle.com/javase/7/docs/api/java/lang/RuntimeException.html 234 // https://docs.oracle.com/javase/7/docs/api/java/lang/Exception.html 235 // https://cs.android.com/android/platform/superproject/+/master:frameworks/native/libs/binder/include/binder/Status.h;drc=88e25c0861499ee3ab885814dddc097ab234cb7b;l=57 236 // https://cs.android.com/android/platform/superproject/+/master:frameworks/base/media/java/android/media/AudioSystem.java;drc=3ac246c43294d7f7012bdcb0ccb7bae1aa695bd4;l=785 237 // https://cs.android.com/android/platform/superproject/+/master:frameworks/av/media/libaaudio/include/aaudio/AAudio.h;drc=cfd3a6fa3aaaf712a890dc02452b38ef401083b8;l=120 238 // https://abseil.io/docs/cpp/guides/status-codes 239 240 // Status errors: 241 // An empty status string or "ok" is interpreted as no error. 242 #define AMEDIAMETRICS_PROP_STATUS_VALUE_OK "ok" 243 244 // Error category: argument 245 // IllegalArgumentException 246 // NullPointerException 247 // BAD_VALUE 248 // absl::INVALID_ARGUMENT 249 // absl::OUT_OF_RANGE 250 // Out of range, out of bounds. 251 #define AMEDIAMETRICS_PROP_STATUS_VALUE_ARGUMENT "argument" 252 253 // Error category: io 254 // IOException 255 // android.os.DeadObjectException, android.os.RemoteException 256 // DEAD_OBJECT 257 // FAILED_TRANSACTION 258 // IO_ERROR 259 // file or ioctl failure 260 // Service, rpc, binder, or socket failure. 261 // Hardware or device failure. 262 #define AMEDIAMETRICS_PROP_STATUS_VALUE_IO "io" 263 264 // Error category: outOfMemory 265 // OutOfMemoryException 266 // NO_MEMORY 267 // absl::RESOURCE_EXHAUSTED 268 #define AMEDIAMETRICS_PROP_STATUS_VALUE_MEMORY "memory" 269 270 // Error category: security 271 // SecurityException 272 // PERMISSION_DENIED 273 // absl::PERMISSION_DENIED 274 // absl::UNAUTHENTICATED 275 #define AMEDIAMETRICS_PROP_STATUS_VALUE_SECURITY "security" 276 277 // Error category: state 278 // IllegalStateException 279 // UnsupportedOperationException 280 // INVALID_OPERATION 281 // NO_INIT 282 // absl::NOT_FOUND 283 // absl::ALREADY_EXISTS 284 // absl::FAILED_PRECONDITION 285 // absl::UNAVAILABLE 286 // absl::UNIMPLEMENTED 287 // Functionality not implemented (argument may or may not be correct). 288 // Call unexpected or out of order. 289 #define AMEDIAMETRICS_PROP_STATUS_VALUE_STATE "state" 290 291 // Error category: timeout 292 // TimeoutException 293 // WOULD_BLOCK 294 // absl::DEADLINE_EXCEEDED 295 // absl::ABORTED 296 #define AMEDIAMETRICS_PROP_STATUS_VALUE_TIMEOUT "timeout" 297 298 // Error category: unknown 299 // Exception (Java specified not listed above, or custom app/service) 300 // UNKNOWN_ERROR 301 // absl::INTERNAL 302 // absl::DATA_LOSS 303 // Catch-all bucket for errors not listed above. 304 #define AMEDIAMETRICS_PROP_STATUS_VALUE_UNKNOWN "unknown" 305 306 #endif // ANDROID_MEDIA_MEDIAMETRICSCONSTANTS_H 307