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