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 // AudioConverter is a complete mixing, resampling, buffering, and channel 6 // mixing solution for converting data from one set of AudioParameters to 7 // another. 8 // 9 // For efficiency, pieces are only invoked when necessary; i.e., 10 // - The resampler is only used if sample rates differ. 11 // - The FIFO is only used if buffer sizes differ. 12 // - The channel mixer is only used if channel layouts differ. 13 // 14 // Additionally, since resampling is the most expensive operation, input mixing 15 // and channel down mixing are done prior to resampling. Likewise, channel up 16 // mixing is performed after resampling. 17 18 #ifndef MEDIA_BASE_AUDIO_CONVERTER_H_ 19 #define MEDIA_BASE_AUDIO_CONVERTER_H_ 20 21 #include <list> 22 23 #include "base/callback.h" 24 #include "base/memory/scoped_ptr.h" 25 #include "base/time/time.h" 26 #include "media/audio/audio_parameters.h" 27 #include "media/base/media_export.h" 28 29 namespace media { 30 31 class AudioBus; 32 class AudioPullFifo; 33 class ChannelMixer; 34 class MultiChannelResampler; 35 36 // Converts audio data between two AudioParameters formats. Sample usage: 37 // AudioParameters input(...), output(...); 38 // AudioConverter ac(input, output); 39 // scoped_ptr<AudioBus> output_audio_bus = AudioBus::Create(output); 40 // ac.AddInput(<AudioConverter::InputCallback* 1>); 41 // ac.AddInput(<AudioConverter::InputCallback* 2>); 42 // ac.Convert(output_audio_bus.get()); 43 // 44 // Convert() will ask for input audio data from each InputCallback and convert 45 // the data into the provided AudioBus. 46 class MEDIA_EXPORT AudioConverter { 47 public: 48 // Interface for inputs into the converter. Each InputCallback is added or 49 // removed from Convert() processing via AddInput() and RemoveInput(). 50 class MEDIA_EXPORT InputCallback { 51 public: 52 // Method for providing more data into the converter. Expects |audio_bus| 53 // to be completely filled with data upon return; zero padded if not enough 54 // frames are available to satisfy the request. The return value is the 55 // volume level of the provided audio data. If a volume level of zero is 56 // returned no further processing will be done on the provided data, else 57 // the volume level will be used to scale the provided audio data. 58 virtual double ProvideInput(AudioBus* audio_bus, 59 base::TimeDelta buffer_delay) = 0; 60 61 protected: ~InputCallback()62 virtual ~InputCallback() {} 63 }; 64 65 // Constructs an AudioConverter for converting between the given input and 66 // output parameters. Specifying |disable_fifo| means all InputCallbacks are 67 // capable of handling arbitrary buffer size requests; i.e. one call might ask 68 // for 10 frames of data (indicated by the size of AudioBus provided) and the 69 // next might ask for 20. In synthetic testing, disabling the FIFO yields a 70 // ~20% speed up for common cases. 71 AudioConverter(const AudioParameters& input_params, 72 const AudioParameters& output_params, 73 bool disable_fifo); 74 ~AudioConverter(); 75 76 // Converts audio from all inputs into the |dest|. If an |initial_delay| is 77 // specified, it will be propagated to each input. 78 void Convert(AudioBus* dest); 79 void ConvertWithDelay(const base::TimeDelta& initial_delay, AudioBus* dest); 80 81 // Adds or removes an input from the converter. RemoveInput() will call 82 // Reset() if no inputs remain after the specified input is removed. 83 void AddInput(InputCallback* input); 84 void RemoveInput(InputCallback* input); 85 86 // Flushes all buffered data. 87 void Reset(); 88 89 // The maximum size in frames that guarantees we will only make a single call 90 // to each input's ProvideInput for more data. 91 int ChunkSize() const; 92 empty()93 bool empty() const { return transform_inputs_.empty(); } 94 95 private: 96 // Provides input to the MultiChannelResampler. Called by the resampler when 97 // more data is necessary. 98 void ProvideInput(int resampler_frame_delay, AudioBus* audio_bus); 99 100 // Provides input to the AudioPullFifo. Called by the fifo when more data is 101 // necessary. 102 void SourceCallback(int fifo_frame_delay, AudioBus* audio_bus); 103 104 // (Re)creates the temporary |unmixed_audio_| buffer if necessary. 105 void CreateUnmixedAudioIfNecessary(int frames); 106 107 // Set of inputs for Convert(). 108 typedef std::list<InputCallback*> InputCallbackSet; 109 InputCallbackSet transform_inputs_; 110 111 // Used to buffer data between the client and the output device in cases where 112 // the client buffer size is not the same as the output device buffer size. 113 scoped_ptr<AudioPullFifo> audio_fifo_; 114 int chunk_size_; 115 116 // Handles resampling. 117 scoped_ptr<MultiChannelResampler> resampler_; 118 119 // Handles channel transforms. |unmixed_audio_| is a temporary destination 120 // for audio data before it goes into the channel mixer. 121 scoped_ptr<ChannelMixer> channel_mixer_; 122 scoped_ptr<AudioBus> unmixed_audio_; 123 124 // Temporary AudioBus destination for mixing inputs. 125 scoped_ptr<AudioBus> mixer_input_audio_bus_; 126 127 // Since resampling is expensive, figure out if we should downmix channels 128 // before resampling. 129 bool downmix_early_; 130 131 // Used to calculate buffer delay information for InputCallbacks. 132 base::TimeDelta input_frame_duration_; 133 base::TimeDelta output_frame_duration_; 134 base::TimeDelta initial_delay_; 135 int resampler_frame_delay_; 136 137 // Number of channels of input audio data. Set during construction via the 138 // value from the input AudioParameters class. Preserved to recreate internal 139 // AudioBus structures on demand in response to varying frame size requests. 140 const int input_channel_count_; 141 142 DISALLOW_COPY_AND_ASSIGN(AudioConverter); 143 }; 144 145 } // namespace media 146 147 #endif // MEDIA_BASE_AUDIO_CONVERTER_H_ 148