src/media/audio/audio_io.h

   1 // Copyright (c) 2012 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MEDIA_AUDIO_AUDIO_IO_H_
   6 #define MEDIA_AUDIO_AUDIO_IO_H_
   7
   8 #if defined(OS_TIZEN)
   9 #include <string>
  10 #endif
  11
  12 #include "base/basictypes.h"
  13 #include "media/audio/audio_buffers_state.h"
  14 #include "media/base/audio_bus.h"
  15
  16 // Low-level audio output support. To make sound there are 3 objects involved:
  17 // - AudioSource : produces audio samples on a pull model. Implements
  18 //   the AudioSourceCallback interface.
  19 // - AudioOutputStream : uses the AudioSource to render audio on a given
  20 //   channel, format and sample frequency configuration. Data from the
  21 //   AudioSource is delivered in a 'pull' model.
  22 // - AudioManager : factory for the AudioOutputStream objects, manager
  23 //   of the hardware resources and mixer control.
  24 //
  25 // The number and configuration of AudioOutputStream does not need to match the
  26 // physically available hardware resources. For example you can have:
  27 //
  28 //  MonoPCMSource1 --> MonoPCMStream1 --> |       | --> audio left channel
  29 //  StereoPCMSource -> StereoPCMStream -> | mixer |
  30 //  MonoPCMSource2 --> MonoPCMStream2 --> |       | --> audio right channel
  31 //
  32 // This facility's objective is mix and render audio with low overhead using
  33 // the OS basic audio support, abstracting as much as possible the
  34 // idiosyncrasies of each platform. Non-goals:
  35 // - Positional, 3d audio
  36 // - Dependence on non-default libraries such as DirectX 9, 10, XAudio
  37 // - Digital signal processing or effects
  38 // - Extra features if a specific hardware is installed (EAX, X-fi)
  39 //
  40 // The primary client of this facility is audio coming from several tabs.
  41 // Specifically for this case we avoid supporting complex formats such as MP3
  42 // or WMA. Complex format decoding should be done by the renderers.
  43
  44
  45 // Models an audio stream that gets rendered to the audio hardware output.
  46 // Because we support more audio streams than physically available channels
  47 // a given AudioOutputStream might or might not talk directly to hardware.
  48 // An audio stream allocates several buffers for audio data and calls
  49 // AudioSourceCallback::OnMoreData() periodically to fill these buffers,
  50 // as the data is written to the audio device. Size of each packet is determined
  51 // by |samples_per_packet| specified in AudioParameters  when the stream is
  52 // created.
  53
  54 namespace media {
  55
  56 class MEDIA_EXPORT AudioOutputStream {
  57  public:
  58   // Audio sources must implement AudioSourceCallback. This interface will be
  59   // called in a random thread which very likely is a high priority thread. Do
  60   // not rely on using this thread TLS or make calls that alter the thread
  61   // itself such as creating Windows or initializing COM.
  62   class MEDIA_EXPORT AudioSourceCallback {
  63    public:
  64     // Provide more data by fully filling |dest|.  The source will return
  65     // the number of frames it filled.  |buffers_state| contains current state
  66     // of the buffers, and can be used by the source to calculate delay.
  67     virtual int OnMoreData(AudioBus* dest,
  68                            AudioBuffersState buffers_state) = 0;
  69
  70     // There was an error while playing a buffer. Audio source cannot be
  71     // destroyed yet. No direct action needed by the AudioStream, but it is
  72     // a good place to stop accumulating sound data since is is likely that
  73     // playback will not continue.
  74     virtual void OnError(AudioOutputStream* stream) = 0;
  75
  76    protected:
  77     virtual ~AudioSourceCallback() {}
  78   };
  79
  80   virtual ~AudioOutputStream() {}
  81
  82   // Open the stream. false is returned if the stream cannot be opened.  Open()
  83   // must always be followed by a call to Close() even if Open() fails.
  84   virtual bool Open() = 0;
  85
  86   // Starts playing audio and generating AudioSourceCallback::OnMoreData().
  87   // Since implementor of AudioOutputStream may have internal buffers, right
  88   // after calling this method initial buffers are fetched.
  89   //
  90   // The output stream does not take ownership of this callback.
  91   virtual void Start(AudioSourceCallback* callback) = 0;
  92
  93   // Stops playing audio. Effect might not be instantaneous as the hardware
  94   // might have locked audio data that is processing.
  95   virtual void Stop() = 0;
  96
  97   // Sets the relative volume, with range [0.0, 1.0] inclusive.
  98   virtual void SetVolume(double volume) = 0;
  99
 100   // Gets the relative volume, with range [0.0, 1.0] inclusive.
 101   virtual void GetVolume(double* volume) = 0;
 102
 103   // Close the stream. This also generates AudioSourceCallback::OnClose().
 104   // After calling this method, the object should not be used anymore.
 105   virtual void Close() = 0;
 106
 107 #if defined(OS_TIZEN)
 108   // Sets an application ID and class properties, which are used to tag audio
 109   // streams in pulseaudio/Murphy.
 110   virtual void SetMediaStreamProperties(const std::string& app_id,
 111                                         const std::string& app_class) {}
 112 #endif
 113 };
 114
 115 // Models an audio sink receiving recorded audio from the audio driver.
 116 class MEDIA_EXPORT AudioInputStream {
 117  public:
 118   class MEDIA_EXPORT AudioInputCallback {
 119    public:
 120     // Called by the audio recorder when a full packet of audio data is
 121     // available. This is called from a special audio thread and the
 122     // implementation should return as soon as possible.
 123     // TODO(henrika): should be pure virtual when old OnData() is phased out.
 124     virtual void OnData(AudioInputStream* stream,
 125                         const AudioBus* source,
 126                         uint32 hardware_delay_bytes,
 127                         double volume) {};
 128
 129     // TODO(henrika): don't use; to be removed.
 130     virtual void OnData(AudioInputStream* stream,
 131                         const uint8* src,
 132                         uint32 size,
 133                         uint32 hardware_delay_bytes,
 134                         double volume) {};
 135
 136     // There was an error while recording audio. The audio sink cannot be
 137     // destroyed yet. No direct action needed by the AudioInputStream, but it
 138     // is a good place to stop accumulating sound data since is is likely that
 139     // recording will not continue.
 140     virtual void OnError(AudioInputStream* stream) = 0;
 141
 142    protected:
 143     virtual ~AudioInputCallback() {}
 144   };
 145
 146   virtual ~AudioInputStream() {}
 147
 148   // Open the stream and prepares it for recording. Call Start() to actually
 149   // begin recording.
 150   virtual bool Open() = 0;
 151
 152   // Starts recording audio and generating AudioInputCallback::OnData().
 153   // The input stream does not take ownership of this callback.
 154   virtual void Start(AudioInputCallback* callback) = 0;
 155
 156   // Stops recording audio. Effect might not be instantaneous as there could be
 157   // pending audio callbacks in the queue which will be issued first before
 158   // recording stops.
 159   virtual void Stop() = 0;
 160
 161   // Close the stream. This also generates AudioInputCallback::OnClose(). This
 162   // should be the last call made on this object.
 163   virtual void Close() = 0;
 164
 165   // Returns the maximum microphone analog volume or 0.0 if device does not
 166   // have volume control.
 167   virtual double GetMaxVolume() = 0;
 168
 169   // Sets the microphone analog volume, with range [0, max_volume] inclusive.
 170   virtual void SetVolume(double volume) = 0;
 171
 172   // Returns the microphone analog volume, with range [0, max_volume] inclusive.
 173   virtual double GetVolume() = 0;
 174
 175   // Sets the Automatic Gain Control (AGC) state.
 176   virtual void SetAutomaticGainControl(bool enabled) = 0;
 177
 178   // Returns the Automatic Gain Control (AGC) state.
 179   virtual bool GetAutomaticGainControl() = 0;
 180
 181   // Returns the current muting state for the microphone.
 182   virtual bool IsMuted() = 0;
 183 };
 184
 185 }  // namespace media
 186
 187 #endif  // MEDIA_AUDIO_AUDIO_IO_H_