AudioTrack.h revision 2729ea9262ca60d93047e984739887cfc89e82eb
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 <utils/IInterface.h> 30#include <utils/IMemory.h> 31#include <utils/threads.h> 32 33 34namespace android { 35 36// ---------------------------------------------------------------------------- 37 38class audio_track_cblk_t; 39 40// ---------------------------------------------------------------------------- 41 42class AudioTrack 43{ 44public: 45 46 enum stream_type { 47 DEFAULT =-1, 48 VOICE_CALL = 0, 49 SYSTEM = 1, 50 RING = 2, 51 MUSIC = 3, 52 ALARM = 4, 53 NUM_STREAM_TYPES 54 }; 55 56 enum channel_index { 57 MONO = 0, 58 LEFT = 0, 59 RIGHT = 1 60 }; 61 62 /* Create Buffer on the stack and pass it to obtainBuffer() 63 * and releaseBuffer(). 64 */ 65 66 class Buffer 67 { 68 public: 69 enum { 70 MUTE = 0x00000001 71 }; 72 uint32_t flags; 73 int channelCount; 74 int format; 75 size_t frameCount; 76 size_t size; 77 union { 78 void* raw; 79 short* i16; 80 int8_t* i8; 81 }; 82 }; 83 84 /* Returns AudioFlinger's frame count. AudioTrack's buffers will 85 * be created with this size. 86 */ 87 static size_t frameCount(); 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 availlable. 92 */ 93 typedef void (*callback_t)(void* user, const Buffer& info); 94 95 /* Constructs an uninitialized AudioTrack. No connection with 96 * AudioFlinger takes place. 97 */ 98 AudioTrack(); 99 100 /* Creates an audio track and registers it with AudioFlinger. 101 * Once created, the track needs to be started before it can be used. 102 * Unspecified values are set to the audio hardware's current 103 * values. 104 */ 105 106 AudioTrack( int streamType, 107 uint32_t sampleRate = 0, 108 int format = 0, 109 int channelCount = 0, 110 int bufferCount = 0, 111 uint32_t flags = 0, 112 callback_t cbf = 0, void* user = 0); 113 114 115 /* Terminates the AudioTrack and unregisters it from AudioFlinger. 116 * Also destroys all resources assotiated with the AudioTrack. 117 */ 118 ~AudioTrack(); 119 120 121 /* Initialize an uninitialized AudioTrack. */ 122 status_t set(int streamType =-1, 123 uint32_t sampleRate = 0, 124 int format = 0, 125 int channelCount = 0, 126 int bufferCount = 0, 127 uint32_t flags = 0, 128 callback_t cbf = 0, void* user = 0); 129 130 131 /* Result of constructing the AudioTrack. This must be checked 132 * before using any AudioTrack API (except for set()), using 133 * an uninitialized AudoiTrack prduces undefined results. 134 */ 135 status_t initCheck() const; 136 137 /* Returns this track's latency in nanoseconds or framecount. 138 * This only includes the latency due to the fill buffer size. 139 * In particular, the hardware or driver latencies are not accounted. 140 */ 141 nsecs_t latency() const; 142 143 /* getters, see constructor */ 144 145 int streamType() const; 146 uint32_t sampleRate() const; 147 int format() const; 148 int channelCount() const; 149 int bufferCount() const; 150 151 152 /* After it's created the track is not active. Call start() to 153 * make it active. If set, the callback will start being called. 154 */ 155 void start(); 156 157 /* Stop a track. If set, the callback will cease being called and 158 * obtainBuffer returns STOPPED. Note that obtainBuffer() still works 159 * and will fill up buffers until the pool is exhausted. 160 */ 161 void stop(); 162 bool stopped() const; 163 164 /* flush a stopped track. All pending buffers are discarded. 165 * This function has no effect if the track is not stoped. 166 */ 167 void flush(); 168 169 /* Pause a track. If set, the callback will cease being called and 170 * obtainBuffer returns STOPPED. Note that obtainBuffer() still works 171 * and will fill up buffers until the pool is exhausted. 172 */ 173 void pause(); 174 175 /* mute or unmutes this track. 176 * While mutted, the callback, if set, is still called. 177 */ 178 void mute(bool); 179 bool muted() const; 180 181 182 /* set volume for this track, mostly used for games' sound effects 183 */ 184 void setVolume(float left, float right); 185 void getVolume(float* left, float* right); 186 187 /* set sample rate for this track, mostly used for games' sound effects 188 */ 189 void setSampleRate(int sampleRate); 190 uint32_t getSampleRate(); 191 192 /* obtains a buffer of "frameCount" frames. The buffer must be 193 * filled entirely. If the track is stopped, obtainBuffer() returns 194 * STOPPED instead of NO_ERROR as long as there are buffers availlable, 195 * at which point NO_MORE_BUFFERS is returned. 196 * Buffers will be returned until the pool (buffercount()) 197 * is exhausted, at which point obtainBuffer() will either block 198 * or return WOULD_BLOCK depending on the value of the "blocking" 199 * parameter. 200 */ 201 202 enum { 203 NO_MORE_BUFFERS = 0x80000001, 204 STOPPED = 1 205 }; 206 207 status_t obtainBuffer(Buffer* audioBuffer, bool blocking); 208 void releaseBuffer(Buffer* audioBuffer); 209 210 211 /* As a convenience we provide a write() interface to the audio buffer. 212 * This is implemented on top of lockBuffer/unlockBuffer. For best 213 * performance 214 * 215 */ 216 ssize_t write(const void* buffer, size_t size); 217 218 /* 219 * Dumps the state of an audio track. 220 */ 221 status_t dump(int fd, const Vector<String16>& args) const; 222 223private: 224 /* copying audio tracks is not allowed */ 225 AudioTrack(const AudioTrack& other); 226 AudioTrack& operator = (const AudioTrack& other); 227 228 /* a small internal class to handle the callback */ 229 class AudioTrackThread : public Thread 230 { 231 public: 232 AudioTrackThread(AudioTrack& receiver); 233 private: 234 friend class AudioTrack; 235 virtual bool threadLoop(); 236 virtual status_t readyToRun(); 237 virtual void onFirstRef(); 238 AudioTrack& mReceiver; 239 Mutex mLock; 240 }; 241 242 bool processAudioBuffer(const sp<AudioTrackThread>& thread); 243 244 sp<IAudioFlinger> mAudioFlinger; 245 sp<IAudioTrack> mAudioTrack; 246 sp<IMemory> mCblkMemory; 247 sp<AudioTrackThread> mAudioTrackThread; 248 249 float mVolume[2]; 250 uint32_t mSampleRate; 251 size_t mFrameCount; 252 253 audio_track_cblk_t* mCblk; 254 uint8_t mStreamType; 255 uint8_t mFormat; 256 uint8_t mBufferCount; 257 uint8_t mChannelCount : 4; 258 uint8_t mMuted : 1; 259 uint8_t mReserved : 2; 260 status_t mStatus; 261 nsecs_t mLatency; 262 263 volatile int32_t mActive; 264 265 callback_t mCbf; 266 void* mUserData; 267 268 AudioTrack::Buffer mAudioBuffer; 269 size_t mPosition; 270 271 uint32_t mReservedFBC[4]; 272}; 273 274 275}; // namespace android 276 277#endif // ANDROID_AUDIOTRACK_H 278