blob: 5ba8461b18226045dbd423b26350bb50db862b39 [file] [log] [blame]
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -08001/*
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
Glenn Kastena6364332012-04-19 09:35:04 -070020#include <cutils/sched_policy.h>
Glenn Kasten9f80dd22012-12-18 15:57:32 -080021#include <media/AudioSystem.h>
22#include <media/IAudioTrack.h>
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -080023#include <utils/threads.h>
24
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -080025namespace android {
26
27// ----------------------------------------------------------------------------
28
29class audio_track_cblk_t;
Glenn Kastene3aa6592012-12-04 12:22:46 -080030class AudioTrackClientProxy;
Glenn Kasten9f80dd22012-12-18 15:57:32 -080031class StaticAudioTrackClientProxy;
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -080032
33// ----------------------------------------------------------------------------
34
Glenn Kasten9f80dd22012-12-18 15:57:32 -080035class AudioTrack : public RefBase
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -080036{
37public:
38 enum channel_index {
39 MONO = 0,
40 LEFT = 0,
41 RIGHT = 1
42 };
43
Glenn Kasten9f80dd22012-12-18 15:57:32 -080044 /* Events used by AudioTrack callback function (callback_t).
Glenn Kastenad2f6db2012-11-01 15:45:06 -070045 * Keep in sync with frameworks/base/media/java/android/media/AudioTrack.java NATIVE_EVENT_*.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -080046 */
47 enum event_type {
Glenn Kasten083d1c12012-11-30 15:00:36 -080048 EVENT_MORE_DATA = 0, // Request to write more data to buffer.
49 // If this event is delivered but the callback handler
50 // does not want to write more data, the handler must explicitly
51 // ignore the event by setting frameCount to zero.
52 EVENT_UNDERRUN = 1, // Buffer underrun occurred.
Glenn Kasten85ab62c2012-11-01 11:11:38 -070053 EVENT_LOOP_END = 2, // Sample loop end was reached; playback restarted from
54 // loop start if loop count was not 0.
55 EVENT_MARKER = 3, // Playback head is at the specified marker position
56 // (See setMarkerPosition()).
57 EVENT_NEW_POS = 4, // Playback head is at a new position
58 // (See setPositionUpdatePeriod()).
Glenn Kasten9f80dd22012-12-18 15:57:32 -080059 EVENT_BUFFER_END = 5, // Playback head is at the end of the buffer.
60 // Not currently used by android.media.AudioTrack.
61 EVENT_NEW_IAUDIOTRACK = 6, // IAudioTrack was re-created, either due to re-routing and
62 // voluntary invalidation by mediaserver, or mediaserver crash.
Richard Fitzgeraldad3af332013-03-25 16:54:37 +000063 EVENT_STREAM_END = 7, // Sent after all the buffers queued in AF and HW are played
64 // back (after stop is called)
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -080065 };
66
Glenn Kasten99e53b82012-01-19 08:59:58 -080067 /* Client should declare Buffer on the stack and pass address to obtainBuffer()
68 * and releaseBuffer(). See also callback_t for EVENT_MORE_DATA.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -080069 */
70
71 class Buffer
72 {
73 public:
Glenn Kasten9f80dd22012-12-18 15:57:32 -080074 // FIXME use m prefix
Glenn Kasten99e53b82012-01-19 08:59:58 -080075 size_t frameCount; // number of sample frames corresponding to size;
76 // on input it is the number of frames desired,
77 // on output is the number of frames actually filled
Glenn Kastenfb1fdc92013-07-10 17:03:19 -070078 // (currently ignored, but will make the primary field in future)
Glenn Kasten99e53b82012-01-19 08:59:58 -080079
Glenn Kasten9f80dd22012-12-18 15:57:32 -080080 size_t size; // input/output in bytes == frameCount * frameSize
Glenn Kastenfb1fdc92013-07-10 17:03:19 -070081 // on output is the number of bytes actually filled
Glenn Kasten9f80dd22012-12-18 15:57:32 -080082 // FIXME this is redundant with respect to frameCount,
83 // and TRANSFER_OBTAIN mode is broken for 8-bit data
84 // since we don't define the frame format
85
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -080086 union {
87 void* raw;
Glenn Kasten9f80dd22012-12-18 15:57:32 -080088 short* i16; // signed 16-bit
89 int8_t* i8; // unsigned 8-bit, offset by 0x80
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -080090 };
91 };
92
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -080093 /* As a convenience, if a callback is supplied, a handler thread
94 * is automatically created with the appropriate priority. This thread
Glenn Kasten99e53b82012-01-19 08:59:58 -080095 * invokes the callback when a new buffer becomes available or various conditions occur.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -080096 * Parameters:
97 *
98 * event: type of event notified (see enum AudioTrack::event_type).
99 * user: Pointer to context for use by the callback receiver.
100 * info: Pointer to optional parameter according to event type:
101 * - EVENT_MORE_DATA: pointer to AudioTrack::Buffer struct. The callback must not write
Glenn Kasten99e53b82012-01-19 08:59:58 -0800102 * more bytes than indicated by 'size' field and update 'size' if fewer bytes are
103 * written.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800104 * - EVENT_UNDERRUN: unused.
105 * - EVENT_LOOP_END: pointer to an int indicating the number of loops remaining.
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800106 * - EVENT_MARKER: pointer to const uint32_t containing the marker position in frames.
107 * - EVENT_NEW_POS: pointer to const uint32_t containing the new position in frames.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800108 * - EVENT_BUFFER_END: unused.
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800109 * - EVENT_NEW_IAUDIOTRACK: unused.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800110 */
111
Glenn Kastend217a8c2011-06-01 15:20:35 -0700112 typedef void (*callback_t)(int event, void* user, void *info);
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800113
Chia-chi Yeh33005a92010-06-16 06:33:13 +0800114 /* Returns the minimum frame count required for the successful creation of
115 * an AudioTrack object.
116 * Returned status (from utils/Errors.h) can be:
117 * - NO_ERROR: successful operation
118 * - NO_INIT: audio server or audio hardware not initialized
119 */
120
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800121 static status_t getMinFrameCount(size_t* frameCount,
122 audio_stream_type_t streamType,
123 uint32_t sampleRate);
124
125 /* How data is transferred to AudioTrack
126 */
127 enum transfer_type {
128 TRANSFER_DEFAULT, // not specified explicitly; determine from the other parameters
129 TRANSFER_CALLBACK, // callback EVENT_MORE_DATA
130 TRANSFER_OBTAIN, // FIXME deprecated: call obtainBuffer() and releaseBuffer()
131 TRANSFER_SYNC, // synchronous write()
132 TRANSFER_SHARED, // shared memory
133 };
Chia-chi Yeh33005a92010-06-16 06:33:13 +0800134
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800135 /* Constructs an uninitialized AudioTrack. No connection with
Glenn Kasten083d1c12012-11-30 15:00:36 -0800136 * AudioFlinger takes place. Use set() after this.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800137 */
138 AudioTrack();
139
Glenn Kastenad2f6db2012-11-01 15:45:06 -0700140 /* Creates an AudioTrack object and registers it with AudioFlinger.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800141 * Once created, the track needs to be started before it can be used.
Glenn Kasten083d1c12012-11-30 15:00:36 -0800142 * Unspecified values are set to appropriate default values.
143 * With this constructor, the track is configured for streaming mode.
144 * Data to be rendered is supplied by write() or by the callback EVENT_MORE_DATA.
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800145 * Intermixing a combination of write() and non-ignored EVENT_MORE_DATA is not allowed.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800146 *
147 * Parameters:
148 *
149 * streamType: Select the type of audio stream this track is attached to
Dima Zavinfce7a472011-04-19 22:30:36 -0700150 * (e.g. AUDIO_STREAM_MUSIC).
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800151 * sampleRate: Data source sampling rate in Hz.
Dima Zavinfce7a472011-04-19 22:30:36 -0700152 * format: Audio format (e.g AUDIO_FORMAT_PCM_16_BIT for signed
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800153 * 16 bits per sample).
Glenn Kasten28b76b32012-07-03 17:24:41 -0700154 * channelMask: Channel mask.
Eric Laurentd8d61852012-03-05 17:06:40 -0800155 * frameCount: Minimum size of track PCM buffer in frames. This defines the
Glenn Kastenad2f6db2012-11-01 15:45:06 -0700156 * application's contribution to the
Eric Laurentd8d61852012-03-05 17:06:40 -0800157 * latency of the track. The actual size selected by the AudioTrack could be
158 * larger if the requested size is not compatible with current audio HAL
Glenn Kasten083d1c12012-11-30 15:00:36 -0800159 * configuration. Zero means to use a default value.
Eric Laurent0ca3cf92012-04-18 09:24:29 -0700160 * flags: See comments on audio_output_flags_t in <system/audio.h>.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800161 * cbf: Callback function. If not null, this function is called periodically
Glenn Kasten083d1c12012-11-30 15:00:36 -0800162 * to provide new data and inform of marker, position updates, etc.
Glenn Kasten362c4e62011-12-14 10:28:06 -0800163 * user: Context for use by the callback receiver.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800164 * notificationFrames: The callback function is called each time notificationFrames PCM
Glenn Kasten362c4e62011-12-14 10:28:06 -0800165 * frames have been consumed from track input buffer.
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800166 * This is expressed in units of frames at the initial source sample rate.
Glenn Kasten362c4e62011-12-14 10:28:06 -0800167 * sessionId: Specific session ID, or zero to use default.
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800168 * transferType: How data is transferred to AudioTrack.
169 * threadCanCallJava: Not present in parameter list, and so is fixed at false.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800170 */
171
Glenn Kastenfff6d712012-01-12 16:38:12 -0800172 AudioTrack( audio_stream_type_t streamType,
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800173 uint32_t sampleRate = 0,
Glenn Kastene1c39622012-01-04 09:36:37 -0800174 audio_format_t format = AUDIO_FORMAT_DEFAULT,
Glenn Kasten28b76b32012-07-03 17:24:41 -0700175 audio_channel_mask_t channelMask = 0,
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800176 int frameCount = 0,
Eric Laurent0ca3cf92012-04-18 09:24:29 -0700177 audio_output_flags_t flags = AUDIO_OUTPUT_FLAG_NONE,
Glenn Kastena0d68332012-01-27 16:47:15 -0800178 callback_t cbf = NULL,
179 void* user = NULL,
Eric Laurentbe916aa2010-06-01 23:49:17 -0700180 int notificationFrames = 0,
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800181 int sessionId = 0,
Richard Fitzgeraldad3af332013-03-25 16:54:37 +0000182 transfer_type transferType = TRANSFER_DEFAULT,
183 const audio_offload_info_t *offloadInfo = NULL);
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800184
Glenn Kasten083d1c12012-11-30 15:00:36 -0800185 /* Creates an audio track and registers it with AudioFlinger.
186 * With this constructor, the track is configured for static buffer mode.
187 * The format must not be 8-bit linear PCM.
188 * Data to be rendered is passed in a shared memory buffer
189 * identified by the argument sharedBuffer, which must be non-0.
190 * The memory should be initialized to the desired data before calling start().
Glenn Kasten4bae3642012-11-30 13:41:12 -0800191 * The write() method is not supported in this case.
Glenn Kasten362c4e62011-12-14 10:28:06 -0800192 * It is recommended to pass a callback function to be notified of playback end by an
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800193 * EVENT_UNDERRUN event.
194 */
195
Glenn Kastenfff6d712012-01-12 16:38:12 -0800196 AudioTrack( audio_stream_type_t streamType,
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800197 uint32_t sampleRate = 0,
Glenn Kastene1c39622012-01-04 09:36:37 -0800198 audio_format_t format = AUDIO_FORMAT_DEFAULT,
Glenn Kasten28b76b32012-07-03 17:24:41 -0700199 audio_channel_mask_t channelMask = 0,
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800200 const sp<IMemory>& sharedBuffer = 0,
Eric Laurent0ca3cf92012-04-18 09:24:29 -0700201 audio_output_flags_t flags = AUDIO_OUTPUT_FLAG_NONE,
Glenn Kastena0d68332012-01-27 16:47:15 -0800202 callback_t cbf = NULL,
203 void* user = NULL,
Eric Laurentbe916aa2010-06-01 23:49:17 -0700204 int notificationFrames = 0,
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800205 int sessionId = 0,
Richard Fitzgeraldad3af332013-03-25 16:54:37 +0000206 transfer_type transferType = TRANSFER_DEFAULT,
207 const audio_offload_info_t *offloadInfo = NULL);
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800208
209 /* Terminates the AudioTrack and unregisters it from AudioFlinger.
Glenn Kasten362c4e62011-12-14 10:28:06 -0800210 * Also destroys all resources associated with the AudioTrack.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800211 */
Glenn Kasten2799d742013-05-30 14:33:29 -0700212protected:
213 virtual ~AudioTrack();
214public:
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800215
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800216 /* Initialize an AudioTrack that was created using the AudioTrack() constructor.
217 * Don't call set() more than once, or after the AudioTrack() constructors that take parameters.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800218 * Returned status (from utils/Errors.h) can be:
Glenn Kasten362c4e62011-12-14 10:28:06 -0800219 * - NO_ERROR: successful initialization
220 * - INVALID_OPERATION: AudioTrack is already initialized
Glenn Kasten28b76b32012-07-03 17:24:41 -0700221 * - BAD_VALUE: invalid parameter (channelMask, format, sampleRate...)
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800222 * - NO_INIT: audio server or audio hardware not initialized
Glenn Kasten083d1c12012-11-30 15:00:36 -0800223 * If sharedBuffer is non-0, the frameCount parameter is ignored and
224 * replaced by the shared buffer's total allocated size in frame units.
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800225 *
226 * Parameters not listed in the AudioTrack constructors above:
227 *
228 * threadCanCallJava: Whether callbacks are made from an attached thread and thus can call JNI.
Glenn Kastenad2f6db2012-11-01 15:45:06 -0700229 */
Glenn Kastenfff6d712012-01-12 16:38:12 -0800230 status_t set(audio_stream_type_t streamType = AUDIO_STREAM_DEFAULT,
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800231 uint32_t sampleRate = 0,
Glenn Kastene1c39622012-01-04 09:36:37 -0800232 audio_format_t format = AUDIO_FORMAT_DEFAULT,
Glenn Kasten28b76b32012-07-03 17:24:41 -0700233 audio_channel_mask_t channelMask = 0,
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800234 int frameCount = 0,
Eric Laurent0ca3cf92012-04-18 09:24:29 -0700235 audio_output_flags_t flags = AUDIO_OUTPUT_FLAG_NONE,
Glenn Kastena0d68332012-01-27 16:47:15 -0800236 callback_t cbf = NULL,
237 void* user = NULL,
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800238 int notificationFrames = 0,
239 const sp<IMemory>& sharedBuffer = 0,
Eric Laurentbe916aa2010-06-01 23:49:17 -0700240 bool threadCanCallJava = false,
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800241 int sessionId = 0,
Richard Fitzgeraldad3af332013-03-25 16:54:37 +0000242 transfer_type transferType = TRANSFER_DEFAULT,
243 const audio_offload_info_t *offloadInfo = NULL);
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800244
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800245 /* Result of constructing the AudioTrack. This must be checked
Glenn Kasten362c4e62011-12-14 10:28:06 -0800246 * before using any AudioTrack API (except for set()), because using
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800247 * an uninitialized AudioTrack produces undefined results.
248 * See set() method above for possible return codes.
249 */
Glenn Kasten01437b72012-11-29 07:32:49 -0800250 status_t initCheck() const { return mStatus; }
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800251
Glenn Kasten362c4e62011-12-14 10:28:06 -0800252 /* Returns this track's estimated latency in milliseconds.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800253 * This includes the latency due to AudioTrack buffer size, AudioMixer (if any)
254 * and audio hardware driver.
255 */
Glenn Kastenc9b2e202013-02-26 11:32:32 -0800256 uint32_t latency() const { return mLatency; }
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800257
Glenn Kasten99e53b82012-01-19 08:59:58 -0800258 /* getters, see constructors and set() */
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800259
Glenn Kasten01437b72012-11-29 07:32:49 -0800260 audio_stream_type_t streamType() const { return mStreamType; }
261 audio_format_t format() const { return mFormat; }
Glenn Kastenb9980652012-01-11 09:48:27 -0800262
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800263 /* Return frame size in bytes, which for linear PCM is
264 * channelCount * (bit depth per channel / 8).
Glenn Kastenb9980652012-01-11 09:48:27 -0800265 * channelCount is determined from channelMask, and bit depth comes from format.
Glenn Kasten083d1c12012-11-30 15:00:36 -0800266 * For non-linear formats, the frame size is typically 1 byte.
Glenn Kastenb9980652012-01-11 09:48:27 -0800267 */
Glenn Kasten01437b72012-11-29 07:32:49 -0800268 size_t frameSize() const { return mFrameSize; }
269
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800270 uint32_t channelCount() const { return mChannelCount; }
271 uint32_t frameCount() const { return mFrameCount; }
272
Glenn Kasten083d1c12012-11-30 15:00:36 -0800273 /* Return the static buffer specified in constructor or set(), or 0 for streaming mode */
Glenn Kasten01437b72012-11-29 07:32:49 -0800274 sp<IMemory> sharedBuffer() const { return mSharedBuffer; }
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800275
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800276 /* After it's created the track is not active. Call start() to
277 * make it active. If set, the callback will start being called.
Glenn Kasten083d1c12012-11-30 15:00:36 -0800278 * If the track was previously paused, volume is ramped up over the first mix buffer.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800279 */
Richard Fitzgeraldb1a270d2013-05-14 12:12:21 +0100280 status_t start();
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800281
Glenn Kasten083d1c12012-11-30 15:00:36 -0800282 /* Stop a track.
283 * In static buffer mode, the track is stopped immediately.
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800284 * In streaming mode, the callback will cease being called. Note that obtainBuffer() still
285 * works and will fill up buffers until the pool is exhausted, and then will return WOULD_BLOCK.
286 * In streaming mode the stop does not occur immediately: any data remaining in the buffer
Glenn Kasten083d1c12012-11-30 15:00:36 -0800287 * is first drained, mixed, and output, and only then is the track marked as stopped.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800288 */
289 void stop();
290 bool stopped() const;
291
Glenn Kasten4bae3642012-11-30 13:41:12 -0800292 /* Flush a stopped or paused track. All previously buffered data is discarded immediately.
293 * This has the effect of draining the buffers without mixing or output.
294 * Flush is intended for streaming mode, for example before switching to non-contiguous content.
295 * This function is a no-op if the track is not stopped or paused, or uses a static buffer.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800296 */
297 void flush();
298
Glenn Kasten083d1c12012-11-30 15:00:36 -0800299 /* Pause a track. After pause, the callback will cease being called and
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800300 * obtainBuffer returns WOULD_BLOCK. Note that obtainBuffer() still works
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800301 * and will fill up buffers until the pool is exhausted.
Glenn Kasten083d1c12012-11-30 15:00:36 -0800302 * Volume is ramped down over the next mix buffer following the pause request,
303 * and then the track is marked as paused. It can be resumed with ramp up by start().
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800304 */
305 void pause();
306
Glenn Kasten362c4e62011-12-14 10:28:06 -0800307 /* Set volume for this track, mostly used for games' sound effects
308 * left and right volumes. Levels must be >= 0.0 and <= 1.0.
Glenn Kastenb1c09932012-02-27 16:21:04 -0800309 * This is the older API. New applications should use setVolume(float) when possible.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800310 */
Eric Laurentbe916aa2010-06-01 23:49:17 -0700311 status_t setVolume(float left, float right);
Glenn Kastenb1c09932012-02-27 16:21:04 -0800312
313 /* Set volume for all channels. This is the preferred API for new applications,
314 * especially for multi-channel content.
315 */
316 status_t setVolume(float volume);
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800317
Glenn Kasten362c4e62011-12-14 10:28:06 -0800318 /* Set the send level for this track. An auxiliary effect should be attached
319 * to the track with attachEffect(). Level must be >= 0.0 and <= 1.0.
Eric Laurentbe916aa2010-06-01 23:49:17 -0700320 */
Eric Laurent2beeb502010-07-16 07:43:46 -0700321 status_t setAuxEffectSendLevel(float level);
Glenn Kastena5224f32012-01-04 12:41:44 -0800322 void getAuxEffectSendLevel(float* level) const;
Eric Laurentbe916aa2010-06-01 23:49:17 -0700323
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800324 /* Set source sample rate for this track in Hz, mostly used for games' sound effects
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800325 */
Glenn Kasten3b16c762012-11-14 08:44:39 -0800326 status_t setSampleRate(uint32_t sampleRate);
327
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800328 /* Return current source sample rate in Hz, or 0 if unknown */
Glenn Kastena5224f32012-01-04 12:41:44 -0800329 uint32_t getSampleRate() const;
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800330
331 /* Enables looping and sets the start and end points of looping.
Glenn Kasten083d1c12012-11-30 15:00:36 -0800332 * Only supported for static buffer mode.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800333 *
334 * Parameters:
335 *
Glenn Kasten9c6745f2012-11-30 13:35:29 -0800336 * loopStart: loop start in frames relative to start of buffer.
337 * loopEnd: loop end in frames relative to start of buffer.
Glenn Kasten362c4e62011-12-14 10:28:06 -0800338 * loopCount: number of loops to execute. Calling setLoop() with loopCount == 0 cancels any
Glenn Kasten9c6745f2012-11-30 13:35:29 -0800339 * pending or active loop. loopCount == -1 means infinite looping.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800340 *
341 * For proper operation the following condition must be respected:
Glenn Kasten9c6745f2012-11-30 13:35:29 -0800342 * loopCount != 0 implies 0 <= loopStart < loopEnd <= frameCount().
343 *
344 * If the loop period (loopEnd - loopStart) is too small for the implementation to support,
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800345 * setLoop() will return BAD_VALUE. loopCount must be >= -1.
Glenn Kasten9c6745f2012-11-30 13:35:29 -0800346 *
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800347 */
348 status_t setLoop(uint32_t loopStart, uint32_t loopEnd, int loopCount);
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800349
Glenn Kasten362c4e62011-12-14 10:28:06 -0800350 /* Sets marker position. When playback reaches the number of frames specified, a callback with
351 * event type EVENT_MARKER is called. Calling setMarkerPosition with marker == 0 cancels marker
Glenn Kasten083d1c12012-11-30 15:00:36 -0800352 * notification callback. To set a marker at a position which would compute as 0,
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800353 * a workaround is to the set the marker at a nearby position such as ~0 or 1.
Glenn Kasten85ab62c2012-11-01 11:11:38 -0700354 * If the AudioTrack has been opened with no callback function associated, the operation will
355 * fail.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800356 *
357 * Parameters:
358 *
Glenn Kasten083d1c12012-11-30 15:00:36 -0800359 * marker: marker position expressed in wrapping (overflow) frame units,
360 * like the return value of getPosition().
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800361 *
362 * Returned status (from utils/Errors.h) can be:
363 * - NO_ERROR: successful operation
364 * - INVALID_OPERATION: the AudioTrack has no callback installed.
365 */
366 status_t setMarkerPosition(uint32_t marker);
Glenn Kastena5224f32012-01-04 12:41:44 -0800367 status_t getMarkerPosition(uint32_t *marker) const;
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800368
Glenn Kasten362c4e62011-12-14 10:28:06 -0800369 /* Sets position update period. Every time the number of frames specified has been played,
370 * a callback with event type EVENT_NEW_POS is called.
371 * Calling setPositionUpdatePeriod with updatePeriod == 0 cancels new position notification
372 * callback.
Glenn Kasten85ab62c2012-11-01 11:11:38 -0700373 * If the AudioTrack has been opened with no callback function associated, the operation will
374 * fail.
Glenn Kasten083d1c12012-11-30 15:00:36 -0800375 * Extremely small values may be rounded up to a value the implementation can support.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800376 *
377 * Parameters:
378 *
379 * updatePeriod: position update notification period expressed in frames.
380 *
381 * Returned status (from utils/Errors.h) can be:
382 * - NO_ERROR: successful operation
383 * - INVALID_OPERATION: the AudioTrack has no callback installed.
384 */
385 status_t setPositionUpdatePeriod(uint32_t updatePeriod);
Glenn Kastena5224f32012-01-04 12:41:44 -0800386 status_t getPositionUpdatePeriod(uint32_t *updatePeriod) const;
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800387
Glenn Kasten9c6745f2012-11-30 13:35:29 -0800388 /* Sets playback head position.
389 * Only supported for static buffer mode.
390 *
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800391 * Parameters:
392 *
Glenn Kasten9c6745f2012-11-30 13:35:29 -0800393 * position: New playback head position in frames relative to start of buffer.
394 * 0 <= position <= frameCount(). Note that end of buffer is permitted,
395 * but will result in an immediate underrun if started.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800396 *
397 * Returned status (from utils/Errors.h) can be:
398 * - NO_ERROR: successful operation
Glenn Kasten083d1c12012-11-30 15:00:36 -0800399 * - INVALID_OPERATION: the AudioTrack is not stopped or paused, or is streaming mode.
Glenn Kasten85ab62c2012-11-01 11:11:38 -0700400 * - BAD_VALUE: The specified position is beyond the number of frames present in AudioTrack
401 * buffer
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800402 */
403 status_t setPosition(uint32_t position);
Glenn Kasten083d1c12012-11-30 15:00:36 -0800404
405 /* Return the total number of frames played since playback start.
406 * The counter will wrap (overflow) periodically, e.g. every ~27 hours at 44.1 kHz.
407 * It is reset to zero by flush(), reload(), and stop().
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800408 *
409 * Parameters:
410 *
411 * position: Address where to return play head position.
412 *
413 * Returned status (from utils/Errors.h) can be:
414 * - NO_ERROR: successful operation
415 * - BAD_VALUE: position is NULL
Glenn Kasten083d1c12012-11-30 15:00:36 -0800416 */
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800417 status_t getPosition(uint32_t *position) const;
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800418
Glenn Kasten9c6745f2012-11-30 13:35:29 -0800419 /* For static buffer mode only, this returns the current playback position in frames
Glenn Kasten02de8922013-07-31 12:30:12 -0700420 * relative to start of buffer. It is analogous to the position units used by
Glenn Kasten9c6745f2012-11-30 13:35:29 -0800421 * setLoop() and setPosition(). After underrun, the position will be at end of buffer.
422 */
423 status_t getBufferPosition(uint32_t *position);
Glenn Kasten9c6745f2012-11-30 13:35:29 -0800424
Glenn Kasten362c4e62011-12-14 10:28:06 -0800425 /* Forces AudioTrack buffer full condition. When playing a static buffer, this method avoids
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800426 * rewriting the buffer before restarting playback after a stop.
427 * This method must be called with the AudioTrack in paused or stopped state.
Glenn Kasten083d1c12012-11-30 15:00:36 -0800428 * Not allowed in streaming mode.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800429 *
430 * Returned status (from utils/Errors.h) can be:
431 * - NO_ERROR: successful operation
Glenn Kasten083d1c12012-11-30 15:00:36 -0800432 * - INVALID_OPERATION: the AudioTrack is not stopped or paused, or is streaming mode.
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800433 */
434 status_t reload();
435
Glenn Kasten362c4e62011-12-14 10:28:06 -0800436 /* Returns a handle on the audio output used by this AudioTrack.
Eric Laurentc2f1f072009-07-17 12:17:14 -0700437 *
438 * Parameters:
439 * none.
440 *
441 * Returned value:
442 * handle on audio hardware output
443 */
444 audio_io_handle_t getOutput();
445
Glenn Kasten362c4e62011-12-14 10:28:06 -0800446 /* Returns the unique session ID associated with this track.
Eric Laurentbe916aa2010-06-01 23:49:17 -0700447 *
448 * Parameters:
449 * none.
450 *
451 * Returned value:
Glenn Kasten362c4e62011-12-14 10:28:06 -0800452 * AudioTrack session ID.
Eric Laurentbe916aa2010-06-01 23:49:17 -0700453 */
Glenn Kasten01437b72012-11-29 07:32:49 -0800454 int getSessionId() const { return mSessionId; }
Eric Laurentbe916aa2010-06-01 23:49:17 -0700455
Glenn Kasten362c4e62011-12-14 10:28:06 -0800456 /* Attach track auxiliary output to specified effect. Use effectId = 0
Eric Laurentbe916aa2010-06-01 23:49:17 -0700457 * to detach track from effect.
458 *
459 * Parameters:
460 *
461 * effectId: effectId obtained from AudioEffect::id().
462 *
463 * Returned status (from utils/Errors.h) can be:
464 * - NO_ERROR: successful operation
465 * - INVALID_OPERATION: the effect is not an auxiliary effect.
466 * - BAD_VALUE: The specified effect ID is invalid
467 */
468 status_t attachAuxEffect(int effectId);
469
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800470 /* Obtains a buffer of up to "audioBuffer->frameCount" empty slots for frames.
471 * After filling these slots with data, the caller should release them with releaseBuffer().
472 * If the track buffer is not full, obtainBuffer() returns as many contiguous
473 * [empty slots for] frames as are available immediately.
474 * If the track buffer is full and track is stopped, obtainBuffer() returns WOULD_BLOCK
475 * regardless of the value of waitCount.
476 * If the track buffer is full and track is not stopped, obtainBuffer() blocks with a
477 * maximum timeout based on waitCount; see chart below.
Glenn Kastenad2f6db2012-11-01 15:45:06 -0700478 * Buffers will be returned until the pool
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800479 * is exhausted, at which point obtainBuffer() will either block
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800480 * or return WOULD_BLOCK depending on the value of the "waitCount"
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800481 * parameter.
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800482 * Each sample is 16-bit signed PCM.
Glenn Kasten99e53b82012-01-19 08:59:58 -0800483 *
Glenn Kasten083d1c12012-11-30 15:00:36 -0800484 * obtainBuffer() and releaseBuffer() are deprecated for direct use by applications,
485 * which should use write() or callback EVENT_MORE_DATA instead.
486 *
Glenn Kasten99e53b82012-01-19 08:59:58 -0800487 * Interpretation of waitCount:
488 * +n limits wait time to n * WAIT_PERIOD_MS,
489 * -1 causes an (almost) infinite wait time,
490 * 0 non-blocking.
Glenn Kasten05d49992012-11-06 14:25:20 -0800491 *
492 * Buffer fields
493 * On entry:
494 * frameCount number of frames requested
495 * After error return:
496 * frameCount 0
497 * size 0
Glenn Kasten22eb4e22012-11-07 14:03:00 -0800498 * raw undefined
Glenn Kasten05d49992012-11-06 14:25:20 -0800499 * After successful return:
500 * frameCount actual number of frames available, <= number requested
501 * size actual number of bytes available
502 * raw pointer to the buffer
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800503 */
504
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800505 /* FIXME Deprecated public API for TRANSFER_OBTAIN mode */
506 status_t obtainBuffer(Buffer* audioBuffer, int32_t waitCount)
507 __attribute__((__deprecated__));
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800508
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800509private:
Glenn Kasten02de8922013-07-31 12:30:12 -0700510 /* If nonContig is non-NULL, it is an output parameter that will be set to the number of
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800511 * additional non-contiguous frames that are available immediately.
512 * FIXME We could pass an array of Buffers instead of only one Buffer to obtainBuffer(),
513 * in case the requested amount of frames is in two or more non-contiguous regions.
514 * FIXME requested and elapsed are both relative times. Consider changing to absolute time.
515 */
516 status_t obtainBuffer(Buffer* audioBuffer, const struct timespec *requested,
517 struct timespec *elapsed = NULL, size_t *nonContig = NULL);
518public:
Glenn Kasten99e53b82012-01-19 08:59:58 -0800519
Richard Fitzgeraldad3af332013-03-25 16:54:37 +0000520//EL_FIXME to be reconciled with new obtainBuffer() return codes and control block proxy
521// enum {
522// NO_MORE_BUFFERS = 0x80000001, // same name in AudioFlinger.h, ok to be different value
523// TEAR_DOWN = 0x80000002,
524// STOPPED = 1,
525// STREAM_END_WAIT,
526// STREAM_END
527// };
528
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800529 /* Release a filled buffer of "audioBuffer->frameCount" frames for AudioFlinger to process. */
530 // FIXME make private when obtainBuffer() for TRANSFER_OBTAIN is removed
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800531 void releaseBuffer(Buffer* audioBuffer);
532
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800533 /* As a convenience we provide a write() interface to the audio buffer.
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800534 * Input parameter 'size' is in byte units.
Glenn Kasten99e53b82012-01-19 08:59:58 -0800535 * This is implemented on top of obtainBuffer/releaseBuffer. For best
536 * performance use callbacks. Returns actual number of bytes written >= 0,
537 * or one of the following negative status codes:
Glenn Kasten02de8922013-07-31 12:30:12 -0700538 * INVALID_OPERATION AudioTrack is configured for static buffer or streaming mode
Glenn Kasten99e53b82012-01-19 08:59:58 -0800539 * BAD_VALUE size is invalid
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800540 * WOULD_BLOCK when obtainBuffer() returns same, or
541 * AudioTrack was stopped during the write
Glenn Kasten99e53b82012-01-19 08:59:58 -0800542 * or any other error code returned by IAudioTrack::start() or restoreTrack_l().
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800543 */
544 ssize_t write(const void* buffer, size_t size);
545
546 /*
547 * Dumps the state of an audio track.
548 */
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800549 status_t dump(int fd, const Vector<String16>& args) const;
550
551 /*
552 * Return the total number of frames which AudioFlinger desired but were unavailable,
553 * and thus which resulted in an underrun. Reset to zero by stop().
554 */
555 uint32_t getUnderrunFrames() const;
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800556
Richard Fitzgeraldad3af332013-03-25 16:54:37 +0000557 /* Get the flags */
558 audio_output_flags_t getFlags() const { return mFlags; }
559
560 /* Set parameters - only possible when using direct output */
561 status_t setParameters(const String8& keyValuePairs);
562
563 /* Get parameters */
564 String8 getParameters(const String8& keys);
565
John Grossman4ff14ba2012-02-08 16:37:41 -0800566protected:
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800567 /* copying audio tracks is not allowed */
568 AudioTrack(const AudioTrack& other);
569 AudioTrack& operator = (const AudioTrack& other);
570
571 /* a small internal class to handle the callback */
572 class AudioTrackThread : public Thread
573 {
574 public:
575 AudioTrackThread(AudioTrack& receiver, bool bCanCallJava = false);
Glenn Kasten3acbd052012-02-28 10:39:56 -0800576
577 // Do not call Thread::requestExitAndWait() without first calling requestExit().
578 // Thread::requestExitAndWait() is not virtual, and the implementation doesn't do enough.
579 virtual void requestExit();
580
581 void pause(); // suspend thread from execution at next loop boundary
582 void resume(); // allow thread to execute, if not requested to exit
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800583 void pauseConditional();
584 // like pause(), but only if prior resume() wasn't latched
Glenn Kasten3acbd052012-02-28 10:39:56 -0800585
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800586 private:
587 friend class AudioTrack;
588 virtual bool threadLoop();
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800589 AudioTrack& mReceiver;
590 virtual ~AudioTrackThread();
Glenn Kasten3acbd052012-02-28 10:39:56 -0800591 Mutex mMyLock; // Thread::mLock is private
592 Condition mMyCond; // Thread::mThreadExitedCondition is private
593 bool mPaused; // whether thread is currently paused
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800594 bool mResumeLatch; // whether next pauseConditional() will be a nop
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800595 };
596
Glenn Kasten99e53b82012-01-19 08:59:58 -0800597 // body of AudioTrackThread::threadLoop()
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800598 // returns the maximum amount of time before we would like to run again, where:
599 // 0 immediately
600 // > 0 no later than this many nanoseconds from now
601 // NS_WHENEVER still active but no particular deadline
602 // NS_INACTIVE inactive so don't run again until re-started
603 // NS_NEVER never again
604 static const nsecs_t NS_WHENEVER = -1, NS_INACTIVE = -2, NS_NEVER = -3;
605 nsecs_t processAudioBuffer(const sp<AudioTrackThread>& thread);
Richard Fitzgeraldad3af332013-03-25 16:54:37 +0000606 status_t processStreamEnd(int32_t waitCount);
607
Glenn Kastenea7939a2012-03-14 12:56:26 -0700608
Glenn Kastend5ed6e82012-11-02 13:05:14 -0700609 // caller must hold lock on mLock for all _l methods
Richard Fitzgeraldad3af332013-03-25 16:54:37 +0000610
Glenn Kastenfff6d712012-01-12 16:38:12 -0800611 status_t createTrack_l(audio_stream_type_t streamType,
Eric Laurent34f1d8e2009-11-04 08:27:26 -0800612 uint32_t sampleRate,
Glenn Kastene1c39622012-01-04 09:36:37 -0800613 audio_format_t format,
Glenn Kastene33054e2012-11-14 12:54:39 -0800614 size_t frameCount,
Eric Laurent0ca3cf92012-04-18 09:24:29 -0700615 audio_output_flags_t flags,
Eric Laurent34f1d8e2009-11-04 08:27:26 -0800616 const sp<IMemory>& sharedBuffer,
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800617 audio_io_handle_t output,
618 size_t epoch);
Glenn Kasten4bae3642012-11-30 13:41:12 -0800619
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800620 // can only be called when mState != STATE_ACTIVE
Eric Laurent1703cdf2011-03-07 14:52:59 -0800621 void flush_l();
Glenn Kasten4bae3642012-11-30 13:41:12 -0800622
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800623 void setLoop_l(uint32_t loopStart, uint32_t loopEnd, int loopCount);
Eric Laurent1703cdf2011-03-07 14:52:59 -0800624 audio_io_handle_t getOutput_l();
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800625
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800626 // FIXME enum is faster than strcmp() for parameter 'from'
627 status_t restoreTrack_l(const char *from);
628
Richard Fitzgeraldb1a270d2013-05-14 12:12:21 +0100629 bool isOffloaded() const
630 { return (mFlags & AUDIO_OUTPUT_FLAG_COMPRESS_OFFLOAD) != 0; }
631
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800632 // may be changed if IAudioTrack is re-created
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800633 sp<IAudioTrack> mAudioTrack;
634 sp<IMemory> mCblkMemory;
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800635 audio_track_cblk_t* mCblk; // re-load after mLock.unlock()
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800636
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800637 sp<AudioTrackThread> mAudioTrackThread;
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800638 float mVolume[2];
Eric Laurentbe916aa2010-06-01 23:49:17 -0700639 float mSendLevel;
Glenn Kastene3aa6592012-12-04 12:22:46 -0800640 uint32_t mSampleRate;
Glenn Kastenb6037442012-11-14 13:42:25 -0800641 size_t mFrameCount; // corresponds to current IAudioTrack
642 size_t mReqFrameCount; // frame count to request the next time a new
643 // IAudioTrack is needed
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800644
Glenn Kasten22eb4e22012-11-07 14:03:00 -0800645
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800646 // constant after constructor or set()
Glenn Kasten60a83922012-06-21 12:56:37 -0700647 audio_format_t mFormat; // as requested by client, not forced to 16-bit
Glenn Kastenfff6d712012-01-12 16:38:12 -0800648 audio_stream_type_t mStreamType;
Glenn Kastene4756fe2012-11-29 13:38:14 -0800649 uint32_t mChannelCount;
Glenn Kasten28b76b32012-07-03 17:24:41 -0700650 audio_channel_mask_t mChannelMask;
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800651 transfer_type mTransfer;
Glenn Kasten83a03822012-11-12 07:58:20 -0800652
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800653 // mFrameSize is equal to mFrameSizeAF for non-PCM or 16-bit PCM data. For 8-bit PCM data, it's
654 // twice as large as mFrameSize because data is expanded to 16-bit before it's stored in buffer.
Glenn Kasten83a03822012-11-12 07:58:20 -0800655 size_t mFrameSize; // app-level frame size
656 size_t mFrameSizeAF; // AudioFlinger frame size
657
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800658 status_t mStatus;
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800659
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800660 // can change dynamically when IAudioTrack invalidated
661 uint32_t mLatency; // in ms
662
663 // Indicates the current track state. Protected by mLock.
664 enum State {
665 STATE_ACTIVE,
666 STATE_STOPPED,
667 STATE_PAUSED,
Richard Fitzgeraldb1a270d2013-05-14 12:12:21 +0100668 STATE_PAUSED_STOPPING,
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800669 STATE_FLUSHED,
Richard Fitzgeraldb1a270d2013-05-14 12:12:21 +0100670 STATE_STOPPING,
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800671 } mState;
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800672
Glenn Kasten99e53b82012-01-19 08:59:58 -0800673 callback_t mCbf; // callback handler for events, or NULL
Glenn Kastenad2f6db2012-11-01 15:45:06 -0700674 void* mUserData; // for client callback handler
675
676 // for notification APIs
Glenn Kasten85ab62c2012-11-01 11:11:38 -0700677 uint32_t mNotificationFramesReq; // requested number of frames between each
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800678 // notification callback,
679 // at initial source sample rate
Glenn Kasten85ab62c2012-11-01 11:11:38 -0700680 uint32_t mNotificationFramesAct; // actual number of frames between each
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800681 // notification callback,
682 // at initial source sample rate
683 bool mRefreshRemaining; // processAudioBuffer() should refresh next 2
684
685 // These are private to processAudioBuffer(), and are not protected by a lock
686 uint32_t mRemainingFrames; // number of frames to request in obtainBuffer()
687 bool mRetryOnPartialBuffer; // sleep and retry after partial obtainBuffer()
Richard Fitzgeraldb1a270d2013-05-14 12:12:21 +0100688 uint32_t mObservedSequence; // last observed value of mSequence
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800689
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800690 sp<IMemory> mSharedBuffer;
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800691 uint32_t mLoopPeriod; // in frames, zero means looping is disabled
Glenn Kasten083d1c12012-11-30 15:00:36 -0800692 uint32_t mMarkerPosition; // in wrapping (overflow) frame units
Jean-Michel Trivi2c22aeb2009-03-24 18:11:07 -0700693 bool mMarkerReached;
Glenn Kastenad2f6db2012-11-01 15:45:06 -0700694 uint32_t mNewPosition; // in frames
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800695 uint32_t mUpdatePeriod; // in frames, zero means no EVENT_NEW_POS
Glenn Kastenad2f6db2012-11-01 15:45:06 -0700696
Eric Laurent0ca3cf92012-04-18 09:24:29 -0700697 audio_output_flags_t mFlags;
Eric Laurentbe916aa2010-06-01 23:49:17 -0700698 int mSessionId;
Eric Laurent2beeb502010-07-16 07:43:46 -0700699 int mAuxEffectId;
Glenn Kastend5ed6e82012-11-02 13:05:14 -0700700
Glenn Kasten9a2aaf92012-01-03 09:42:47 -0800701 mutable Mutex mLock;
Glenn Kastend5ed6e82012-11-02 13:05:14 -0700702
John Grossman4ff14ba2012-02-08 16:37:41 -0800703 bool mIsTimed;
Glenn Kasten87913512011-06-22 16:15:25 -0700704 int mPreviousPriority; // before start()
Glenn Kastena6364332012-04-19 09:35:04 -0700705 SchedPolicy mPreviousSchedulingGroup;
Glenn Kastena07f17c2013-04-23 12:39:37 -0700706 bool mAwaitBoost; // thread should wait for priority boost before running
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800707
708 // The proxy should only be referenced while a lock is held because the proxy isn't
709 // multi-thread safe, especially the SingleStateQueue part of the proxy.
710 // An exception is that a blocking ClientProxy::obtainBuffer() may be called without a lock,
711 // provided that the caller also holds an extra reference to the proxy and shared memory to keep
712 // them around in case they are replaced during the obtainBuffer().
713 sp<StaticAudioTrackClientProxy> mStaticProxy; // for type safety only
714 sp<AudioTrackClientProxy> mProxy; // primary owner of the memory
715
716 bool mInUnderrun; // whether track is currently in underrun state
Glenn Kastend054c322013-07-12 12:59:20 -0700717 String8 mName; // server's name for this IAudioTrack
Glenn Kasten9f80dd22012-12-18 15:57:32 -0800718
719private:
720 class DeathNotifier : public IBinder::DeathRecipient {
721 public:
722 DeathNotifier(AudioTrack* audioTrack) : mAudioTrack(audioTrack) { }
723 protected:
724 virtual void binderDied(const wp<IBinder>& who);
725 private:
726 const wp<AudioTrack> mAudioTrack;
727 };
728
729 sp<DeathNotifier> mDeathNotifier;
730 uint32_t mSequence; // incremented for each new IAudioTrack attempt
Richard Fitzgeraldb1a270d2013-05-14 12:12:21 +0100731 audio_io_handle_t mOutput; // cached output io handle
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800732};
733
John Grossman4ff14ba2012-02-08 16:37:41 -0800734class TimedAudioTrack : public AudioTrack
735{
736public:
737 TimedAudioTrack();
738
739 /* allocate a shared memory buffer that can be passed to queueTimedBuffer */
740 status_t allocateTimedBuffer(size_t size, sp<IMemory>* buffer);
741
742 /* queue a buffer obtained via allocateTimedBuffer for playback at the
Glenn Kastenc3ae93f2012-07-30 10:59:30 -0700743 given timestamp. PTS units are microseconds on the media time timeline.
John Grossman4ff14ba2012-02-08 16:37:41 -0800744 The media time transform (set with setMediaTimeTransform) set by the
745 audio producer will handle converting from media time to local time
746 (perhaps going through the common time timeline in the case of
747 synchronized multiroom audio case) */
748 status_t queueTimedBuffer(const sp<IMemory>& buffer, int64_t pts);
749
750 /* define a transform between media time and either common time or
751 local time */
752 enum TargetTimeline {LOCAL_TIME, COMMON_TIME};
753 status_t setMediaTimeTransform(const LinearTransform& xform,
754 TargetTimeline target);
755};
The Android Open Source Project89fa4ad2009-03-03 19:31:44 -0800756
757}; // namespace android
758
759#endif // ANDROID_AUDIOTRACK_H