AudioTrack.h revision ab5cdbaf65ca509681d2726aacdf3ac8bfb6b3fa
124943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner/* 224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Copyright (C) 2007 The Android Open Source Project 324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Licensed under the Apache License, Version 2.0 (the "License"); 524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * you may not use this file except in compliance with the License. 624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * You may obtain a copy of the License at 724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * http://www.apache.org/licenses/LICENSE-2.0 924943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 10d891f9b872103235cfd2ed452c6f14a4394d9b3aDaniel Malea * Unless required by applicable law or agreed to in writing, software 11d891f9b872103235cfd2ed452c6f14a4394d9b3aDaniel Malea * distributed under the License is distributed on an "AS IS" BASIS, 1224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 1324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * See the License for the specific language governing permissions and 1424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * limitations under the License. 1524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner */ 1624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 1724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner#ifndef ANDROID_AUDIOTRACK_H 18841026fc8d1cc22bd3b9e74623b413a3e6aa9d38Sean Callanan#define ANDROID_AUDIOTRACK_H 1924943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 2024943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner#include <cutils/sched_policy.h> 21324067bc91877dbbd6ec3a8663914fa3dbb7e3c9Jim Ingham#include <media/AudioSystem.h> 2224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner#include <media/AudioTimestamp.h> 2365dafa8344c8c018e346dd331a7782081a896239Sean Callanan#include <media/IAudioTrack.h> 2463c468c6743f7c77add899b91d5847a076c0acf3Stephen Wilson#include <utils/threads.h> 2524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 2624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattnernamespace android { 27841026fc8d1cc22bd3b9e74623b413a3e6aa9d38Sean Callanan 2863094e0bb161580564954dee512955c1c79d3476Greg Clayton// ---------------------------------------------------------------------------- 2924943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 30324067bc91877dbbd6ec3a8663914fa3dbb7e3c9Jim Inghamstruct audio_track_cblk_t; 3124943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattnerclass AudioTrackClientProxy; 3224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattnerclass StaticAudioTrackClientProxy; 3324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 3424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner// ---------------------------------------------------------------------------- 3524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 36abe0fed36d83e1c37af9dae90c2d25db742b4515Greg Claytonclass AudioTrack : public RefBase 37841026fc8d1cc22bd3b9e74623b413a3e6aa9d38Sean Callanan{ 3824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattnerpublic: 3924943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 4024943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner /* Events used by AudioTrack callback function (callback_t). 4124943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Keep in sync with frameworks/base/media/java/android/media/AudioTrack.java NATIVE_EVENT_*. 42a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton */ 43a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton enum event_type { 4424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner EVENT_MORE_DATA = 0, // Request to write more data to buffer. 4524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner // If this event is delivered but the callback handler 4624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner // does not want to write more data, the handler must explicitly 4724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner // ignore the event by setting frameCount to zero. 4824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner EVENT_UNDERRUN = 1, // Buffer underrun occurred. 4924943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner EVENT_LOOP_END = 2, // Sample loop end was reached; playback restarted from 5024943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner // loop start if loop count was not 0. 5124943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner EVENT_MARKER = 3, // Playback head is at the specified marker position 52a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton // (See setMarkerPosition()). 53a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton EVENT_NEW_POS = 4, // Playback head is at a new position 54a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton // (See setPositionUpdatePeriod()). 5547beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham EVENT_BUFFER_END = 5, // Playback head is at the end of the buffer. 56b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham // Not currently used by android.media.AudioTrack. 57c82316ee7956f48345e0b7b89039cd246fb2a99dJim Ingham EVENT_NEW_IAUDIOTRACK = 6, // IAudioTrack was re-created, either due to re-routing and 58a47ab9573e6956003f809462a4cfabb6d97b4eedJim Ingham // voluntary invalidation by mediaserver, or mediaserver crash. 59a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton EVENT_STREAM_END = 7, // Sent after all the buffers queued in AF and HW are played 60a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton // back (after stop is called) 61a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton EVENT_NEW_TIMESTAMP = 8, // Delivered periodically and when there's a significant change 62a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton // in the mapping from frame position to presentation time. 63a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton // See AudioTimestamp for the information included with event. 64a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton }; 65a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton 66a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton /* Client should declare Buffer on the stack and pass address to obtainBuffer() 67a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton * and releaseBuffer(). See also callback_t for EVENT_MORE_DATA. 6824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner */ 69a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton 70a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton class Buffer 71a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton { 7224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner public: 7324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner // FIXME use m prefix 7424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner size_t frameCount; // number of sample frames corresponding to size; 756475c42148a8ea1ca86e5db465db7eca742d897dGreg Clayton // on input it is the number of frames desired, 7624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner // on output is the number of frames actually filled 7724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner // (currently ignored, but will make the primary field in future) 7824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 79c1ad82eb979ee856b86aec6e2acb7bddf75f7c4fCaroline Tice size_t size; // input/output in bytes == frameCount * frameSize 80c1ad82eb979ee856b86aec6e2acb7bddf75f7c4fCaroline Tice // on input it is unused 81c1ad82eb979ee856b86aec6e2acb7bddf75f7c4fCaroline Tice // on output is the number of bytes actually filled 829c236733d43e6250c8a5671a438f4a2afeb9c0b2Greg Clayton // FIXME this is redundant with respect to frameCount, 83c1ad82eb979ee856b86aec6e2acb7bddf75f7c4fCaroline Tice // and TRANSFER_OBTAIN mode is broken for 8-bit data 84c1ad82eb979ee856b86aec6e2acb7bddf75f7c4fCaroline Tice // since we don't define the frame format 8524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 8647beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham union { 8747beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham void* raw; 8847beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham short* i16; // signed 16-bit 8947beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham int8_t* i8; // unsigned 8-bit, offset by 0x80 9047beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham }; // input: unused, output: pointer to buffer 9147beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham }; 9247beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham 9347beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham /* As a convenience, if a callback is supplied, a handler thread 9447beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham * is automatically created with the appropriate priority. This thread 9547beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham * invokes the callback when a new buffer becomes available or various conditions occur. 96324067bc91877dbbd6ec3a8663914fa3dbb7e3c9Jim Ingham * Parameters: 97ea9d4267a629a1c732eb0400fa0288cee31ad49dJim Ingham * 98b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * event: type of event notified (see enum AudioTrack::event_type). 99b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * user: Pointer to context for use by the callback receiver. 100b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * info: Pointer to optional parameter according to event type: 101b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * - EVENT_MORE_DATA: pointer to AudioTrack::Buffer struct. The callback must not write 102b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * more bytes than indicated by 'size' field and update 'size' if fewer bytes are 103b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * written. 104b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * - EVENT_UNDERRUN: unused. 105b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * - EVENT_LOOP_END: pointer to an int indicating the number of loops remaining. 106b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * - EVENT_MARKER: pointer to const uint32_t containing the marker position in frames. 107b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * - EVENT_NEW_POS: pointer to const uint32_t containing the new position in frames. 10847beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham * - EVENT_BUFFER_END: unused. 10947beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham * - EVENT_NEW_IAUDIOTRACK: unused. 11047beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham * - EVENT_STREAM_END: unused. 11147beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham * - EVENT_NEW_TIMESTAMP: pointer to const AudioTimestamp. 11247beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham */ 11347beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham 11447beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham typedef void (*callback_t)(int event, void* user, void *info); 11547beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham 11647beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham /* Returns the minimum frame count required for the successful creation of 11747beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham * an AudioTrack object. 11847beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham * Returned status (from utils/Errors.h) can be: 11947beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham * - NO_ERROR: successful operation 120ea9d4267a629a1c732eb0400fa0288cee31ad49dJim Ingham * - NO_INIT: audio server or audio hardware not initialized 12147dc457387b690c5e4df1c0c7dd8c4337b92e630Sean Callanan * - BAD_VALUE: unsupported configuration 12247dc457387b690c5e4df1c0c7dd8c4337b92e630Sean Callanan * frameCount is guaranteed to be non-zero if status is NO_ERROR, 123b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * and is undefined otherwise. 124b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham */ 125b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham 126b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham static status_t getMinFrameCount(size_t* frameCount, 1279c236733d43e6250c8a5671a438f4a2afeb9c0b2Greg Clayton audio_stream_type_t streamType, 12847dc457387b690c5e4df1c0c7dd8c4337b92e630Sean Callanan uint32_t sampleRate); 12947dc457387b690c5e4df1c0c7dd8c4337b92e630Sean Callanan 13024943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner /* How data is transferred to AudioTrack 1319c236733d43e6250c8a5671a438f4a2afeb9c0b2Greg Clayton */ 13224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner enum transfer_type { 13324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner TRANSFER_DEFAULT, // not specified explicitly; determine from the other parameters 13424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner TRANSFER_CALLBACK, // callback EVENT_MORE_DATA 13524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner TRANSFER_OBTAIN, // FIXME deprecated: call obtainBuffer() and releaseBuffer() 13624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner TRANSFER_SYNC, // synchronous write() 13724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner TRANSFER_SHARED, // shared memory 13824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner }; 139a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton 14024943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner /* Constructs an uninitialized AudioTrack. No connection with 141b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * AudioFlinger takes place. Use set() after this. 142b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham */ 143b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham AudioTrack(); 144b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham 145b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham /* Creates an AudioTrack object and registers it with AudioFlinger. 146b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * Once created, the track needs to be started before it can be used. 147b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * Unspecified values are set to appropriate default values. 148b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * With this constructor, the track is configured for streaming mode. 149b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * Data to be rendered is supplied by write() or by the callback EVENT_MORE_DATA. 150b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * Intermixing a combination of write() and non-ignored EVENT_MORE_DATA is not allowed. 151b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * 152b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham * Parameters: 15324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 15447beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham * streamType: Select the type of audio stream this track is attached to 15547beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham * (e.g. AUDIO_STREAM_MUSIC). 15624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * sampleRate: Data source sampling rate in Hz. 15724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * format: Audio format. For mixed tracks, any PCM format supported by server is OK 158b344843f75ef893762c93fd0a22d2d45712ce74dGreg Clayton * or AUDIO_FORMAT_PCM_8_BIT which is handled on client side. For direct 15924943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * and offloaded tracks, the possible format(s) depends on the output sink. 16024943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * channelMask: Channel mask, such that audio_is_output_channel(channelMask) is true. 16124943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * frameCount: Minimum size of track PCM buffer in frames. This defines the 16224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * application's contribution to the 16324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * latency of the track. The actual size selected by the AudioTrack could be 164238c0a1e7b733cee539258faa656159c63f9e893Greg Clayton * larger if the requested size is not compatible with current audio HAL 165da26bd203cbb104291b39891febf7481794f205fJim Ingham * configuration. Zero means to use a default value. 166da26bd203cbb104291b39891febf7481794f205fJim Ingham * flags: See comments on audio_output_flags_t in <system/audio.h>. 16702ed285a58314cb9766275ae658c5ffe2fff5a0cJim Ingham * cbf: Callback function. If not null, this function is called periodically 168da26bd203cbb104291b39891febf7481794f205fJim Ingham * to provide new data and inform of marker, position updates, etc. 169ea0bb4d45c14447a2fe9be9f4bd8e79a84513537Greg Clayton * user: Context for use by the callback receiver. 170a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton * notificationFrames: The callback function is called each time notificationFrames PCM 171a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton * frames have been consumed from track input buffer. 172a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton * This is expressed in units of frames at the initial source sample rate. 173cc112ac3c53c7c6e115d9969f38d22c43eac17f5Johnny Chen * sessionId: Specific session ID, or zero to use default. 17424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * transferType: How data is transferred to AudioTrack. 17524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * threadCanCallJava: Not present in parameter list, and so is fixed at false. 17624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner */ 17747beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham 17847beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham AudioTrack( audio_stream_type_t streamType, 17947beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham uint32_t sampleRate, 18047beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham audio_format_t format, 18147beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham audio_channel_mask_t, 18247beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham size_t frameCount = 0, 18302ed285a58314cb9766275ae658c5ffe2fff5a0cJim Ingham audio_output_flags_t flags = AUDIO_OUTPUT_FLAG_NONE, 18402ed285a58314cb9766275ae658c5ffe2fff5a0cJim Ingham callback_t cbf = NULL, 18502ed285a58314cb9766275ae658c5ffe2fff5a0cJim Ingham void* user = NULL, 18602ed285a58314cb9766275ae658c5ffe2fff5a0cJim Ingham uint32_t notificationFrames = 0, 18702ed285a58314cb9766275ae658c5ffe2fff5a0cJim Ingham int sessionId = AUDIO_SESSION_ALLOCATE, 18802ed285a58314cb9766275ae658c5ffe2fff5a0cJim Ingham transfer_type transferType = TRANSFER_DEFAULT, 18902ed285a58314cb9766275ae658c5ffe2fff5a0cJim Ingham const audio_offload_info_t *offloadInfo = NULL, 19047beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham int uid = -1, 19124943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner pid_t pid = -1); 19224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 19324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner /* Creates an audio track and registers it with AudioFlinger. 19402ed285a58314cb9766275ae658c5ffe2fff5a0cJim Ingham * With this constructor, the track is configured for static buffer mode. 19524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * The format must not be 8-bit linear PCM. 19643b014aa33e20e61790e16ed69a2c57aae2fbc6eCaroline Tice * Data to be rendered is passed in a shared memory buffer 19743b014aa33e20e61790e16ed69a2c57aae2fbc6eCaroline Tice * identified by the argument sharedBuffer, which must be non-0. 19843b014aa33e20e61790e16ed69a2c57aae2fbc6eCaroline Tice * The memory should be initialized to the desired data before calling start(). 19943b014aa33e20e61790e16ed69a2c57aae2fbc6eCaroline Tice * The write() method is not supported in this case. 20043b014aa33e20e61790e16ed69a2c57aae2fbc6eCaroline Tice * It is recommended to pass a callback function to be notified of playback end by an 20143b014aa33e20e61790e16ed69a2c57aae2fbc6eCaroline Tice * EVENT_UNDERRUN event. 20243b014aa33e20e61790e16ed69a2c57aae2fbc6eCaroline Tice */ 20343b014aa33e20e61790e16ed69a2c57aae2fbc6eCaroline Tice 20443b014aa33e20e61790e16ed69a2c57aae2fbc6eCaroline Tice AudioTrack( audio_stream_type_t streamType, 20543b014aa33e20e61790e16ed69a2c57aae2fbc6eCaroline Tice uint32_t sampleRate, 20643b014aa33e20e61790e16ed69a2c57aae2fbc6eCaroline Tice audio_format_t format, 20743b014aa33e20e61790e16ed69a2c57aae2fbc6eCaroline Tice audio_channel_mask_t channelMask, 20843b014aa33e20e61790e16ed69a2c57aae2fbc6eCaroline Tice const sp<IMemory>& sharedBuffer, 209a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton audio_output_flags_t flags = AUDIO_OUTPUT_FLAG_NONE, 21024a6bd9835ed1655984397b0cdf35127e47681e9Greg Clayton callback_t cbf = NULL, 21124a6bd9835ed1655984397b0cdf35127e47681e9Greg Clayton void* user = NULL, 212a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton uint32_t notificationFrames = 0, 2133a91e146f4e40ce9b44af3619551f6b6d9bb3b7fEnrico Granata int sessionId = AUDIO_SESSION_ALLOCATE, 214a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton transfer_type transferType = TRANSFER_DEFAULT, 21524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner const audio_offload_info_t *offloadInfo = NULL, 21624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner int uid = -1, 21724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner pid_t pid = -1); 21824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 21924943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner /* Terminates the AudioTrack and unregisters it from AudioFlinger. 22024943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Also destroys all resources associated with the AudioTrack. 22124943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner */ 22224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattnerprotected: 22324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner virtual ~AudioTrack(); 224a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Claytonpublic: 22524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 22624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner /* Initialize an AudioTrack that was created using the AudioTrack() constructor. 22724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Don't call set() more than once, or after the AudioTrack() constructors that take parameters. 22824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Returned status (from utils/Errors.h) can be: 22924943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * - NO_ERROR: successful initialization 23024943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * - INVALID_OPERATION: AudioTrack is already initialized 23163094e0bb161580564954dee512955c1c79d3476Greg Clayton * - BAD_VALUE: invalid parameter (channelMask, format, sampleRate...) 23224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * - NO_INIT: audio server or audio hardware not initialized 23324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * If status is not equal to NO_ERROR, don't call any other APIs on this AudioTrack. 23424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * If sharedBuffer is non-0, the frameCount parameter is ignored and 23524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * replaced by the shared buffer's total allocated size in frame units. 23624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 23724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Parameters not listed in the AudioTrack constructors above: 238892fadd1f1001d1082cd2edcf282fee0cba8ac87Caroline Tice * 239892fadd1f1001d1082cd2edcf282fee0cba8ac87Caroline Tice * threadCanCallJava: Whether callbacks are made from an attached thread and thus can call JNI. 24024943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner */ 24124943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner status_t set(audio_stream_type_t streamType, 24224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner uint32_t sampleRate, 243892fadd1f1001d1082cd2edcf282fee0cba8ac87Caroline Tice audio_format_t format, 2442b5e4e6bc442fb77e7fe96c459f9ca38d4970ed0Caroline Tice audio_channel_mask_t channelMask, 245234981a4559db084f9c90612660e40f19915b89cGreg Clayton size_t frameCount = 0, 246234981a4559db084f9c90612660e40f19915b89cGreg Clayton audio_output_flags_t flags = AUDIO_OUTPUT_FLAG_NONE, 247234981a4559db084f9c90612660e40f19915b89cGreg Clayton callback_t cbf = NULL, 248234981a4559db084f9c90612660e40f19915b89cGreg Clayton void* user = NULL, 249234981a4559db084f9c90612660e40f19915b89cGreg Clayton uint32_t notificationFrames = 0, 250234981a4559db084f9c90612660e40f19915b89cGreg Clayton const sp<IMemory>& sharedBuffer = 0, 2512b5e4e6bc442fb77e7fe96c459f9ca38d4970ed0Caroline Tice bool threadCanCallJava = false, 25224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner int sessionId = AUDIO_SESSION_ALLOCATE, 25324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner transfer_type transferType = TRANSFER_DEFAULT, 25424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner const audio_offload_info_t *offloadInfo = NULL, 25524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner int uid = -1, 25624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner pid_t pid = -1, 25724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner audio_attributes_t* pAttributes = NULL); 25824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 2594a348081030cdd2af758fddc869518357d9befd3Caroline Tice /* Result of constructing the AudioTrack. This must be checked for successful initialization 2604a348081030cdd2af758fddc869518357d9befd3Caroline Tice * before using any AudioTrack API (except for set()), because using 2614a348081030cdd2af758fddc869518357d9befd3Caroline Tice * an uninitialized AudioTrack produces undefined results. 26224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * See set() method above for possible return codes. 26324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner */ 26424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner status_t initCheck() const { return mStatus; } 26524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 26624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner /* Returns this track's estimated latency in milliseconds. 26724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * This includes the latency due to AudioTrack buffer size, AudioMixer (if any) 26824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * and audio hardware driver. 26924943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner */ 27063094e0bb161580564954dee512955c1c79d3476Greg Clayton uint32_t latency() const { return mLatency; } 27124943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 27224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner /* getters, see constructors and set() */ 273c4f55fee15b66ea53da092ca50400ac5d8b0692dCaroline Tice 274c4f55fee15b66ea53da092ca50400ac5d8b0692dCaroline Tice audio_stream_type_t streamType() const { return mStreamType; } 275c4f55fee15b66ea53da092ca50400ac5d8b0692dCaroline Tice audio_format_t format() const { return mFormat; } 276892fadd1f1001d1082cd2edcf282fee0cba8ac87Caroline Tice 2772b5e4e6bc442fb77e7fe96c459f9ca38d4970ed0Caroline Tice /* Return frame size in bytes, which for linear PCM is 278234981a4559db084f9c90612660e40f19915b89cGreg Clayton * channelCount * (bit depth per channel / 8). 279234981a4559db084f9c90612660e40f19915b89cGreg Clayton * channelCount is determined from channelMask, and bit depth comes from format. 280234981a4559db084f9c90612660e40f19915b89cGreg Clayton * For non-linear formats, the frame size is typically 1 byte. 281234981a4559db084f9c90612660e40f19915b89cGreg Clayton */ 282234981a4559db084f9c90612660e40f19915b89cGreg Clayton size_t frameSize() const { return mFrameSize; } 283234981a4559db084f9c90612660e40f19915b89cGreg Clayton 2842b5e4e6bc442fb77e7fe96c459f9ca38d4970ed0Caroline Tice uint32_t channelCount() const { return mChannelCount; } 285c4f55fee15b66ea53da092ca50400ac5d8b0692dCaroline Tice size_t frameCount() const { return mFrameCount; } 286c4f55fee15b66ea53da092ca50400ac5d8b0692dCaroline Tice 287c4f55fee15b66ea53da092ca50400ac5d8b0692dCaroline Tice /* Return the static buffer specified in constructor or set(), or 0 for streaming mode */ 288c4f55fee15b66ea53da092ca50400ac5d8b0692dCaroline Tice sp<IMemory> sharedBuffer() const { return mSharedBuffer; } 289c4f55fee15b66ea53da092ca50400ac5d8b0692dCaroline Tice 290c4f55fee15b66ea53da092ca50400ac5d8b0692dCaroline Tice /* After it's created the track is not active. Call start() to 29124943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * make it active. If set, the callback will start being called. 292c4f55fee15b66ea53da092ca50400ac5d8b0692dCaroline Tice * If the track was previously paused, volume is ramped up over the first mix buffer. 29324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner */ 29487e1f77d81fe724619d7298baf8cc9d32351e9ebCaroline Tice status_t start(); 29587e1f77d81fe724619d7298baf8cc9d32351e9ebCaroline Tice 29624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner /* Stop a track. 29787e1f77d81fe724619d7298baf8cc9d32351e9ebCaroline Tice * In static buffer mode, the track is stopped immediately. 29887e1f77d81fe724619d7298baf8cc9d32351e9ebCaroline Tice * In streaming mode, the callback will cease being called. Note that obtainBuffer() still 29987e1f77d81fe724619d7298baf8cc9d32351e9ebCaroline Tice * works and will fill up buffers until the pool is exhausted, and then will return WOULD_BLOCK. 30087e1f77d81fe724619d7298baf8cc9d32351e9ebCaroline Tice * In streaming mode the stop does not occur immediately: any data remaining in the buffer 30124943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * is first drained, mixed, and output, and only then is the track marked as stopped. 30224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner */ 30324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner void stop(); 30424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner bool stopped() const; 30524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 30624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner /* Flush a stopped or paused track. All previously buffered data is discarded immediately. 30724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * This has the effect of draining the buffers without mixing or output. 30824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Flush is intended for streaming mode, for example before switching to non-contiguous content. 30966ed2fbeaf588fe4105a1305f7e956dcf9fbe299Greg Clayton * This function is a no-op if the track is not stopped or paused, or uses a static buffer. 31066ed2fbeaf588fe4105a1305f7e956dcf9fbe299Greg Clayton */ 31166ed2fbeaf588fe4105a1305f7e956dcf9fbe299Greg Clayton void flush(); 31287e1f77d81fe724619d7298baf8cc9d32351e9ebCaroline Tice 31387e1f77d81fe724619d7298baf8cc9d32351e9ebCaroline Tice /* Pause a track. After pause, the callback will cease being called and 31466ed2fbeaf588fe4105a1305f7e956dcf9fbe299Greg Clayton * obtainBuffer returns WOULD_BLOCK. Note that obtainBuffer() still works 31566ed2fbeaf588fe4105a1305f7e956dcf9fbe299Greg Clayton * and will fill up buffers until the pool is exhausted. 31624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Volume is ramped down over the next mix buffer following the pause request, 31735f6df9e780954bffb056734e2cdada2894da408Greg Clayton * and then the track is marked as paused. It can be resumed with ramp up by start(). 31835f6df9e780954bffb056734e2cdada2894da408Greg Clayton */ 31935f6df9e780954bffb056734e2cdada2894da408Greg Clayton void pause(); 32035f6df9e780954bffb056734e2cdada2894da408Greg Clayton 32135f6df9e780954bffb056734e2cdada2894da408Greg Clayton /* Set volume for this track, mostly used for games' sound effects 32235f6df9e780954bffb056734e2cdada2894da408Greg Clayton * left and right volumes. Levels must be >= 0.0 and <= 1.0. 323f35a96c63732a1b3adf875ea44c7d3d7de6f8eecSean Callanan * This is the older API. New applications should use setVolume(float) when possible. 324f35a96c63732a1b3adf875ea44c7d3d7de6f8eecSean Callanan */ 325f35a96c63732a1b3adf875ea44c7d3d7de6f8eecSean Callanan status_t setVolume(float left, float right); 326f35a96c63732a1b3adf875ea44c7d3d7de6f8eecSean Callanan 327567e7f3ba16eb48cb9fd6a2f26f2f7269eb6983cGreg Clayton /* Set volume for all channels. This is the preferred API for new applications, 328841026fc8d1cc22bd3b9e74623b413a3e6aa9d38Sean Callanan * especially for multi-channel content. 329427f290ff96f3ab9f2cf3a1af7001d2c560424c7Greg Clayton */ 330427f290ff96f3ab9f2cf3a1af7001d2c560424c7Greg Clayton status_t setVolume(float volume); 331b344843f75ef893762c93fd0a22d2d45712ce74dGreg Clayton 3326a92553d2cc2b7a3b853fcb6da101583435c2dc0Sean Callanan /* Set the send level for this track. An auxiliary effect should be attached 3336a92553d2cc2b7a3b853fcb6da101583435c2dc0Sean Callanan * to the track with attachEffect(). Level must be >= 0.0 and <= 1.0. 3343a91e146f4e40ce9b44af3619551f6b6d9bb3b7fEnrico Granata */ 33547beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham status_t setAuxEffectSendLevel(float level); 3363a91e146f4e40ce9b44af3619551f6b6d9bb3b7fEnrico Granata void getAuxEffectSendLevel(float* level) const; 337d27026e46d8430fb451d85ac161a8492e1930245Enrico Granata 338b794020ffbd6473c59a6e98be044df50abf7fc30Jim Ingham /* Set source sample rate for this track in Hz, mostly used for games' sound effects 339d27026e46d8430fb451d85ac161a8492e1930245Enrico Granata */ 3403a91e146f4e40ce9b44af3619551f6b6d9bb3b7fEnrico Granata status_t setSampleRate(uint32_t sampleRate); 34147beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham 34247beabb1386be44e3f90dbc30a0b22c23b93a4dcJim Ingham /* Return current source sample rate in Hz */ 343d27026e46d8430fb451d85ac161a8492e1930245Enrico Granata uint32_t getSampleRate() const; 344567e7f3ba16eb48cb9fd6a2f26f2f7269eb6983cGreg Clayton 34535f6df9e780954bffb056734e2cdada2894da408Greg Clayton /* Enables looping and sets the start and end points of looping. 3466cca9695637b27bd583eaae310d5c09dede7cc49Enrico Granata * Only supported for static buffer mode. 347d27026e46d8430fb451d85ac161a8492e1930245Enrico Granata * 34801711aa1b451159a31d6423ee8919a3a426b4984Sean Callanan * Parameters: 349427f290ff96f3ab9f2cf3a1af7001d2c560424c7Greg Clayton * 350427f290ff96f3ab9f2cf3a1af7001d2c560424c7Greg Clayton * loopStart: loop start in frames relative to start of buffer. 35196abc62dcb25159dbb532e477ba2cf6d85b81700Sean Callanan * loopEnd: loop end in frames relative to start of buffer. 35296abc62dcb25159dbb532e477ba2cf6d85b81700Sean Callanan * loopCount: number of loops to execute. Calling setLoop() with loopCount == 0 cancels any 353427f290ff96f3ab9f2cf3a1af7001d2c560424c7Greg Clayton * pending or active loop. loopCount == -1 means infinite looping. 354427f290ff96f3ab9f2cf3a1af7001d2c560424c7Greg Clayton * 35596abc62dcb25159dbb532e477ba2cf6d85b81700Sean Callanan * For proper operation the following condition must be respected: 35696abc62dcb25159dbb532e477ba2cf6d85b81700Sean Callanan * loopCount != 0 implies 0 <= loopStart < loopEnd <= frameCount(). 35796abc62dcb25159dbb532e477ba2cf6d85b81700Sean Callanan * 35896abc62dcb25159dbb532e477ba2cf6d85b81700Sean Callanan * If the loop period (loopEnd - loopStart) is too small for the implementation to support, 35996abc62dcb25159dbb532e477ba2cf6d85b81700Sean Callanan * setLoop() will return BAD_VALUE. loopCount must be >= -1. 360c3f5cd817ad045cab3a79f37ab5e65f8a659b7abEnrico Granata * 3613a91e146f4e40ce9b44af3619551f6b6d9bb3b7fEnrico Granata */ 36296abc62dcb25159dbb532e477ba2cf6d85b81700Sean Callanan status_t setLoop(uint32_t loopStart, uint32_t loopEnd, int loopCount); 36396abc62dcb25159dbb532e477ba2cf6d85b81700Sean Callanan 36496abc62dcb25159dbb532e477ba2cf6d85b81700Sean Callanan /* Sets marker position. When playback reaches the number of frames specified, a callback with 36596abc62dcb25159dbb532e477ba2cf6d85b81700Sean Callanan * event type EVENT_MARKER is called. Calling setMarkerPosition with marker == 0 cancels marker 36696abc62dcb25159dbb532e477ba2cf6d85b81700Sean Callanan * notification callback. To set a marker at a position which would compute as 0, 36796abc62dcb25159dbb532e477ba2cf6d85b81700Sean Callanan * a workaround is to set the marker at a nearby position such as ~0 or 1. 368427f290ff96f3ab9f2cf3a1af7001d2c560424c7Greg Clayton * If the AudioTrack has been opened with no callback function associated, the operation will 369427f290ff96f3ab9f2cf3a1af7001d2c560424c7Greg Clayton * fail. 370427f290ff96f3ab9f2cf3a1af7001d2c560424c7Greg Clayton * 3712431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan * Parameters: 372fe1b47d67c6884a0860d1ee62a4f0beae707c679Greg Clayton * 3731e1e6cb5314a8f31630dc817a52fb68a70b623feSean Callanan * marker: marker position expressed in wrapping (overflow) frame units, 37496abc62dcb25159dbb532e477ba2cf6d85b81700Sean Callanan * like the return value of getPosition(). 3751e1e6cb5314a8f31630dc817a52fb68a70b623feSean Callanan * 37696abc62dcb25159dbb532e477ba2cf6d85b81700Sean Callanan * Returned status (from utils/Errors.h) can be: 3771e1e6cb5314a8f31630dc817a52fb68a70b623feSean Callanan * - NO_ERROR: successful operation 3781e1e6cb5314a8f31630dc817a52fb68a70b623feSean Callanan * - INVALID_OPERATION: the AudioTrack has no callback installed. 3791e1e6cb5314a8f31630dc817a52fb68a70b623feSean Callanan */ 380fe1b47d67c6884a0860d1ee62a4f0beae707c679Greg Clayton status_t setMarkerPosition(uint32_t marker); 381fe1b47d67c6884a0860d1ee62a4f0beae707c679Greg Clayton status_t getMarkerPosition(uint32_t *marker) const; 382fe1b47d67c6884a0860d1ee62a4f0beae707c679Greg Clayton 3832431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan /* Sets position update period. Every time the number of frames specified has been played, 3842431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan * a callback with event type EVENT_NEW_POS is called. 3852431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan * Calling setPositionUpdatePeriod with updatePeriod == 0 cancels new position notification 38636da2aa6dc5ad9994b638ed09eb81c44cc05540bGreg Clayton * callback. 3872431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan * If the AudioTrack has been opened with no callback function associated, the operation will 3882431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan * fail. 3892431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan * Extremely small values may be rounded up to a value the implementation can support. 3902431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan * 3912431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan * Parameters: 3922431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan * 3932431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan * updatePeriod: position update notification period expressed in frames. 3942431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan * 3952431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan * Returned status (from utils/Errors.h) can be: 3962431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan * - NO_ERROR: successful operation 3972431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan * - INVALID_OPERATION: the AudioTrack has no callback installed. 3982431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan */ 3992431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan status_t setPositionUpdatePeriod(uint32_t updatePeriod); 4002431244f929e269c6ecd51aa3eb606b6a2474f19Sean Callanan status_t getPositionUpdatePeriod(uint32_t *updatePeriod) const; 401fe1b47d67c6884a0860d1ee62a4f0beae707c679Greg Clayton 402360f53f3c216ee4fb433da0a367168785328a856Jim Ingham /* Sets playback head position. 403360f53f3c216ee4fb433da0a367168785328a856Jim Ingham * Only supported for static buffer mode. 404427f290ff96f3ab9f2cf3a1af7001d2c560424c7Greg Clayton * 405427f290ff96f3ab9f2cf3a1af7001d2c560424c7Greg Clayton * Parameters: 406427f290ff96f3ab9f2cf3a1af7001d2c560424c7Greg Clayton * 40787e1f77d81fe724619d7298baf8cc9d32351e9ebCaroline Tice * position: New playback head position in frames relative to start of buffer. 408427f290ff96f3ab9f2cf3a1af7001d2c560424c7Greg Clayton * 0 <= position <= frameCount(). Note that end of buffer is permitted, 409841026fc8d1cc22bd3b9e74623b413a3e6aa9d38Sean Callanan * but will result in an immediate underrun if started. 41082b74c85f719be67b78f9284a6a1341d47f7ac9cSean Callanan * 411841026fc8d1cc22bd3b9e74623b413a3e6aa9d38Sean Callanan * Returned status (from utils/Errors.h) can be: 41224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * - NO_ERROR: successful operation 41324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * - INVALID_OPERATION: the AudioTrack is not stopped or paused, or is streaming mode. 41424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * - BAD_VALUE: The specified position is beyond the number of frames present in AudioTrack 415da26bd203cbb104291b39891febf7481794f205fJim Ingham * buffer 41624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner */ 41724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner status_t setPosition(uint32_t position); 41824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 41924943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner /* Return the total number of frames played since playback start. 42024943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * The counter will wrap (overflow) periodically, e.g. every ~27 hours at 44.1 kHz. 421a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton * It is reset to zero by flush(), reload(), and stop(). 42224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 42324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Parameters: 42424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 42524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * position: Address where to return play head position. 42624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 42724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Returned status (from utils/Errors.h) can be: 42824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * - NO_ERROR: successful operation 42924943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * - BAD_VALUE: position is NULL 430238c0a1e7b733cee539258faa656159c63f9e893Greg Clayton */ 43124943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner status_t getPosition(uint32_t *position) const; 43224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 43324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner /* For static buffer mode only, this returns the current playback position in frames 43424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * relative to start of buffer. It is analogous to the position units used by 43524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * setLoop() and setPosition(). After underrun, the position will be at end of buffer. 43663094e0bb161580564954dee512955c1c79d3476Greg Clayton */ 43724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner status_t getBufferPosition(uint32_t *position); 43824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 43924943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner /* Forces AudioTrack buffer full condition. When playing a static buffer, this method avoids 44024943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * rewriting the buffer before restarting playback after a stop. 441238c0a1e7b733cee539258faa656159c63f9e893Greg Clayton * This method must be called with the AudioTrack in paused or stopped state. 44224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Not allowed in streaming mode. 44324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 44424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Returned status (from utils/Errors.h) can be: 44524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * - NO_ERROR: successful operation 44624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * - INVALID_OPERATION: the AudioTrack is not stopped or paused, or is streaming mode. 44724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner */ 44824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner status_t reload(); 44924943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 45024943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner /* Returns a handle on the audio output used by this AudioTrack. 45124943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 45224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Parameters: 45324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * none. 45424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 45524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Returned value: 45624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * handle on audio hardware output, or AUDIO_IO_HANDLE_NONE if the 45724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * track needed to be re-created but that failed 45824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner */ 45924943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner audio_io_handle_t getOutput() const; 46024943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 46124943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner /* Returns the unique session ID associated with this track. 46224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 46324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Parameters: 46424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * none. 46524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 46624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Returned value: 46724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * AudioTrack session ID. 46824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner */ 46924943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner int getSessionId() const { return mSessionId; } 47024943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 47124943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner /* Attach track auxiliary output to specified effect. Use effectId = 0 47224943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * to detach track from effect. 47324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 47424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Parameters: 47524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 47624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * effectId: effectId obtained from AudioEffect::id(). 47724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 47824943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Returned status (from utils/Errors.h) can be: 47924943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * - NO_ERROR: successful operation 48024943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * - INVALID_OPERATION: the effect is not an auxiliary effect. 48124943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * - BAD_VALUE: The specified effect ID is invalid 48263094e0bb161580564954dee512955c1c79d3476Greg Clayton */ 483238c0a1e7b733cee539258faa656159c63f9e893Greg Clayton status_t attachAuxEffect(int effectId); 48424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner 485143fcc3a15425659b381502ed4e1e50a3e726f36Greg Clayton /* Obtains a buffer of up to "audioBuffer->frameCount" empty slots for frames. 486a42880a8e464a3e4f93951ae797313e5e38cdcd3Greg Clayton * After filling these slots with data, the caller should release them with releaseBuffer(). 487143fcc3a15425659b381502ed4e1e50a3e726f36Greg Clayton * If the track buffer is not full, obtainBuffer() returns as many contiguous 488143fcc3a15425659b381502ed4e1e50a3e726f36Greg Clayton * [empty slots for] frames as are available immediately. 489143fcc3a15425659b381502ed4e1e50a3e726f36Greg Clayton * If the track buffer is full and track is stopped, obtainBuffer() returns WOULD_BLOCK 490143fcc3a15425659b381502ed4e1e50a3e726f36Greg Clayton * regardless of the value of waitCount. 491143fcc3a15425659b381502ed4e1e50a3e726f36Greg Clayton * If the track buffer is full and track is not stopped, obtainBuffer() blocks with a 492143fcc3a15425659b381502ed4e1e50a3e726f36Greg Clayton * maximum timeout based on waitCount; see chart below. 49324943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Buffers will be returned until the pool 49424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * is exhausted, at which point obtainBuffer() will either block 49524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * or return WOULD_BLOCK depending on the value of the "waitCount" 49624943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * parameter. 49724943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * Each sample is 16-bit signed PCM. 49846b6249780aafc75d152a926b961fe7a162e8c8aSean Callanan * 49987e1f77d81fe724619d7298baf8cc9d32351e9ebCaroline Tice * obtainBuffer() and releaseBuffer() are deprecated for direct use by applications, 5000deefc7fe1b741b9bb8416a9a971ae2b42794f72Johnny Chen * which should use write() or callback EVENT_MORE_DATA instead. 5010deefc7fe1b741b9bb8416a9a971ae2b42794f72Johnny Chen * 5020deefc7fe1b741b9bb8416a9a971ae2b42794f72Johnny Chen * Interpretation of waitCount: 5030deefc7fe1b741b9bb8416a9a971ae2b42794f72Johnny Chen * +n limits wait time to n * WAIT_PERIOD_MS, 50424943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * -1 causes an (almost) infinite wait time, 50524943d2ee8bfaa7cf5893e4709143924157a5c1eChris Lattner * 0 non-blocking. 506 * 507 * Buffer fields 508 * On entry: 509 * frameCount number of frames requested 510 * After error return: 511 * frameCount 0 512 * size 0 513 * raw undefined 514 * After successful return: 515 * frameCount actual number of frames available, <= number requested 516 * size actual number of bytes available 517 * raw pointer to the buffer 518 */ 519 520 /* FIXME Deprecated public API for TRANSFER_OBTAIN mode */ 521 status_t obtainBuffer(Buffer* audioBuffer, int32_t waitCount) 522 __attribute__((__deprecated__)); 523 524private: 525 /* If nonContig is non-NULL, it is an output parameter that will be set to the number of 526 * additional non-contiguous frames that are available immediately. 527 * FIXME We could pass an array of Buffers instead of only one Buffer to obtainBuffer(), 528 * in case the requested amount of frames is in two or more non-contiguous regions. 529 * FIXME requested and elapsed are both relative times. Consider changing to absolute time. 530 */ 531 status_t obtainBuffer(Buffer* audioBuffer, const struct timespec *requested, 532 struct timespec *elapsed = NULL, size_t *nonContig = NULL); 533public: 534 535 /* Release a filled buffer of "audioBuffer->frameCount" frames for AudioFlinger to process. */ 536 // FIXME make private when obtainBuffer() for TRANSFER_OBTAIN is removed 537 void releaseBuffer(Buffer* audioBuffer); 538 539 /* As a convenience we provide a write() interface to the audio buffer. 540 * Input parameter 'size' is in byte units. 541 * This is implemented on top of obtainBuffer/releaseBuffer. For best 542 * performance use callbacks. Returns actual number of bytes written >= 0, 543 * or one of the following negative status codes: 544 * INVALID_OPERATION AudioTrack is configured for static buffer or streaming mode 545 * BAD_VALUE size is invalid 546 * WOULD_BLOCK when obtainBuffer() returns same, or 547 * AudioTrack was stopped during the write 548 * or any other error code returned by IAudioTrack::start() or restoreTrack_l(). 549 * Default behavior is to only return until all data has been transferred. Set 'blocking' to 550 * false for the method to return immediately without waiting to try multiple times to write 551 * the full content of the buffer. 552 */ 553 ssize_t write(const void* buffer, size_t size, bool blocking = true); 554 555 /* 556 * Dumps the state of an audio track. 557 */ 558 status_t dump(int fd, const Vector<String16>& args) const; 559 560 /* 561 * Return the total number of frames which AudioFlinger desired but were unavailable, 562 * and thus which resulted in an underrun. Reset to zero by stop(). 563 */ 564 uint32_t getUnderrunFrames() const; 565 566 /* Get the flags */ 567 audio_output_flags_t getFlags() const { AutoMutex _l(mLock); return mFlags; } 568 569 /* Set parameters - only possible when using direct output */ 570 status_t setParameters(const String8& keyValuePairs); 571 572 /* Get parameters */ 573 String8 getParameters(const String8& keys); 574 575 /* Poll for a timestamp on demand. 576 * Use if EVENT_NEW_TIMESTAMP is not delivered often enough for your needs, 577 * or if you need to get the most recent timestamp outside of the event callback handler. 578 * Caution: calling this method too often may be inefficient; 579 * if you need a high resolution mapping between frame position and presentation time, 580 * consider implementing that at application level, based on the low resolution timestamps. 581 * Returns NO_ERROR if timestamp is valid. 582 */ 583 status_t getTimestamp(AudioTimestamp& timestamp); 584 585protected: 586 /* copying audio tracks is not allowed */ 587 AudioTrack(const AudioTrack& other); 588 AudioTrack& operator = (const AudioTrack& other); 589 590 void setAttributesFromStreamType(audio_stream_type_t streamType); 591 void setStreamTypeFromAttributes(audio_attributes_t& aa); 592 /* paa is guaranteed non-NULL */ 593 bool isValidAttributes(const audio_attributes_t *paa); 594 595 /* a small internal class to handle the callback */ 596 class AudioTrackThread : public Thread 597 { 598 public: 599 AudioTrackThread(AudioTrack& receiver, bool bCanCallJava = false); 600 601 // Do not call Thread::requestExitAndWait() without first calling requestExit(). 602 // Thread::requestExitAndWait() is not virtual, and the implementation doesn't do enough. 603 virtual void requestExit(); 604 605 void pause(); // suspend thread from execution at next loop boundary 606 void resume(); // allow thread to execute, if not requested to exit 607 608 private: 609 void pauseInternal(nsecs_t ns = 0LL); 610 // like pause(), but only used internally within thread 611 612 friend class AudioTrack; 613 virtual bool threadLoop(); 614 AudioTrack& mReceiver; 615 virtual ~AudioTrackThread(); 616 Mutex mMyLock; // Thread::mLock is private 617 Condition mMyCond; // Thread::mThreadExitedCondition is private 618 bool mPaused; // whether thread is requested to pause at next loop entry 619 bool mPausedInt; // whether thread internally requests pause 620 nsecs_t mPausedNs; // if mPausedInt then associated timeout, otherwise ignored 621 bool mIgnoreNextPausedInt; // whether to ignore next mPausedInt request 622 }; 623 624 // body of AudioTrackThread::threadLoop() 625 // returns the maximum amount of time before we would like to run again, where: 626 // 0 immediately 627 // > 0 no later than this many nanoseconds from now 628 // NS_WHENEVER still active but no particular deadline 629 // NS_INACTIVE inactive so don't run again until re-started 630 // NS_NEVER never again 631 static const nsecs_t NS_WHENEVER = -1, NS_INACTIVE = -2, NS_NEVER = -3; 632 nsecs_t processAudioBuffer(); 633 634 bool isOffloaded() const; 635 bool isDirect() const; 636 bool isOffloadedOrDirect() const; 637 638 // caller must hold lock on mLock for all _l methods 639 640 status_t createTrack_l(size_t epoch); 641 642 // can only be called when mState != STATE_ACTIVE 643 void flush_l(); 644 645 void setLoop_l(uint32_t loopStart, uint32_t loopEnd, int loopCount); 646 647 // FIXME enum is faster than strcmp() for parameter 'from' 648 status_t restoreTrack_l(const char *from); 649 650 bool isOffloaded_l() const 651 { return (mFlags & AUDIO_OUTPUT_FLAG_COMPRESS_OFFLOAD) != 0; } 652 653 bool isOffloadedOrDirect_l() const 654 { return (mFlags & (AUDIO_OUTPUT_FLAG_COMPRESS_OFFLOAD| 655 AUDIO_OUTPUT_FLAG_DIRECT)) != 0; } 656 657 bool isDirect_l() const 658 { return (mFlags & AUDIO_OUTPUT_FLAG_DIRECT) != 0; } 659 660 // Next 4 fields may be changed if IAudioTrack is re-created, but always != 0 661 sp<IAudioTrack> mAudioTrack; 662 sp<IMemory> mCblkMemory; 663 audio_track_cblk_t* mCblk; // re-load after mLock.unlock() 664 audio_io_handle_t mOutput; // returned by AudioSystem::getOutput() 665 666 sp<AudioTrackThread> mAudioTrackThread; 667 668 float mVolume[2]; 669 float mSendLevel; 670 mutable uint32_t mSampleRate; // mutable because getSampleRate() can update it. 671 size_t mFrameCount; // corresponds to current IAudioTrack, value is 672 // reported back by AudioFlinger to the client 673 size_t mReqFrameCount; // frame count to request the first or next time 674 // a new IAudioTrack is needed, non-decreasing 675 676 // constant after constructor or set() 677 audio_format_t mFormat; // as requested by client, not forced to 16-bit 678 audio_stream_type_t mStreamType; 679 uint32_t mChannelCount; 680 audio_channel_mask_t mChannelMask; 681 sp<IMemory> mSharedBuffer; 682 transfer_type mTransfer; 683 audio_offload_info_t mOffloadInfoCopy; 684 const audio_offload_info_t* mOffloadInfo; 685 audio_attributes_t mAttributes; 686 687 // mFrameSize is equal to mFrameSizeAF for non-PCM or 16-bit PCM data. For 8-bit PCM data, it's 688 // twice as large as mFrameSize because data is expanded to 16-bit before it's stored in buffer. 689 size_t mFrameSize; // app-level frame size 690 size_t mFrameSizeAF; // AudioFlinger frame size 691 692 status_t mStatus; 693 694 // can change dynamically when IAudioTrack invalidated 695 uint32_t mLatency; // in ms 696 697 // Indicates the current track state. Protected by mLock. 698 enum State { 699 STATE_ACTIVE, 700 STATE_STOPPED, 701 STATE_PAUSED, 702 STATE_PAUSED_STOPPING, 703 STATE_FLUSHED, 704 STATE_STOPPING, 705 } mState; 706 707 // for client callback handler 708 callback_t mCbf; // callback handler for events, or NULL 709 void* mUserData; 710 711 // for notification APIs 712 uint32_t mNotificationFramesReq; // requested number of frames between each 713 // notification callback, 714 // at initial source sample rate 715 uint32_t mNotificationFramesAct; // actual number of frames between each 716 // notification callback, 717 // at initial source sample rate 718 bool mRefreshRemaining; // processAudioBuffer() should refresh 719 // mRemainingFrames and mRetryOnPartialBuffer 720 721 // These are private to processAudioBuffer(), and are not protected by a lock 722 uint32_t mRemainingFrames; // number of frames to request in obtainBuffer() 723 bool mRetryOnPartialBuffer; // sleep and retry after partial obtainBuffer() 724 uint32_t mObservedSequence; // last observed value of mSequence 725 726 uint32_t mLoopPeriod; // in frames, zero means looping is disabled 727 728 uint32_t mMarkerPosition; // in wrapping (overflow) frame units 729 bool mMarkerReached; 730 uint32_t mNewPosition; // in frames 731 uint32_t mUpdatePeriod; // in frames, zero means no EVENT_NEW_POS 732 733 audio_output_flags_t mFlags; 734 // const after set(), except for bits AUDIO_OUTPUT_FLAG_FAST and AUDIO_OUTPUT_FLAG_OFFLOAD. 735 // mLock must be held to read or write those bits reliably. 736 737 int mSessionId; 738 int mAuxEffectId; 739 740 mutable Mutex mLock; 741 742 bool mIsTimed; 743 int mPreviousPriority; // before start() 744 SchedPolicy mPreviousSchedulingGroup; 745 bool mAwaitBoost; // thread should wait for priority boost before running 746 747 // The proxy should only be referenced while a lock is held because the proxy isn't 748 // multi-thread safe, especially the SingleStateQueue part of the proxy. 749 // An exception is that a blocking ClientProxy::obtainBuffer() may be called without a lock, 750 // provided that the caller also holds an extra reference to the proxy and shared memory to keep 751 // them around in case they are replaced during the obtainBuffer(). 752 sp<StaticAudioTrackClientProxy> mStaticProxy; // for type safety only 753 sp<AudioTrackClientProxy> mProxy; // primary owner of the memory 754 755 bool mInUnderrun; // whether track is currently in underrun state 756 uint32_t mPausedPosition; 757 758private: 759 class DeathNotifier : public IBinder::DeathRecipient { 760 public: 761 DeathNotifier(AudioTrack* audioTrack) : mAudioTrack(audioTrack) { } 762 protected: 763 virtual void binderDied(const wp<IBinder>& who); 764 private: 765 const wp<AudioTrack> mAudioTrack; 766 }; 767 768 sp<DeathNotifier> mDeathNotifier; 769 uint32_t mSequence; // incremented for each new IAudioTrack attempt 770 int mClientUid; 771 pid_t mClientPid; 772}; 773 774class TimedAudioTrack : public AudioTrack 775{ 776public: 777 TimedAudioTrack(); 778 779 /* allocate a shared memory buffer that can be passed to queueTimedBuffer */ 780 status_t allocateTimedBuffer(size_t size, sp<IMemory>* buffer); 781 782 /* queue a buffer obtained via allocateTimedBuffer for playback at the 783 given timestamp. PTS units are microseconds on the media time timeline. 784 The media time transform (set with setMediaTimeTransform) set by the 785 audio producer will handle converting from media time to local time 786 (perhaps going through the common time timeline in the case of 787 synchronized multiroom audio case) */ 788 status_t queueTimedBuffer(const sp<IMemory>& buffer, int64_t pts); 789 790 /* define a transform between media time and either common time or 791 local time */ 792 enum TargetTimeline {LOCAL_TIME, COMMON_TIME}; 793 status_t setMediaTimeTransform(const LinearTransform& xform, 794 TargetTimeline target); 795}; 796 797}; // namespace android 798 799#endif // ANDROID_AUDIOTRACK_H 800