1 /* 2 * Copyright 2018 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_JAUDIOTRACK_H 18 #define ANDROID_JAUDIOTRACK_H 19 20 #include <utility> 21 #include <jni.h> 22 #include <media/AudioResamplerPublic.h> 23 #include <media/AudioSystem.h> 24 #include <media/VolumeShaper.h> 25 #include <system/audio.h> 26 #include <utils/Errors.h> 27 #include <utils/Vector.h> 28 #include <mediaplayer2/JObjectHolder.h> 29 #include <media/AudioTimestamp.h> // It has dependency on audio.h/Errors.h, but doesn't 30 // include them in it. Therefore it is included here at last. 31 32 namespace android { 33 34 class JAudioTrack : public RefBase { 35 public: 36 37 /* Events used by AudioTrack callback function (callback_t). 38 * Keep in sync with frameworks/base/media/java/android/media/AudioTrack.java NATIVE_EVENT_*. 39 */ 40 enum event_type { 41 EVENT_MORE_DATA = 0, // Request to write more data to buffer. 42 EVENT_UNDERRUN = 1, // Buffer underrun occurred. This will not occur for 43 // static tracks. 44 EVENT_NEW_IAUDIOTRACK = 6, // IAudioTrack was re-created, either due to re-routing and 45 // voluntary invalidation by mediaserver, or mediaserver crash. 46 EVENT_STREAM_END = 7, // Sent after all the buffers queued in AF and HW are played 47 // back (after stop is called) for an offloaded track. 48 }; 49 50 class Buffer 51 { 52 public: 53 size_t mSize; // input/output in bytes. 54 void* mData; // pointer to the audio data. 55 }; 56 57 /* As a convenience, if a callback is supplied, a handler thread 58 * is automatically created with the appropriate priority. This thread 59 * invokes the callback when a new buffer becomes available or various conditions occur. 60 * 61 * Parameters: 62 * 63 * event: type of event notified (see enum AudioTrack::event_type). 64 * user: Pointer to context for use by the callback receiver. 65 * info: Pointer to optional parameter according to event type: 66 * - EVENT_MORE_DATA: pointer to JAudioTrack::Buffer struct. The callback must not 67 * write more bytes than indicated by 'size' field and update 'size' if fewer bytes 68 * are written. 69 * - EVENT_NEW_IAUDIOTRACK: unused. 70 * - EVENT_STREAM_END: unused. 71 */ 72 73 typedef void (*callback_t)(int event, void* user, void *info); 74 75 /* Creates an JAudioTrack object for non-offload mode. 76 * Once created, the track needs to be started before it can be used. 77 * Unspecified values are set to appropriate default values. 78 * 79 * Parameters: 80 * 81 * streamType: Select the type of audio stream this track is attached to 82 * (e.g. AUDIO_STREAM_MUSIC). 83 * sampleRate: Data source sampling rate in Hz. Zero means to use the sink sample rate. 84 * A non-zero value must be specified if AUDIO_OUTPUT_FLAG_DIRECT is set. 85 * 0 will not work with current policy implementation for direct output 86 * selection where an exact match is needed for sampling rate. 87 * (TODO: Check direct output after flags can be used in Java AudioTrack.) 88 * format: Audio format. For mixed tracks, any PCM format supported by server is OK. 89 * For direct and offloaded tracks, the possible format(s) depends on the 90 * output sink. 91 * (TODO: How can we check whether a format is supported?) 92 * channelMask: Channel mask, such that audio_is_output_channel(channelMask) is true. 93 * cbf: Callback function. If not null, this function is called periodically 94 * to provide new data and inform of marker, position updates, etc. 95 * user: Context for use by the callback receiver. 96 * frameCount: Minimum size of track PCM buffer in frames. This defines the 97 * application's contribution to the latency of the track. 98 * The actual size selected by the JAudioTrack could be larger if the 99 * requested size is not compatible with current audio HAL configuration. 100 * Zero means to use a default value. 101 * sessionId: Specific session ID, or zero to use default. 102 * pAttributes: If not NULL, supersedes streamType for use case selection. 103 * maxRequiredSpeed: For PCM tracks, this creates an appropriate buffer size that will allow 104 * maxRequiredSpeed playback. Values less than 1.0f and greater than 105 * AUDIO_TIMESTRETCH_SPEED_MAX will be clamped. For non-PCM tracks 106 * and direct or offloaded tracks, this parameter is ignored. 107 * (TODO: Handle this after offload / direct track is supported.) 108 * 109 * TODO: Revive removed arguments after offload mode is supported. 110 */ 111 JAudioTrack(uint32_t sampleRate, 112 audio_format_t format, 113 audio_channel_mask_t channelMask, 114 callback_t cbf, 115 void* user, 116 size_t frameCount = 0, 117 int32_t sessionId = AUDIO_SESSION_ALLOCATE, 118 const jobject pAttributes = NULL, 119 float maxRequiredSpeed = 1.0f); 120 121 /* 122 // Q. May be used in AudioTrack.setPreferredDevice(AudioDeviceInfo)? 123 audio_port_handle_t selectedDeviceId, 124 125 // TODO: No place to use these values. 126 int32_t notificationFrames, 127 const audio_offload_info_t *offloadInfo, 128 */ 129 130 virtual ~JAudioTrack(); 131 132 size_t frameCount(); 133 size_t channelCount(); 134 135 /* Returns this track's estimated latency in milliseconds. 136 * This includes the latency due to AudioTrack buffer size, AudioMixer (if any) 137 * and audio hardware driver. 138 */ 139 uint32_t latency(); 140 141 /* Return the total number of frames played since playback start. 142 * The counter will wrap (overflow) periodically, e.g. every ~27 hours at 44.1 kHz. 143 * It is reset to zero by flush(), reload(), and stop(). 144 * 145 * Parameters: 146 * 147 * position: Address where to return play head position. 148 * 149 * Returned status (from utils/Errors.h) can be: 150 * - NO_ERROR: successful operation 151 * - BAD_VALUE: position is NULL 152 */ 153 status_t getPosition(uint32_t *position); 154 155 // TODO: Does this comment apply same to Java AudioTrack::getTimestamp? 156 // Changed the return type from status_t to bool, since Java AudioTrack::getTimestamp returns 157 // boolean. Will Java getTimestampWithStatus() be public? 158 /* Poll for a timestamp on demand. 159 * Use if EVENT_NEW_TIMESTAMP is not delivered often enough for your needs, 160 * or if you need to get the most recent timestamp outside of the event callback handler. 161 * Caution: calling this method too often may be inefficient; 162 * if you need a high resolution mapping between frame position and presentation time, 163 * consider implementing that at application level, based on the low resolution timestamps. 164 * Returns NO_ERROR if timestamp is valid. 165 * NO_INIT if finds error, and timestamp parameter will be undefined on return. 166 */ 167 status_t getTimestamp(AudioTimestamp& timestamp); 168 169 // TODO: This doc is just copied from AudioTrack.h. Revise it after implemenation. 170 /* Return the extended timestamp, with additional timebase info and improved drain behavior. 171 * 172 * This is similar to the AudioTrack.java API: 173 * getTimestamp(@NonNull AudioTimestamp timestamp, @AudioTimestamp.Timebase int timebase) 174 * 175 * Some differences between this method and the getTimestamp(AudioTimestamp& timestamp) method 176 * 177 * 1. stop() by itself does not reset the frame position. 178 * A following start() resets the frame position to 0. 179 * 2. flush() by itself does not reset the frame position. 180 * The frame position advances by the number of frames flushed, 181 * when the first frame after flush reaches the audio sink. 182 * 3. BOOTTIME clock offsets are provided to help synchronize with 183 * non-audio streams, e.g. sensor data. 184 * 4. Position is returned with 64 bits of resolution. 185 * 186 * Parameters: 187 * timestamp: A pointer to the caller allocated ExtendedTimestamp. 188 * 189 * Returns NO_ERROR on success; timestamp is filled with valid data. 190 * BAD_VALUE if timestamp is NULL. 191 * WOULD_BLOCK if called immediately after start() when the number 192 * of frames consumed is less than the 193 * overall hardware latency to physical output. In WOULD_BLOCK cases, 194 * one might poll again, or use getPosition(), or use 0 position and 195 * current time for the timestamp. 196 * If WOULD_BLOCK is returned, the timestamp is still 197 * modified with the LOCATION_CLIENT portion filled. 198 * DEAD_OBJECT if AudioFlinger dies or the output device changes and 199 * the track cannot be automatically restored. 200 * The application needs to recreate the AudioTrack 201 * because the audio device changed or AudioFlinger died. 202 * This typically occurs for direct or offloaded tracks 203 * or if mDoNotReconnect is true. 204 * INVALID_OPERATION if called on a offloaded or direct track. 205 * Use getTimestamp(AudioTimestamp& timestamp) instead. 206 */ 207 status_t getTimestamp(ExtendedTimestamp *timestamp); 208 209 /* Set source playback rate for timestretch 210 * 1.0 is normal speed: < 1.0 is slower, > 1.0 is faster 211 * 1.0 is normal pitch: < 1.0 is lower pitch, > 1.0 is higher pitch 212 * 213 * AUDIO_TIMESTRETCH_SPEED_MIN <= speed <= AUDIO_TIMESTRETCH_SPEED_MAX 214 * AUDIO_TIMESTRETCH_PITCH_MIN <= pitch <= AUDIO_TIMESTRETCH_PITCH_MAX 215 * 216 * Speed increases the playback rate of media, but does not alter pitch. 217 * Pitch increases the "tonal frequency" of media, but does not affect the playback rate. 218 */ 219 status_t setPlaybackRate(const AudioPlaybackRate &playbackRate); 220 221 /* Return current playback rate */ 222 const AudioPlaybackRate getPlaybackRate(); 223 224 /* Sets the volume shaper object */ 225 media::VolumeShaper::Status applyVolumeShaper( 226 const sp<media::VolumeShaper::Configuration>& configuration, 227 const sp<media::VolumeShaper::Operation>& operation); 228 229 /* Set the send level for this track. An auxiliary effect should be attached 230 * to the track with attachEffect(). Level must be >= 0.0 and <= 1.0. 231 */ 232 status_t setAuxEffectSendLevel(float level); 233 234 /* Attach track auxiliary output to specified effect. Use effectId = 0 235 * to detach track from effect. 236 * 237 * Parameters: 238 * 239 * effectId: effectId obtained from AudioEffect::id(). 240 * 241 * Returned status (from utils/Errors.h) can be: 242 * - NO_ERROR: successful operation 243 * - INVALID_OPERATION: The effect is not an auxiliary effect. 244 * - BAD_VALUE: The specified effect ID is invalid. 245 */ 246 status_t attachAuxEffect(int effectId); 247 248 /* Set volume for this track, mostly used for games' sound effects 249 * left and right volumes. Levels must be >= 0.0 and <= 1.0. 250 * This is the older API. New applications should use setVolume(float) when possible. 251 */ 252 status_t setVolume(float left, float right); 253 254 /* Set volume for all channels. This is the preferred API for new applications, 255 * especially for multi-channel content. 256 */ 257 status_t setVolume(float volume); 258 259 // TODO: Does this comment equally apply to the Java AudioTrack::play()? 260 /* After it's created the track is not active. Call start() to 261 * make it active. If set, the callback will start being called. 262 * If the track was previously paused, volume is ramped up over the first mix buffer. 263 */ 264 status_t start(); 265 266 // TODO: Does this comment still applies? It seems not. (obtainBuffer, AudioFlinger, ...) 267 /* As a convenience we provide a write() interface to the audio buffer. 268 * Input parameter 'size' is in byte units. 269 * This is implemented on top of obtainBuffer/releaseBuffer. For best 270 * performance use callbacks. Returns actual number of bytes written >= 0, 271 * or one of the following negative status codes: 272 * INVALID_OPERATION AudioTrack is configured for static buffer or streaming mode 273 * BAD_VALUE size is invalid 274 * WOULD_BLOCK when obtainBuffer() returns same, or 275 * AudioTrack was stopped during the write 276 * DEAD_OBJECT when AudioFlinger dies or the output device changes and 277 * the track cannot be automatically restored. 278 * The application needs to recreate the AudioTrack 279 * because the audio device changed or AudioFlinger died. 280 * This typically occurs for direct or offload tracks 281 * or if mDoNotReconnect is true. 282 * or any other error code returned by IAudioTrack::start() or restoreTrack_l(). 283 * Default behavior is to only return when all data has been transferred. Set 'blocking' to 284 * false for the method to return immediately without waiting to try multiple times to write 285 * the full content of the buffer. 286 */ 287 ssize_t write(const void* buffer, size_t size, bool blocking = true); 288 289 // TODO: Does this comment equally apply to the Java AudioTrack::stop()? 290 /* Stop a track. 291 * In static buffer mode, the track is stopped immediately. 292 * In streaming mode, the callback will cease being called. Note that obtainBuffer() still 293 * works and will fill up buffers until the pool is exhausted, and then will return WOULD_BLOCK. 294 * In streaming mode the stop does not occur immediately: any data remaining in the buffer 295 * is first drained, mixed, and output, and only then is the track marked as stopped. 296 */ 297 void stop(); 298 bool stopped() const; 299 300 // TODO: Does this comment equally apply to the Java AudioTrack::flush()? 301 /* Flush a stopped or paused track. All previously buffered data is discarded immediately. 302 * This has the effect of draining the buffers without mixing or output. 303 * Flush is intended for streaming mode, for example before switching to non-contiguous content. 304 * This function is a no-op if the track is not stopped or paused, or uses a static buffer. 305 */ 306 void flush(); 307 308 // TODO: Does this comment equally apply to the Java AudioTrack::pause()? 309 // At least we are not using obtainBuffer. 310 /* Pause a track. After pause, the callback will cease being called and 311 * obtainBuffer returns WOULD_BLOCK. Note that obtainBuffer() still works 312 * and will fill up buffers until the pool is exhausted. 313 * Volume is ramped down over the next mix buffer following the pause request, 314 * and then the track is marked as paused. It can be resumed with ramp up by start(). 315 */ 316 void pause(); 317 318 bool isPlaying() const; 319 320 /* Return current source sample rate in Hz. 321 * If specified as zero in constructor, this will be the sink sample rate. 322 */ 323 uint32_t getSampleRate(); 324 325 /* Returns the buffer duration in microseconds at current playback rate. */ 326 status_t getBufferDurationInUs(int64_t *duration); 327 328 audio_format_t format(); 329 330 size_t frameSize(); 331 332 /* 333 * Dumps the state of an audio track. 334 * Not a general-purpose API; intended only for use by media player service to dump its tracks. 335 */ 336 status_t dump(int fd, const Vector<String16>& args) const; 337 338 /* Returns the AudioDeviceInfo used by the output to which this AudioTrack is 339 * attached. 340 */ 341 jobject getRoutedDevice(); 342 343 /* Returns the ID of the audio session this AudioTrack belongs to. */ 344 int32_t getAudioSessionId(); 345 346 /* Sets the preferred audio device to use for output of this AudioTrack. 347 * 348 * Parameters: 349 * Device: an AudioDeviceInfo object. 350 * 351 * Returned value: 352 * - NO_ERROR: successful operation 353 * - BAD_VALUE: failed to set the device 354 */ 355 status_t setPreferredDevice(jobject device); 356 357 // TODO: Add AUDIO_OUTPUT_FLAG_DIRECT when it is possible to check. 358 // TODO: Add AUDIO_FLAG_HW_AV_SYNC when it is possible to check. 359 /* Returns the flags */ getFlags()360 audio_output_flags_t getFlags() const { return mFlags; } 361 362 /* We don't keep stream type here, 363 * instead, we keep attributes and call getVolumeControlStream() to get stream type 364 */ 365 audio_stream_type_t getAudioStreamType(); 366 367 /* Obtain the pending duration in milliseconds for playback of pure PCM data remaining in 368 * AudioTrack. 369 * 370 * Returns NO_ERROR if successful. 371 * INVALID_OPERATION if the AudioTrack does not contain pure PCM data. 372 * BAD_VALUE if msec is nullptr. 373 */ 374 status_t pendingDuration(int32_t *msec); 375 376 /* Adds an AudioDeviceCallback. The caller will be notified when the audio device to which this 377 * AudioTrack is routed is updated. 378 * Replaces any previously installed callback. 379 * 380 * Parameters: 381 * Listener: the listener to receive notification of rerouting events. 382 * Handler: the handler to handler the rerouting events. 383 * 384 * Returns NO_ERROR if successful. 385 * (TODO) INVALID_OPERATION if the same callback is already installed. 386 * (TODO) NO_INIT or PREMISSION_DENIED if AudioFlinger service is not reachable 387 * (TODO) BAD_VALUE if the callback is NULL 388 */ 389 status_t addAudioDeviceCallback(jobject listener, jobject rd); 390 391 /* Removes an AudioDeviceCallback. 392 * 393 * Parameters: 394 * Listener: the listener to receive notification of rerouting events. 395 * 396 * Returns NO_ERROR if successful. 397 * (TODO) INVALID_OPERATION if the callback is not installed 398 * (TODO) BAD_VALUE if the callback is NULL 399 */ 400 status_t removeAudioDeviceCallback(jobject listener); 401 402 /* Register all backed-up routing delegates. 403 * 404 * Parameters: 405 * routingDelegates: backed-up routing delegates 406 * 407 */ 408 void registerRoutingDelegates( 409 Vector<std::pair<sp<JObjectHolder>, sp<JObjectHolder>>>& routingDelegates); 410 411 /* get listener from RoutingDelegate object 412 */ 413 static jobject getListener(const jobject routingDelegateObj); 414 415 /* get handler from RoutingDelegate object 416 */ 417 static jobject getHandler(const jobject routingDelegateObj); 418 419 /* 420 * Parameters: 421 * map and key 422 * 423 * Returns value if key is in the map 424 * nullptr if key is not in the map 425 */ 426 static jobject findByKey( 427 Vector<std::pair<sp<JObjectHolder>, sp<JObjectHolder>>>& mp, const jobject key); 428 429 /* 430 * Parameters: 431 * map and key 432 */ 433 static void eraseByKey( 434 Vector<std::pair<sp<JObjectHolder>, sp<JObjectHolder>>>& mp, const jobject key); 435 436 private: 437 audio_output_flags_t mFlags; 438 439 jclass mAudioTrackCls; 440 jobject mAudioTrackObj; 441 442 /* Creates a Java VolumeShaper.Configuration object from VolumeShaper::Configuration */ 443 jobject createVolumeShaperConfigurationObj( 444 const sp<media::VolumeShaper::Configuration>& config); 445 446 /* Creates a Java VolumeShaper.Operation object from VolumeShaper::Operation */ 447 jobject createVolumeShaperOperationObj( 448 const sp<media::VolumeShaper::Operation>& operation); 449 450 /* Creates a Java StreamEventCallback object */ 451 jobject createStreamEventCallback(callback_t cbf, void* user); 452 453 /* Creates a Java Executor object for running a callback */ 454 jobject createCallbackExecutor(); 455 456 status_t javaToNativeStatus(int javaStatus); 457 }; 458 459 }; // namespace android 460 461 #endif // ANDROID_JAUDIOTRACK_H 462