AudioTrack.h revision 291f4d505aff81969e6666049d3cc3446f836af2
1/* 2 * Copyright (C) 2007 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_AUDIOTRACK_H 18#define ANDROID_AUDIOTRACK_H 19 20#include <stdint.h> 21#include <sys/types.h> 22 23#include <media/IAudioFlinger.h> 24#include <media/IAudioTrack.h> 25#include <media/AudioSystem.h> 26 27#include <utils/RefBase.h> 28#include <utils/Errors.h> 29#include <binder/IInterface.h> 30#include <binder/IMemory.h> 31#include <utils/threads.h> 32 33namespace android { 34 35// ---------------------------------------------------------------------------- 36 37class audio_track_cblk_t; 38 39// ---------------------------------------------------------------------------- 40 41class AudioTrack : virtual public RefBase 42{ 43public: 44 enum channel_index { 45 MONO = 0, 46 LEFT = 0, 47 RIGHT = 1 48 }; 49 50 /* Events used by AudioTrack callback function (audio_track_cblk_t). 51 */ 52 enum event_type { 53 EVENT_MORE_DATA = 0, // Request to write more data to PCM buffer. 54 EVENT_UNDERRUN = 1, // PCM buffer underrun occured. 55 EVENT_LOOP_END = 2, // Sample loop end was reached; playback restarted from loop start if loop count was not 0. 56 EVENT_MARKER = 3, // Playback head is at the specified marker position (See setMarkerPosition()). 57 EVENT_NEW_POS = 4, // Playback head is at a new position (See setPositionUpdatePeriod()). 58 EVENT_BUFFER_END = 5 // Playback head is at the end of the buffer. 59 }; 60 61 /* Client should declare Buffer on the stack and pass address to obtainBuffer() 62 * and releaseBuffer(). See also callback_t for EVENT_MORE_DATA. 63 */ 64 65 class Buffer 66 { 67 public: 68 enum { 69 MUTE = 0x00000001 70 }; 71 uint32_t flags; // 0 or MUTE 72 audio_format_t format; // but AUDIO_FORMAT_PCM_8_BIT -> AUDIO_FORMAT_PCM_16_BIT 73 // accessed directly by WebKit ANP callback 74 int channelCount; // will be removed in the future, do not use 75 76 size_t frameCount; // number of sample frames corresponding to size; 77 // on input it is the number of frames desired, 78 // on output is the number of frames actually filled 79 80 size_t size; // input/output in byte units 81 union { 82 void* raw; 83 short* i16; // signed 16-bit 84 int8_t* i8; // unsigned 8-bit, offset by 0x80 85 }; 86 }; 87 88 89 /* As a convenience, if a callback is supplied, a handler thread 90 * is automatically created with the appropriate priority. This thread 91 * invokes the callback when a new buffer becomes available or various conditions occur. 92 * Parameters: 93 * 94 * event: type of event notified (see enum AudioTrack::event_type). 95 * user: Pointer to context for use by the callback receiver. 96 * info: Pointer to optional parameter according to event type: 97 * - EVENT_MORE_DATA: pointer to AudioTrack::Buffer struct. The callback must not write 98 * more bytes than indicated by 'size' field and update 'size' if fewer bytes are 99 * written. 100 * - EVENT_UNDERRUN: unused. 101 * - EVENT_LOOP_END: pointer to an int indicating the number of loops remaining. 102 * - EVENT_MARKER: pointer to an uint32_t containing the marker position in frames. 103 * - EVENT_NEW_POS: pointer to an uint32_t containing the new position in frames. 104 * - EVENT_BUFFER_END: unused. 105 */ 106 107 typedef void (*callback_t)(int event, void* user, void *info); 108 109 /* Returns the minimum frame count required for the successful creation of 110 * an AudioTrack object. 111 * Returned status (from utils/Errors.h) can be: 112 * - NO_ERROR: successful operation 113 * - NO_INIT: audio server or audio hardware not initialized 114 */ 115 116 static status_t getMinFrameCount(int* frameCount, 117 audio_stream_type_t streamType = AUDIO_STREAM_DEFAULT, 118 uint32_t sampleRate = 0); 119 120 /* Constructs an uninitialized AudioTrack. No connection with 121 * AudioFlinger takes place. 122 */ 123 AudioTrack(); 124 125 /* Creates an audio track and registers it with AudioFlinger. 126 * Once created, the track needs to be started before it can be used. 127 * Unspecified values are set to the audio hardware's current 128 * values. 129 * 130 * Parameters: 131 * 132 * streamType: Select the type of audio stream this track is attached to 133 * (e.g. AUDIO_STREAM_MUSIC). 134 * sampleRate: Track sampling rate in Hz. 135 * format: Audio format (e.g AUDIO_FORMAT_PCM_16_BIT for signed 136 * 16 bits per sample). 137 * channelMask: Channel mask: see audio_channels_t. 138 * frameCount: Minimum size of track PCM buffer in frames. This defines the 139 * latency of the track. The actual size selected by the AudioTrack could be 140 * larger if the requested size is not compatible with current audio HAL 141 * latency. 142 * flags: Reserved for future use. 143 * cbf: Callback function. If not null, this function is called periodically 144 * to request new PCM data. 145 * user: Context for use by the callback receiver. 146 * notificationFrames: The callback function is called each time notificationFrames PCM 147 * frames have been consumed from track input buffer. 148 * sessionId: Specific session ID, or zero to use default. 149 */ 150 151 AudioTrack( audio_stream_type_t streamType, 152 uint32_t sampleRate = 0, 153 audio_format_t format = AUDIO_FORMAT_DEFAULT, 154 int channelMask = 0, 155 int frameCount = 0, 156 audio_policy_output_flags_t flags = AUDIO_POLICY_OUTPUT_FLAG_NONE, 157 callback_t cbf = NULL, 158 void* user = NULL, 159 int notificationFrames = 0, 160 int sessionId = 0); 161 162 // DEPRECATED 163 explicit AudioTrack( int streamType, 164 uint32_t sampleRate = 0, 165 int format = AUDIO_FORMAT_DEFAULT, 166 int channelMask = 0, 167 int frameCount = 0, 168 uint32_t flags = (uint32_t) AUDIO_POLICY_OUTPUT_FLAG_NONE, 169 callback_t cbf = 0, 170 void* user = 0, 171 int notificationFrames = 0, 172 int sessionId = 0); 173 174 /* Creates an audio track and registers it with AudioFlinger. With this constructor, 175 * the PCM data to be rendered by AudioTrack is passed in a shared memory buffer 176 * identified by the argument sharedBuffer. This prototype is for static buffer playback. 177 * PCM data must be present in memory before the AudioTrack is started. 178 * The write() and flush() methods are not supported in this case. 179 * It is recommended to pass a callback function to be notified of playback end by an 180 * EVENT_UNDERRUN event. 181 */ 182 183 AudioTrack( audio_stream_type_t streamType, 184 uint32_t sampleRate = 0, 185 audio_format_t format = AUDIO_FORMAT_DEFAULT, 186 int channelMask = 0, 187 const sp<IMemory>& sharedBuffer = 0, 188 audio_policy_output_flags_t flags = AUDIO_POLICY_OUTPUT_FLAG_NONE, 189 callback_t cbf = NULL, 190 void* user = NULL, 191 int notificationFrames = 0, 192 int sessionId = 0); 193 194 /* Terminates the AudioTrack and unregisters it from AudioFlinger. 195 * Also destroys all resources associated with the AudioTrack. 196 */ 197 ~AudioTrack(); 198 199 200 /* Initialize an uninitialized AudioTrack. 201 * Returned status (from utils/Errors.h) can be: 202 * - NO_ERROR: successful initialization 203 * - INVALID_OPERATION: AudioTrack is already initialized 204 * - BAD_VALUE: invalid parameter (channels, format, sampleRate...) 205 * - NO_INIT: audio server or audio hardware not initialized 206 * */ 207 status_t set(audio_stream_type_t streamType = AUDIO_STREAM_DEFAULT, 208 uint32_t sampleRate = 0, 209 audio_format_t format = AUDIO_FORMAT_DEFAULT, 210 int channelMask = 0, 211 int frameCount = 0, 212 audio_policy_output_flags_t flags = AUDIO_POLICY_OUTPUT_FLAG_NONE, 213 callback_t cbf = NULL, 214 void* user = NULL, 215 int notificationFrames = 0, 216 const sp<IMemory>& sharedBuffer = 0, 217 bool threadCanCallJava = false, 218 int sessionId = 0); 219 220 221 /* Result of constructing the AudioTrack. This must be checked 222 * before using any AudioTrack API (except for set()), because using 223 * an uninitialized AudioTrack produces undefined results. 224 * See set() method above for possible return codes. 225 */ 226 status_t initCheck() const; 227 228 /* Returns this track's estimated latency in milliseconds. 229 * This includes the latency due to AudioTrack buffer size, AudioMixer (if any) 230 * and audio hardware driver. 231 */ 232 uint32_t latency() const; 233 234 /* getters, see constructors and set() */ 235 236 audio_stream_type_t streamType() const; 237 audio_format_t format() const; 238 int channelCount() const; 239 uint32_t frameCount() const; 240 241 /* Return channelCount * (bit depth per channel / 8). 242 * channelCount is determined from channelMask, and bit depth comes from format. 243 */ 244 size_t frameSize() const; 245 246 sp<IMemory>& sharedBuffer(); 247 248 249 /* After it's created the track is not active. Call start() to 250 * make it active. If set, the callback will start being called. 251 */ 252 void start(); 253 254 /* Stop a track. If set, the callback will cease being called and 255 * obtainBuffer returns STOPPED. Note that obtainBuffer() still works 256 * and will fill up buffers until the pool is exhausted. 257 */ 258 void stop(); 259 bool stopped() const; 260 261 /* Flush a stopped track. All pending buffers are discarded. 262 * This function has no effect if the track is not stopped. 263 */ 264 void flush(); 265 266 /* Pause a track. If set, the callback will cease being called and 267 * obtainBuffer returns STOPPED. Note that obtainBuffer() still works 268 * and will fill up buffers until the pool is exhausted. 269 */ 270 void pause(); 271 272 /* Mute or unmute this track. 273 * While muted, the callback, if set, is still called. 274 */ 275 void mute(bool); 276 bool muted() const; 277 278 /* Set volume for this track, mostly used for games' sound effects 279 * left and right volumes. Levels must be >= 0.0 and <= 1.0. 280 */ 281 status_t setVolume(float left, float right); 282 void getVolume(float* left, float* right) const; 283 284 /* Set the send level for this track. An auxiliary effect should be attached 285 * to the track with attachEffect(). Level must be >= 0.0 and <= 1.0. 286 */ 287 status_t setAuxEffectSendLevel(float level); 288 void getAuxEffectSendLevel(float* level) const; 289 290 /* Set sample rate for this track, mostly used for games' sound effects 291 */ 292 status_t setSampleRate(int sampleRate); 293 uint32_t getSampleRate() const; 294 295 /* Enables looping and sets the start and end points of looping. 296 * 297 * Parameters: 298 * 299 * loopStart: loop start expressed as the number of PCM frames played since AudioTrack start. 300 * loopEnd: loop end expressed as the number of PCM frames played since AudioTrack start. 301 * loopCount: number of loops to execute. Calling setLoop() with loopCount == 0 cancels any 302 * pending or active loop. loopCount = -1 means infinite looping. 303 * 304 * For proper operation the following condition must be respected: 305 * (loopEnd-loopStart) <= framecount() 306 */ 307 status_t setLoop(uint32_t loopStart, uint32_t loopEnd, int loopCount); 308 309 /* Sets marker position. When playback reaches the number of frames specified, a callback with 310 * event type EVENT_MARKER is called. Calling setMarkerPosition with marker == 0 cancels marker 311 * notification callback. 312 * If the AudioTrack has been opened with no callback function associated, the operation will fail. 313 * 314 * Parameters: 315 * 316 * marker: marker position expressed in frames. 317 * 318 * Returned status (from utils/Errors.h) can be: 319 * - NO_ERROR: successful operation 320 * - INVALID_OPERATION: the AudioTrack has no callback installed. 321 */ 322 status_t setMarkerPosition(uint32_t marker); 323 status_t getMarkerPosition(uint32_t *marker) const; 324 325 326 /* Sets position update period. Every time the number of frames specified has been played, 327 * a callback with event type EVENT_NEW_POS is called. 328 * Calling setPositionUpdatePeriod with updatePeriod == 0 cancels new position notification 329 * callback. 330 * If the AudioTrack has been opened with no callback function associated, the operation will fail. 331 * 332 * Parameters: 333 * 334 * updatePeriod: position update notification period expressed in frames. 335 * 336 * Returned status (from utils/Errors.h) can be: 337 * - NO_ERROR: successful operation 338 * - INVALID_OPERATION: the AudioTrack has no callback installed. 339 */ 340 status_t setPositionUpdatePeriod(uint32_t updatePeriod); 341 status_t getPositionUpdatePeriod(uint32_t *updatePeriod) const; 342 343 /* Sets playback head position within AudioTrack buffer. The new position is specified 344 * in number of frames. 345 * This method must be called with the AudioTrack in paused or stopped state. 346 * Note that the actual position set is <position> modulo the AudioTrack buffer size in frames. 347 * Therefore using this method makes sense only when playing a "static" audio buffer 348 * as opposed to streaming. 349 * The getPosition() method on the other hand returns the total number of frames played since 350 * playback start. 351 * 352 * Parameters: 353 * 354 * position: New playback head position within AudioTrack buffer. 355 * 356 * Returned status (from utils/Errors.h) can be: 357 * - NO_ERROR: successful operation 358 * - INVALID_OPERATION: the AudioTrack is not stopped. 359 * - BAD_VALUE: The specified position is beyond the number of frames present in AudioTrack buffer 360 */ 361 status_t setPosition(uint32_t position); 362 status_t getPosition(uint32_t *position); 363 364 /* Forces AudioTrack buffer full condition. When playing a static buffer, this method avoids 365 * rewriting the buffer before restarting playback after a stop. 366 * This method must be called with the AudioTrack in paused or stopped state. 367 * 368 * Returned status (from utils/Errors.h) can be: 369 * - NO_ERROR: successful operation 370 * - INVALID_OPERATION: the AudioTrack is not stopped. 371 */ 372 status_t reload(); 373 374 /* Returns a handle on the audio output used by this AudioTrack. 375 * 376 * Parameters: 377 * none. 378 * 379 * Returned value: 380 * handle on audio hardware output 381 */ 382 audio_io_handle_t getOutput(); 383 384 /* Returns the unique session ID associated with this track. 385 * 386 * Parameters: 387 * none. 388 * 389 * Returned value: 390 * AudioTrack session ID. 391 */ 392 int getSessionId() const; 393 394 /* Attach track auxiliary output to specified effect. Use effectId = 0 395 * to detach track from effect. 396 * 397 * Parameters: 398 * 399 * effectId: effectId obtained from AudioEffect::id(). 400 * 401 * Returned status (from utils/Errors.h) can be: 402 * - NO_ERROR: successful operation 403 * - INVALID_OPERATION: the effect is not an auxiliary effect. 404 * - BAD_VALUE: The specified effect ID is invalid 405 */ 406 status_t attachAuxEffect(int effectId); 407 408 /* Obtains a buffer of "frameCount" frames. The buffer must be 409 * filled entirely, and then released with releaseBuffer(). 410 * If the track is stopped, obtainBuffer() returns 411 * STOPPED instead of NO_ERROR as long as there are buffers available, 412 * at which point NO_MORE_BUFFERS is returned. 413 * Buffers will be returned until the pool (buffercount()) 414 * is exhausted, at which point obtainBuffer() will either block 415 * or return WOULD_BLOCK depending on the value of the "blocking" 416 * parameter. 417 * 418 * Interpretation of waitCount: 419 * +n limits wait time to n * WAIT_PERIOD_MS, 420 * -1 causes an (almost) infinite wait time, 421 * 0 non-blocking. 422 */ 423 424 enum { 425 NO_MORE_BUFFERS = 0x80000001, // same name in AudioFlinger.h, ok to be different value 426 STOPPED = 1 427 }; 428 429 status_t obtainBuffer(Buffer* audioBuffer, int32_t waitCount); 430 431 /* Release a filled buffer of "frameCount" frames for AudioFlinger to process. */ 432 void releaseBuffer(Buffer* audioBuffer); 433 434 /* As a convenience we provide a write() interface to the audio buffer. 435 * This is implemented on top of obtainBuffer/releaseBuffer. For best 436 * performance use callbacks. Returns actual number of bytes written >= 0, 437 * or one of the following negative status codes: 438 * INVALID_OPERATION AudioTrack is configured for shared buffer mode 439 * BAD_VALUE size is invalid 440 * STOPPED AudioTrack was stopped during the write 441 * NO_MORE_BUFFERS when obtainBuffer() returns same 442 * or any other error code returned by IAudioTrack::start() or restoreTrack_l(). 443 */ 444 ssize_t write(const void* buffer, size_t size); 445 446 /* 447 * Dumps the state of an audio track. 448 */ 449 status_t dump(int fd, const Vector<String16>& args) const; 450 451protected: 452 /* copying audio tracks is not allowed */ 453 AudioTrack(const AudioTrack& other); 454 AudioTrack& operator = (const AudioTrack& other); 455 456 /* a small internal class to handle the callback */ 457 class AudioTrackThread : public Thread 458 { 459 public: 460 AudioTrackThread(AudioTrack& receiver, bool bCanCallJava = false); 461 private: 462 friend class AudioTrack; 463 virtual bool threadLoop(); 464 virtual status_t readyToRun(); 465 virtual void onFirstRef(); 466 AudioTrack& mReceiver; 467 }; 468 469 // body of AudioTrackThread::threadLoop() 470 bool processAudioBuffer(const sp<AudioTrackThread>& thread); 471 472 status_t createTrack_l(audio_stream_type_t streamType, 473 uint32_t sampleRate, 474 audio_format_t format, 475 uint32_t channelMask, 476 int frameCount, 477 audio_policy_output_flags_t flags, 478 const sp<IMemory>& sharedBuffer, 479 audio_io_handle_t output); 480 void flush_l(); 481 status_t setLoop_l(uint32_t loopStart, uint32_t loopEnd, int loopCount); 482 audio_io_handle_t getOutput_l(); 483 status_t restoreTrack_l(audio_track_cblk_t*& cblk, bool fromStart); 484 bool stopped_l() const { return !mActive; } 485 486 sp<IAudioTrack> mAudioTrack; 487 sp<IMemory> mCblkMemory; 488 sp<AudioTrackThread> mAudioTrackThread; 489 490 float mVolume[2]; 491 float mSendLevel; 492 uint32_t mFrameCount; 493 494 audio_track_cblk_t* mCblk; 495 audio_format_t mFormat; 496 audio_stream_type_t mStreamType; 497 uint8_t mChannelCount; 498 uint8_t mMuted; 499 uint8_t mReserved; 500 uint32_t mChannelMask; 501 status_t mStatus; 502 uint32_t mLatency; 503 504 bool mActive; // protected by mLock 505 506 callback_t mCbf; // callback handler for events, or NULL 507 void* mUserData; 508 uint32_t mNotificationFramesReq; // requested number of frames between each notification callback 509 uint32_t mNotificationFramesAct; // actual number of frames between each notification callback 510 sp<IMemory> mSharedBuffer; 511 int mLoopCount; 512 uint32_t mRemainingFrames; 513 uint32_t mMarkerPosition; 514 bool mMarkerReached; 515 uint32_t mNewPosition; 516 uint32_t mUpdatePeriod; 517 bool mFlushed; // FIXME will be made obsolete by making flush() synchronous 518 audio_policy_output_flags_t mFlags; 519 int mSessionId; 520 int mAuxEffectId; 521 mutable Mutex mLock; 522 status_t mRestoreStatus; 523 bool mIsTimed; 524 int mPreviousPriority; // before start() 525 int mPreviousSchedulingGroup; 526}; 527 528class TimedAudioTrack : public AudioTrack 529{ 530public: 531 TimedAudioTrack(); 532 533 /* allocate a shared memory buffer that can be passed to queueTimedBuffer */ 534 status_t allocateTimedBuffer(size_t size, sp<IMemory>* buffer); 535 536 /* queue a buffer obtained via allocateTimedBuffer for playback at the 537 given timestamp. PTS units a microseconds on the media time timeline. 538 The media time transform (set with setMediaTimeTransform) set by the 539 audio producer will handle converting from media time to local time 540 (perhaps going through the common time timeline in the case of 541 synchronized multiroom audio case) */ 542 status_t queueTimedBuffer(const sp<IMemory>& buffer, int64_t pts); 543 544 /* define a transform between media time and either common time or 545 local time */ 546 enum TargetTimeline {LOCAL_TIME, COMMON_TIME}; 547 status_t setMediaTimeTransform(const LinearTransform& xform, 548 TargetTimeline target); 549}; 550 551}; // namespace android 552 553#endif // ANDROID_AUDIOTRACK_H 554