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