Home | History | Annotate | Download | only in media
      1 /*
      2  * Copyright (C) 2008 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_AUDIOSYSTEM_H_
     18 #define ANDROID_AUDIOSYSTEM_H_
     19 
     20 #include <hardware/audio_effect.h>
     21 #include <media/IAudioFlingerClient.h>
     22 #include <system/audio.h>
     23 #include <system/audio_policy.h>
     24 #include <utils/Errors.h>
     25 #include <utils/Mutex.h>
     26 
     27 namespace android {
     28 
     29 typedef void (*audio_error_callback)(status_t err);
     30 
     31 class IAudioFlinger;
     32 class IAudioPolicyService;
     33 class String8;
     34 
     35 class AudioSystem
     36 {
     37 public:
     38 
     39     /* These are static methods to control the system-wide AudioFlinger
     40      * only privileged processes can have access to them
     41      */
     42 
     43     // mute/unmute microphone
     44     static status_t muteMicrophone(bool state);
     45     static status_t isMicrophoneMuted(bool *state);
     46 
     47     // set/get master volume
     48     static status_t setMasterVolume(float value);
     49     static status_t getMasterVolume(float* volume);
     50 
     51     // mute/unmute audio outputs
     52     static status_t setMasterMute(bool mute);
     53     static status_t getMasterMute(bool* mute);
     54 
     55     // set/get stream volume on specified output
     56     static status_t setStreamVolume(audio_stream_type_t stream, float value,
     57                                     audio_io_handle_t output);
     58     static status_t getStreamVolume(audio_stream_type_t stream, float* volume,
     59                                     audio_io_handle_t output);
     60 
     61     // mute/unmute stream
     62     static status_t setStreamMute(audio_stream_type_t stream, bool mute);
     63     static status_t getStreamMute(audio_stream_type_t stream, bool* mute);
     64 
     65     // set audio mode in audio hardware
     66     static status_t setMode(audio_mode_t mode);
     67 
     68     // returns true in *state if tracks are active on the specified stream or have been active
     69     // in the past inPastMs milliseconds
     70     static status_t isStreamActive(audio_stream_type_t stream, bool *state, uint32_t inPastMs = 0);
     71     // returns true in *state if tracks are active for what qualifies as remote playback
     72     // on the specified stream or have been active in the past inPastMs milliseconds. Remote
     73     // playback isn't mutually exclusive with local playback.
     74     static status_t isStreamActiveRemotely(audio_stream_type_t stream, bool *state,
     75             uint32_t inPastMs = 0);
     76     // returns true in *state if a recorder is currently recording with the specified source
     77     static status_t isSourceActive(audio_source_t source, bool *state);
     78 
     79     // set/get audio hardware parameters. The function accepts a list of parameters
     80     // key value pairs in the form: key1=value1;key2=value2;...
     81     // Some keys are reserved for standard parameters (See AudioParameter class).
     82     static status_t setParameters(audio_io_handle_t ioHandle, const String8& keyValuePairs);
     83     static String8  getParameters(audio_io_handle_t ioHandle, const String8& keys);
     84 
     85     static void setErrorCallback(audio_error_callback cb);
     86 
     87     // helper function to obtain AudioFlinger service handle
     88     static const sp<IAudioFlinger>& get_audio_flinger();
     89 
     90     static float linearToLog(int volume);
     91     static int logToLinear(float volume);
     92 
     93     static status_t getOutputSamplingRate(uint32_t* samplingRate,
     94             audio_stream_type_t stream = AUDIO_STREAM_DEFAULT);
     95     static status_t getOutputFrameCount(size_t* frameCount,
     96             audio_stream_type_t stream = AUDIO_STREAM_DEFAULT);
     97     static status_t getOutputLatency(uint32_t* latency,
     98             audio_stream_type_t stream = AUDIO_STREAM_DEFAULT);
     99     static status_t getSamplingRate(audio_io_handle_t output,
    100                                           audio_stream_type_t streamType,
    101                                           uint32_t* samplingRate);
    102     // returns the number of frames per audio HAL write buffer. Corresponds to
    103     // audio_stream->get_buffer_size()/audio_stream_frame_size()
    104     static status_t getFrameCount(audio_io_handle_t output,
    105                                   audio_stream_type_t stream,
    106                                   size_t* frameCount);
    107     // returns the audio output stream latency in ms. Corresponds to
    108     // audio_stream_out->get_latency()
    109     static status_t getLatency(audio_io_handle_t output,
    110                                audio_stream_type_t stream,
    111                                uint32_t* latency);
    112 
    113     static bool routedToA2dpOutput(audio_stream_type_t streamType);
    114 
    115     static status_t getInputBufferSize(uint32_t sampleRate, audio_format_t format,
    116         audio_channel_mask_t channelMask, size_t* buffSize);
    117 
    118     static status_t setVoiceVolume(float volume);
    119 
    120     // return the number of audio frames written by AudioFlinger to audio HAL and
    121     // audio dsp to DAC since the output on which the specified stream is playing
    122     // has exited standby.
    123     // returned status (from utils/Errors.h) can be:
    124     // - NO_ERROR: successful operation, halFrames and dspFrames point to valid data
    125     // - INVALID_OPERATION: Not supported on current hardware platform
    126     // - BAD_VALUE: invalid parameter
    127     // NOTE: this feature is not supported on all hardware platforms and it is
    128     // necessary to check returned status before using the returned values.
    129     static status_t getRenderPosition(audio_io_handle_t output,
    130                                       size_t *halFrames,
    131                                       size_t *dspFrames,
    132                                       audio_stream_type_t stream = AUDIO_STREAM_DEFAULT);
    133 
    134     // return the number of input frames lost by HAL implementation, or 0 if the handle is invalid
    135     static size_t getInputFramesLost(audio_io_handle_t ioHandle);
    136 
    137     static int newAudioSessionId();
    138     static void acquireAudioSessionId(int audioSession);
    139     static void releaseAudioSessionId(int audioSession);
    140 
    141     // types of io configuration change events received with ioConfigChanged()
    142     enum io_config_event {
    143         OUTPUT_OPENED,
    144         OUTPUT_CLOSED,
    145         OUTPUT_CONFIG_CHANGED,
    146         INPUT_OPENED,
    147         INPUT_CLOSED,
    148         INPUT_CONFIG_CHANGED,
    149         STREAM_CONFIG_CHANGED,
    150         NUM_CONFIG_EVENTS
    151     };
    152 
    153     // audio output descriptor used to cache output configurations in client process to avoid
    154     // frequent calls through IAudioFlinger
    155     class OutputDescriptor {
    156     public:
    157         OutputDescriptor()
    158         : samplingRate(0), format(AUDIO_FORMAT_DEFAULT), channelMask(0), frameCount(0), latency(0)  {}
    159 
    160         uint32_t samplingRate;
    161         audio_format_t format;
    162         audio_channel_mask_t channelMask;
    163         size_t frameCount;
    164         uint32_t latency;
    165     };
    166 
    167     // Events used to synchronize actions between audio sessions.
    168     // For instance SYNC_EVENT_PRESENTATION_COMPLETE can be used to delay recording start until
    169     // playback is complete on another audio session.
    170     // See definitions in MediaSyncEvent.java
    171     enum sync_event_t {
    172         SYNC_EVENT_SAME = -1,             // used internally to indicate restart with same event
    173         SYNC_EVENT_NONE = 0,
    174         SYNC_EVENT_PRESENTATION_COMPLETE,
    175 
    176         //
    177         // Define new events here: SYNC_EVENT_START, SYNC_EVENT_STOP, SYNC_EVENT_TIME ...
    178         //
    179         SYNC_EVENT_CNT,
    180     };
    181 
    182     // Timeout for synchronous record start. Prevents from blocking the record thread forever
    183     // if the trigger event is not fired.
    184     static const uint32_t kSyncRecordStartTimeOutMs = 30000;
    185 
    186     //
    187     // IAudioPolicyService interface (see AudioPolicyInterface for method descriptions)
    188     //
    189     static status_t setDeviceConnectionState(audio_devices_t device, audio_policy_dev_state_t state,
    190                                                 const char *device_address);
    191     static audio_policy_dev_state_t getDeviceConnectionState(audio_devices_t device,
    192                                                                 const char *device_address);
    193     static status_t setPhoneState(audio_mode_t state);
    194     static status_t setForceUse(audio_policy_force_use_t usage, audio_policy_forced_cfg_t config);
    195     static audio_policy_forced_cfg_t getForceUse(audio_policy_force_use_t usage);
    196     static audio_io_handle_t getOutput(audio_stream_type_t stream,
    197                                         uint32_t samplingRate = 0,
    198                                         audio_format_t format = AUDIO_FORMAT_DEFAULT,
    199                                         audio_channel_mask_t channelMask = AUDIO_CHANNEL_OUT_STEREO,
    200                                         audio_output_flags_t flags = AUDIO_OUTPUT_FLAG_NONE,
    201                                         const audio_offload_info_t *offloadInfo = NULL);
    202     static status_t startOutput(audio_io_handle_t output,
    203                                 audio_stream_type_t stream,
    204                                 int session = 0);
    205     static status_t stopOutput(audio_io_handle_t output,
    206                                audio_stream_type_t stream,
    207                                int session = 0);
    208     static void releaseOutput(audio_io_handle_t output);
    209     static audio_io_handle_t getInput(audio_source_t inputSource,
    210                                     uint32_t samplingRate = 0,
    211                                     audio_format_t format = AUDIO_FORMAT_DEFAULT,
    212                                     audio_channel_mask_t channelMask = AUDIO_CHANNEL_IN_MONO,
    213                                     int sessionId = 0);
    214     static status_t startInput(audio_io_handle_t input);
    215     static status_t stopInput(audio_io_handle_t input);
    216     static void releaseInput(audio_io_handle_t input);
    217     static status_t initStreamVolume(audio_stream_type_t stream,
    218                                       int indexMin,
    219                                       int indexMax);
    220     static status_t setStreamVolumeIndex(audio_stream_type_t stream,
    221                                          int index,
    222                                          audio_devices_t device);
    223     static status_t getStreamVolumeIndex(audio_stream_type_t stream,
    224                                          int *index,
    225                                          audio_devices_t device);
    226 
    227     static uint32_t getStrategyForStream(audio_stream_type_t stream);
    228     static audio_devices_t getDevicesForStream(audio_stream_type_t stream);
    229 
    230     static audio_io_handle_t getOutputForEffect(const effect_descriptor_t *desc);
    231     static status_t registerEffect(const effect_descriptor_t *desc,
    232                                     audio_io_handle_t io,
    233                                     uint32_t strategy,
    234                                     int session,
    235                                     int id);
    236     static status_t unregisterEffect(int id);
    237     static status_t setEffectEnabled(int id, bool enabled);
    238 
    239     // clear stream to output mapping cache (gStreamOutputMap)
    240     // and output configuration cache (gOutputs)
    241     static void clearAudioConfigCache();
    242 
    243     static const sp<IAudioPolicyService>& get_audio_policy_service();
    244 
    245     // helpers for android.media.AudioManager.getProperty(), see description there for meaning
    246     static uint32_t getPrimaryOutputSamplingRate();
    247     static size_t getPrimaryOutputFrameCount();
    248 
    249     static status_t setLowRamDevice(bool isLowRamDevice);
    250 
    251     // Check if hw offload is possible for given format, stream type, sample rate,
    252     // bit rate, duration, video and streaming or offload property is enabled
    253     static bool isOffloadSupported(const audio_offload_info_t& info);
    254 
    255     // check presence of audio flinger service.
    256     // returns NO_ERROR if binding to service succeeds, DEAD_OBJECT otherwise
    257     static status_t checkAudioFlinger();
    258     // ----------------------------------------------------------------------------
    259 
    260 private:
    261 
    262     class AudioFlingerClient: public IBinder::DeathRecipient, public BnAudioFlingerClient
    263     {
    264     public:
    265         AudioFlingerClient() {
    266         }
    267 
    268         // DeathRecipient
    269         virtual void binderDied(const wp<IBinder>& who);
    270 
    271         // IAudioFlingerClient
    272 
    273         // indicate a change in the configuration of an output or input: keeps the cached
    274         // values for output/input parameters up-to-date in client process
    275         virtual void ioConfigChanged(int event, audio_io_handle_t ioHandle, const void *param2);
    276     };
    277 
    278     class AudioPolicyServiceClient: public IBinder::DeathRecipient
    279     {
    280     public:
    281         AudioPolicyServiceClient() {
    282         }
    283 
    284         // DeathRecipient
    285         virtual void binderDied(const wp<IBinder>& who);
    286     };
    287 
    288     static sp<AudioFlingerClient> gAudioFlingerClient;
    289     static sp<AudioPolicyServiceClient> gAudioPolicyServiceClient;
    290     friend class AudioFlingerClient;
    291     friend class AudioPolicyServiceClient;
    292 
    293     static Mutex gLock;
    294     static sp<IAudioFlinger> gAudioFlinger;
    295     static audio_error_callback gAudioErrorCallback;
    296 
    297     static size_t gInBuffSize;
    298     // previous parameters for recording buffer size queries
    299     static uint32_t gPrevInSamplingRate;
    300     static audio_format_t gPrevInFormat;
    301     static audio_channel_mask_t gPrevInChannelMask;
    302 
    303     static sp<IAudioPolicyService> gAudioPolicyService;
    304 
    305     // mapping between stream types and outputs
    306     static DefaultKeyedVector<audio_stream_type_t, audio_io_handle_t> gStreamOutputMap;
    307     // list of output descriptors containing cached parameters
    308     // (sampling rate, framecount, channel count...)
    309     static DefaultKeyedVector<audio_io_handle_t, OutputDescriptor *> gOutputs;
    310 };
    311 
    312 };  // namespace android
    313 
    314 #endif  /*ANDROID_AUDIOSYSTEM_H_*/
    315