AudioTrack.h revision 4ff14bae91075eb274eb1c2975982358946e7e63
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: Total size of track PCM buffer in frames. This defines the 139 * latency of the track. 140 * flags: Reserved for future use. 141 * cbf: Callback function. If not null, this function is called periodically 142 * to request new PCM data. 143 * user: Context for use by the callback receiver. 144 * notificationFrames: The callback function is called each time notificationFrames PCM 145 * frames have been consumed from track input buffer. 146 * sessionId: Specific session ID, or zero to use default. 147 */ 148 149 AudioTrack( audio_stream_type_t streamType, 150 uint32_t sampleRate = 0, 151 audio_format_t format = AUDIO_FORMAT_DEFAULT, 152 int channelMask = 0, 153 int frameCount = 0, 154 uint32_t flags = 0, 155 callback_t cbf = NULL, 156 void* user = NULL, 157 int notificationFrames = 0, 158 int sessionId = 0); 159 160 // DEPRECATED 161 explicit AudioTrack( int streamType, 162 uint32_t sampleRate = 0, 163 int format = AUDIO_FORMAT_DEFAULT, 164 int channelMask = 0, 165 int frameCount = 0, 166 uint32_t flags = 0, 167 callback_t cbf = 0, 168 void* user = 0, 169 int notificationFrames = 0, 170 int sessionId = 0); 171 172 /* Creates an audio track and registers it with AudioFlinger. With this constructor, 173 * the PCM data to be rendered by AudioTrack is passed in a shared memory buffer 174 * identified by the argument sharedBuffer. This prototype is for static buffer playback. 175 * PCM data must be present in memory before the AudioTrack is started. 176 * The write() and flush() methods are not supported in this case. 177 * It is recommended to pass a callback function to be notified of playback end by an 178 * EVENT_UNDERRUN event. 179 */ 180 181 AudioTrack( audio_stream_type_t streamType, 182 uint32_t sampleRate = 0, 183 audio_format_t format = AUDIO_FORMAT_DEFAULT, 184 int channelMask = 0, 185 const sp<IMemory>& sharedBuffer = 0, 186 uint32_t flags = 0, 187 callback_t cbf = NULL, 188 void* user = NULL, 189 int notificationFrames = 0, 190 int sessionId = 0); 191 192 /* Terminates the AudioTrack and unregisters it from AudioFlinger. 193 * Also destroys all resources associated with the AudioTrack. 194 */ 195 ~AudioTrack(); 196 197 198 /* Initialize an uninitialized AudioTrack. 199 * Returned status (from utils/Errors.h) can be: 200 * - NO_ERROR: successful initialization 201 * - INVALID_OPERATION: AudioTrack is already initialized 202 * - BAD_VALUE: invalid parameter (channels, format, sampleRate...) 203 * - NO_INIT: audio server or audio hardware not initialized 204 * */ 205 status_t set(audio_stream_type_t streamType = AUDIO_STREAM_DEFAULT, 206 uint32_t sampleRate = 0, 207 audio_format_t format = AUDIO_FORMAT_DEFAULT, 208 int channelMask = 0, 209 int frameCount = 0, 210 uint32_t flags = 0, 211 callback_t cbf = NULL, 212 void* user = NULL, 213 int notificationFrames = 0, 214 const sp<IMemory>& sharedBuffer = 0, 215 bool threadCanCallJava = false, 216 int sessionId = 0); 217 218 219 /* Result of constructing the AudioTrack. This must be checked 220 * before using any AudioTrack API (except for set()), because using 221 * an uninitialized AudioTrack produces undefined results. 222 * See set() method above for possible return codes. 223 */ 224 status_t initCheck() const; 225 226 /* Returns this track's estimated latency in milliseconds. 227 * This includes the latency due to AudioTrack buffer size, AudioMixer (if any) 228 * and audio hardware driver. 229 */ 230 uint32_t latency() const; 231 232 /* getters, see constructors and set() */ 233 234 audio_stream_type_t streamType() const; 235 audio_format_t format() const; 236 int channelCount() const; 237 uint32_t frameCount() const; 238 239 /* Return channelCount * (bit depth per channel / 8). 240 * channelCount is determined from channelMask, and bit depth comes from format. 241 */ 242 size_t frameSize() const; 243 244 sp<IMemory>& sharedBuffer(); 245 246 247 /* After it's created the track is not active. Call start() to 248 * make it active. If set, the callback will start being called. 249 */ 250 void start(); 251 252 /* Stop a track. If set, the callback will cease being called and 253 * obtainBuffer returns STOPPED. Note that obtainBuffer() still works 254 * and will fill up buffers until the pool is exhausted. 255 */ 256 void stop(); 257 bool stopped() const; 258 259 /* Flush a stopped track. All pending buffers are discarded. 260 * This function has no effect if the track is not stopped. 261 */ 262 void flush(); 263 264 /* Pause a track. If set, the callback will cease being called and 265 * obtainBuffer returns STOPPED. Note that obtainBuffer() still works 266 * and will fill up buffers until the pool is exhausted. 267 */ 268 void pause(); 269 270 /* Mute or unmute this track. 271 * While muted, the callback, if set, is still called. 272 */ 273 void mute(bool); 274 bool muted() const; 275 276 /* Set volume for this track, mostly used for games' sound effects 277 * left and right volumes. Levels must be >= 0.0 and <= 1.0. 278 */ 279 status_t setVolume(float left, float right); 280 void getVolume(float* left, float* right) const; 281 282 /* Set the send level for this track. An auxiliary effect should be attached 283 * to the track with attachEffect(). Level must be >= 0.0 and <= 1.0. 284 */ 285 status_t setAuxEffectSendLevel(float level); 286 void getAuxEffectSendLevel(float* level) const; 287 288 /* Set sample rate for this track, mostly used for games' sound effects 289 */ 290 status_t setSampleRate(int sampleRate); 291 uint32_t getSampleRate() const; 292 293 /* Enables looping and sets the start and end points of looping. 294 * 295 * Parameters: 296 * 297 * loopStart: loop start expressed as the number of PCM frames played since AudioTrack start. 298 * loopEnd: loop end expressed as the number of PCM frames played since AudioTrack start. 299 * loopCount: number of loops to execute. Calling setLoop() with loopCount == 0 cancels any 300 * pending or active loop. loopCount = -1 means infinite looping. 301 * 302 * For proper operation the following condition must be respected: 303 * (loopEnd-loopStart) <= framecount() 304 */ 305 status_t setLoop(uint32_t loopStart, uint32_t loopEnd, int loopCount); 306 307 /* Sets marker position. When playback reaches the number of frames specified, a callback with 308 * event type EVENT_MARKER is called. Calling setMarkerPosition with marker == 0 cancels marker 309 * notification callback. 310 * If the AudioTrack has been opened with no callback function associated, the operation will fail. 311 * 312 * Parameters: 313 * 314 * marker: marker position expressed in frames. 315 * 316 * Returned status (from utils/Errors.h) can be: 317 * - NO_ERROR: successful operation 318 * - INVALID_OPERATION: the AudioTrack has no callback installed. 319 */ 320 status_t setMarkerPosition(uint32_t marker); 321 status_t getMarkerPosition(uint32_t *marker) const; 322 323 324 /* Sets position update period. Every time the number of frames specified has been played, 325 * a callback with event type EVENT_NEW_POS is called. 326 * Calling setPositionUpdatePeriod with updatePeriod == 0 cancels new position notification 327 * callback. 328 * If the AudioTrack has been opened with no callback function associated, the operation will fail. 329 * 330 * Parameters: 331 * 332 * updatePeriod: position update notification period expressed in frames. 333 * 334 * Returned status (from utils/Errors.h) can be: 335 * - NO_ERROR: successful operation 336 * - INVALID_OPERATION: the AudioTrack has no callback installed. 337 */ 338 status_t setPositionUpdatePeriod(uint32_t updatePeriod); 339 status_t getPositionUpdatePeriod(uint32_t *updatePeriod) const; 340 341 /* Sets playback head position within AudioTrack buffer. The new position is specified 342 * in number of frames. 343 * This method must be called with the AudioTrack in paused or stopped state. 344 * Note that the actual position set is <position> modulo the AudioTrack buffer size in frames. 345 * Therefore using this method makes sense only when playing a "static" audio buffer 346 * as opposed to streaming. 347 * The getPosition() method on the other hand returns the total number of frames played since 348 * playback start. 349 * 350 * Parameters: 351 * 352 * position: New playback head position within AudioTrack buffer. 353 * 354 * Returned status (from utils/Errors.h) can be: 355 * - NO_ERROR: successful operation 356 * - INVALID_OPERATION: the AudioTrack is not stopped. 357 * - BAD_VALUE: The specified position is beyond the number of frames present in AudioTrack buffer 358 */ 359 status_t setPosition(uint32_t position); 360 status_t getPosition(uint32_t *position); 361 362 /* Forces AudioTrack buffer full condition. When playing a static buffer, this method avoids 363 * rewriting the buffer before restarting playback after a stop. 364 * This method must be called with the AudioTrack in paused or stopped state. 365 * 366 * Returned status (from utils/Errors.h) can be: 367 * - NO_ERROR: successful operation 368 * - INVALID_OPERATION: the AudioTrack is not stopped. 369 */ 370 status_t reload(); 371 372 /* Returns a handle on the audio output used by this AudioTrack. 373 * 374 * Parameters: 375 * none. 376 * 377 * Returned value: 378 * handle on audio hardware output 379 */ 380 audio_io_handle_t getOutput(); 381 382 /* Returns the unique session ID associated with this track. 383 * 384 * Parameters: 385 * none. 386 * 387 * Returned value: 388 * AudioTrack session ID. 389 */ 390 int getSessionId() const; 391 392 /* Attach track auxiliary output to specified effect. Use effectId = 0 393 * to detach track from effect. 394 * 395 * Parameters: 396 * 397 * effectId: effectId obtained from AudioEffect::id(). 398 * 399 * Returned status (from utils/Errors.h) can be: 400 * - NO_ERROR: successful operation 401 * - INVALID_OPERATION: the effect is not an auxiliary effect. 402 * - BAD_VALUE: The specified effect ID is invalid 403 */ 404 status_t attachAuxEffect(int effectId); 405 406 /* Obtains a buffer of "frameCount" frames. The buffer must be 407 * filled entirely, and then released with releaseBuffer(). 408 * If the track is stopped, obtainBuffer() returns 409 * STOPPED instead of NO_ERROR as long as there are buffers available, 410 * at which point NO_MORE_BUFFERS is returned. 411 * Buffers will be returned until the pool (buffercount()) 412 * is exhausted, at which point obtainBuffer() will either block 413 * or return WOULD_BLOCK depending on the value of the "blocking" 414 * parameter. 415 * 416 * Interpretation of waitCount: 417 * +n limits wait time to n * WAIT_PERIOD_MS, 418 * -1 causes an (almost) infinite wait time, 419 * 0 non-blocking. 420 */ 421 422 enum { 423 NO_MORE_BUFFERS = 0x80000001, // same name in AudioFlinger.h, ok to be different value 424 STOPPED = 1 425 }; 426 427 status_t obtainBuffer(Buffer* audioBuffer, int32_t waitCount); 428 429 /* Release a filled buffer of "frameCount" frames for AudioFlinger to process. */ 430 void releaseBuffer(Buffer* audioBuffer); 431 432 /* As a convenience we provide a write() interface to the audio buffer. 433 * This is implemented on top of obtainBuffer/releaseBuffer. For best 434 * performance use callbacks. Returns actual number of bytes written >= 0, 435 * or one of the following negative status codes: 436 * INVALID_OPERATION AudioTrack is configured for shared buffer mode 437 * BAD_VALUE size is invalid 438 * STOPPED AudioTrack was stopped during the write 439 * NO_MORE_BUFFERS when obtainBuffer() returns same 440 * or any other error code returned by IAudioTrack::start() or restoreTrack_l(). 441 */ 442 ssize_t write(const void* buffer, size_t size); 443 444 /* 445 * Dumps the state of an audio track. 446 */ 447 status_t dump(int fd, const Vector<String16>& args) const; 448 449protected: 450 /* copying audio tracks is not allowed */ 451 AudioTrack(const AudioTrack& other); 452 AudioTrack& operator = (const AudioTrack& other); 453 454 /* a small internal class to handle the callback */ 455 class AudioTrackThread : public Thread 456 { 457 public: 458 AudioTrackThread(AudioTrack& receiver, bool bCanCallJava = false); 459 private: 460 friend class AudioTrack; 461 virtual bool threadLoop(); 462 virtual status_t readyToRun(); 463 virtual void onFirstRef(); 464 AudioTrack& mReceiver; 465 }; 466 467 // body of AudioTrackThread::threadLoop() 468 bool processAudioBuffer(const sp<AudioTrackThread>& thread); 469 status_t createTrack_l(audio_stream_type_t streamType, 470 uint32_t sampleRate, 471 audio_format_t format, 472 uint32_t channelMask, 473 int frameCount, 474 uint32_t flags, 475 const sp<IMemory>& sharedBuffer, 476 audio_io_handle_t output, 477 bool enforceFrameCount); 478 void flush_l(); 479 status_t setLoop_l(uint32_t loopStart, uint32_t loopEnd, int loopCount); 480 audio_io_handle_t getOutput_l(); 481 status_t restoreTrack_l(audio_track_cblk_t*& cblk, bool fromStart); 482 bool stopped_l() const { return !mActive; } 483 484 sp<IAudioTrack> mAudioTrack; 485 sp<IMemory> mCblkMemory; 486 sp<AudioTrackThread> mAudioTrackThread; 487 488 float mVolume[2]; 489 float mSendLevel; 490 uint32_t mFrameCount; 491 492 audio_track_cblk_t* mCblk; 493 audio_format_t mFormat; 494 audio_stream_type_t mStreamType; 495 uint8_t mChannelCount; 496 uint8_t mMuted; 497 uint8_t mReserved; 498 uint32_t mChannelMask; 499 status_t mStatus; 500 uint32_t mLatency; 501 502 bool mActive; // protected by mLock 503 504 callback_t mCbf; // callback handler for events, or NULL 505 void* mUserData; 506 uint32_t mNotificationFramesReq; // requested number of frames between each notification callback 507 uint32_t mNotificationFramesAct; // actual number of frames between each notification callback 508 sp<IMemory> mSharedBuffer; 509 int mLoopCount; 510 uint32_t mRemainingFrames; 511 uint32_t mMarkerPosition; 512 bool mMarkerReached; 513 uint32_t mNewPosition; 514 uint32_t mUpdatePeriod; 515 bool mFlushed; // FIXME will be made obsolete by making flush() synchronous 516 uint32_t mFlags; 517 int mSessionId; 518 int mAuxEffectId; 519 mutable Mutex mLock; 520 status_t mRestoreStatus; 521 bool mIsTimed; 522 int mPreviousPriority; // before start() 523 int mPreviousSchedulingGroup; 524}; 525 526class TimedAudioTrack : public AudioTrack 527{ 528public: 529 TimedAudioTrack(); 530 531 /* allocate a shared memory buffer that can be passed to queueTimedBuffer */ 532 status_t allocateTimedBuffer(size_t size, sp<IMemory>* buffer); 533 534 /* queue a buffer obtained via allocateTimedBuffer for playback at the 535 given timestamp. PTS units a microseconds on the media time timeline. 536 The media time transform (set with setMediaTimeTransform) set by the 537 audio producer will handle converting from media time to local time 538 (perhaps going through the common time timeline in the case of 539 synchronized multiroom audio case) */ 540 status_t queueTimedBuffer(const sp<IMemory>& buffer, int64_t pts); 541 542 /* define a transform between media time and either common time or 543 local time */ 544 enum TargetTimeline {LOCAL_TIME, COMMON_TIME}; 545 status_t setMediaTimeTransform(const LinearTransform& xform, 546 TargetTimeline target); 547}; 548 549}; // namespace android 550 551#endif // ANDROID_AUDIOTRACK_H 552