2 // Open Service Platform
3 // Copyright (c) 2012 Samsung Electronics Co., Ltd.
5 // Licensed under the Apache License, Version 2.0 (the License);
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
19 * @file FMediaAudioIn.h
20 * @brief This is the header file for the %AudioIn class.
22 * This header file contains the declarations of the %AudioIn class.
25 #ifndef _FMEDIA_AUDIO_IN_H_
26 #define _FMEDIA_AUDIO_IN_H_
28 #include <FMediaAudioTypes.h>
29 #include <FMediaIAudioInEventListener.h>
31 namespace Tizen { namespace Media
35 * @brief This class records directly from an audio device.
39 * The %AudioIn class records directly from an audio device by providing methods for capturing PCM data from an audio input device.
40 * An application can capture audio data with the help of an event listener after preparing the %AudioIn class
41 * with proper channel count, sample type, and sampling rate.
42 * To minimize the overhead of the %AudioIn class,
43 * it is recommended that you use optimal channel type, sample type, and sampling rate.
44 * These can be retrieved with GetOptimizedChannelType(), GetOptimizedSampleType()
45 * and GetOptimizedSampleRate().
47 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/media/recording_pcm_audio.htm">Recording PCM Audio</a>.
49 * The following example demonstrates how to use the %AudioIn class.
57 * using namespace Tizen::Base;
58 * using namespace Tizen::Io;
59 * using namespace Tizen::Media;
61 * #define MAX_BUFFER_COUNT 3
64 * : public Tizen::Media::IAudioInEventListener
71 * virtual void OnAudioInBufferIsFilled( Tizen::Base::ByteBuffer* pData);
72 * virtual void OnAudioInErrorOccurred(result r) {}
73 * virtual void OnAudioInInterrupted(void) {}
74 * virtual void OnAudioInReleased(void) {}
75 * virtual void OnAudioInAudioFocusChanged(void) {}
79 * ByteBuffer __buffer[MAX_BUFFER_COUNT];
83 * AudioInSample::Start(void)
87 * AudioInputDevice inputDevice = AUDIO_INPUT_DEVICE_MIC;
88 * AudioSampleType sampleType = AUDIO_TYPE_PCM_U8;
89 * AudioChannelType channelType = AUDIO_CHANNEL_TYPE_STEREO;
90 * int sampleRate = 8000;
92 * // Constructs an AudioIn instance
93 * r = __audioIn.Construct(*this);
99 * // Prepares the AudioIn instance
100 * r = __audioIn.Prepare(inputDevice, sampleType, channelType, sampleRate);
106 * minBufferSize = __audioIn.GetMinBufferSize();
108 * for (int i = 0; i < MAX_BUFFER_COUNT; i++)
110 * // Prepares buffers to store PCM data
111 * r = __buffer[i].Construct(minBufferSize);
116 * // Adds buffer to the __audioIn
117 * __audioIn.AddBuffer(&__buffer[i]);
124 * // Starts capturing
125 * r = __audioIn.Start();
135 * AudioInSample::Stop(void)
137 * // Stops and unprepares the __audioIn
139 * __audioIn.Unprepare();
143 * AudioInSample::OnAudioInBufferIsFilled( Tizen::Base::ByteBuffer* pData)
145 * // Consumes filled data here
147 * // Clears the buffer
150 * // Adds the byte buffer to the __audioIn to fill data again
151 * __audioIn.AddBuffer(pData);
159 class _OSP_EXPORT_ AudioIn
160 : public Tizen::Base::Object
164 * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
168 * @remarks After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
173 * This destructor overrides Tizen::Base::Object::~Object().
174 * All allocated resources are deallocated with this method. @n
175 * This method must be called in the same thread as the Construct() method.
181 virtual ~AudioIn(void);
184 * Initializes this instance of %AudioIn with the specified IAudioInEventListener. @n
185 * The %Construct() method creates an instance of %AudioIn in the subsystem.
189 * @return An error code
190 * @param[in] listener An instance of IAudioInEventListener
191 * @exception E_SUCCESS The method is successful.
192 * @exception E_DEVICE_BUSY The device cannot be approached because of other operations.
193 * @exception E_UNSUPPORTED_OPERATION This operation is not supported.
194 * @exception E_OUT_OF_MEMORY The memory is insufficient.
195 * @exception E_SYSTEM A system error has occurred.
196 * @remarks Only one instance of %AudioIn is operational at a given time.
198 result Construct(IAudioInEventListener& listener);
202 * Prepares the specified audio input device with the application-defined settings. @n
203 * When the caller finishes using the audio input device, the resources must be released by calling the Unprepare() method.
205 * @brief <i> [Deprecated] </i>
206 * @deprecated This method is deprecated because AudioInputDevice is no longer used in %AudioIn class. @n
207 * Instead of using this method, use Prepare(AudioSampleType audioSampleType, AudioChannelType audioChannelType, int audioSampleRate).
211 * @return An error code
212 * @param[in] audioInputDevice An audio input device
213 * @param[in] audioSampleType The type of audio sample
214 * @param[in] audioChannelType The audio channel type
215 * @param[in] audioSampleRate The audio sample rate in Hertz (Hz)
216 * @exception E_SUCCESS The method is successful.
217 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
218 * @exception E_SYSTEM A system error has occurred.
219 * @exception E_INVALID_ARG A specified input parameter is invalid.
220 * @exception E_UNSUPPORTED_FORMAT The specified audio sample type is not supported.
223 result Prepare(AudioInputDevice audioInputDevice, AudioSampleType audioSampleType, AudioChannelType audioChannelType, int audioSampleRate);
226 * Prepares the specified audio input device with the application-defined settings. @n
227 * When the caller finishes using the audio input device, the resources must be released by calling the Unprepare() method.
231 * @return An error code
232 * @param[in] audioSampleType The type of audio sample
233 * @param[in] audioChannelType The audio channel type
234 * @param[in] audioSampleRate The audio sample rate in Hertz (Hz)
235 * @exception E_SUCCESS The method is successful.
236 * @exception E_DEVICE_FAILED The device failed with unknown reason.
237 * @exception E_INVALID_ARG A specified input parameter is invalid.
238 * @exception E_UNSUPPORTED_FORMAT The specified audio sample type is not supported.
240 result Prepare(AudioSampleType audioSampleType, AudioChannelType audioChannelType, int audioSampleRate);
243 * Stops the usage of the input device and releases the allocated resources during the execution of the Prepare() method. @n
244 * Resources allocated during %Prepare() are released.
248 * @return An error code
249 * @exception E_SUCCESS The method is successful.
250 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
251 * @exception E_SYSTEM A system error has occurred.
253 result Unprepare(void);
256 * Adds an input buffer to the specified audio input device. @n
257 * When the buffer is filled, the %AudioIn class returns the buffer to the caller
258 * by invoking IAudioInEventListener::OnAudioInBufferIsFilled().
262 * @return An error code
263 * @param[in] pByteBuffer A pointer to the buffer
264 * @exception E_SUCCESS The method is successful.
265 * @exception E_INVALID_ARG The input parameter is invalid.
266 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
267 * @exception E_SYSTEM A system error has occurred.
268 * @exception E_OUT_OF_MEMORY The memory is insufficient.
269 * @remarks The data size of @c pByteBuffer must be the same as every call of this method.
271 * @see IAudioInEventListener::OnAudioInBufferIsFilled()
273 result AddBuffer(const Tizen::Base::ByteBuffer* pByteBuffer);
276 * Starts reading the audio data from an audio input device and fills the data into the buffer.
280 * @return An error code
281 * @exception E_SUCCESS The method is successful.
282 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
283 * @exception E_DEVICE_BUSY The device cannot be approached because of other operations.
284 * @exception E_SYSTEM A system error has occurred.
285 * @remarks Several buffers must be added to the queue with AddBuffer() before calling this method.
287 * @see IAudioInEventListener::OnAudioInBufferIsFilled()
292 * Stops using the audio input device. @n
293 * All pending and current buffers that are filled with audio data
294 * at the time of calling the %Stop() method, are returned to the listener.
295 * Use Start() to start capturing audio input data again.
299 * @return An error code
300 * @exception E_SUCCESS The method is successful.
301 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
302 * @exception E_SYSTEM A system error has occurred.
303 * @see IAudioInEventListener::OnAudioInBufferIsFilled()
308 * Resets using the audio input device without returning buffers to the caller. @n
309 * All pending and current buffers are released immediately without any notifications.
310 * The state is changed to @c AUDIOIN_STATE_PREPARED.
314 * @return An error code
315 * @exception E_SUCCESS The method is successful.
316 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
317 * @exception E_SYSTEM A system error has occurred.
322 * Gets the current state of this instance.
326 * @return The state of this instance
327 * @exception E_SUCCESS The method is successful.
328 * @exception E_SYSTEM A system error has occurred.
329 * @remarks The specific error code can be accessed using the GetLastResult() method.
331 AudioInState GetState(void) const;
334 * Gets the maximum size of the buffer that can be used with AddBuffer(). @n
335 * This maximum value is set by Prepare() and reset to @c 0 by Unprepare().
339 * @return The maximum size of the buffer in bytes, @n
340 * else @c -1 if an error occurs
341 * @exception E_SUCCESS The method is successful.
342 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
343 * @exception E_SYSTEM A system error has occurred.
344 * @remarks The return value is available after calling the Prepare() method.
345 * @remarks The specific error code can be accessed using the GetLastResult() method.
347 int GetMaxBufferSize(void) const;
350 * Gets the minimum size of the buffer that can be used with AddBuffer(). @n
351 * This minimum value is set by Prepare() and reset to @c 0 by Unprepare().
355 * @return The minimum size of the buffer in bytes, @n
356 * else @c -1 if an error occurs
357 * @exception E_SUCCESS The method is successful.
358 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
359 * @exception E_SYSTEM A system error has occurred.
360 * @remarks The return value is available after calling the Prepare() method.
361 * @remarks The specific error code can be accessed using the GetLastResult() method.
363 int GetMinBufferSize(void) const;
366 * Gets the optimized sample type of the audio input device.
370 * @return The audio encoding type
371 * @exception E_SUCCESS The method is successful.
372 * @exception E_SYSTEM A system error has occurred.
373 * @remarks The specific error code can be accessed using the GetLastResult() method.
375 AudioSampleType GetOptimizedSampleType(void) const;
378 * Gets the optimized channel type of the audio input device.
382 * @return The audio channel type
383 * @exception E_SUCCESS The method is successful.
384 * @exception E_SYSTEM A system error has occurred.
385 * @remarks The specific error code can be accessed using the GetLastResult() method.
387 AudioChannelType GetOptimizedChannelType(void) const;
390 * Gets the optimized sample rate of the audio input device.
394 * @return The sample rate in Hertz (Hz)
395 * @exception E_SUCCESS The method is successful.
396 * @exception E_SYSTEM A system error has occurred.
397 * @remarks The specific error code can be accessed using the GetLastResult() method.
399 int GetOptimizedSampleRate(void) const;
404 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
408 AudioIn(const AudioIn& rhs);
411 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
415 AudioIn& operator =(const AudioIn& rhs);
417 friend class _AudioInImpl;
418 class _AudioInImpl* __pAudioInImpl;