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 FMediaAudioOut.h
20 * @brief This is the header file for the %AudioOut class.
22 * This header file contains the declarations of the %AudioOut class.
25 #ifndef _FMEDIA_AUDIO_OUT_H_
26 #define _FMEDIA_AUDIO_OUT_H_
28 #include <FBaseByteBuffer.h>
29 #include <FMediaAudioTypes.h>
30 #include <FMediaAudioManagerTypes.h>
31 #include <FMediaIAudioOutEventListener.h>
33 namespace Tizen { namespace Media
38 * @brief This class plays raw audio data.
43 * The maximum number of %AudioOut instances is limited by Media::MediaCapability class. This number is a system wide count so that the application must not be able to construct more instances than the maximum number permitted.
45 * The %AudioOut class plays raw audio data and provides methods for:
46 * - Playing PCM data in various audio sample types
47 * - Controlling volume
49 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/media/playing_pcm_audio.htm">Playing PCM Audio</a>.
51 * The following example demonstrates how to use the %AudioOut class.
60 * using namespace Tizen::Base;
61 * using namespace Tizen::Io;
62 * using namespace Tizen::Media;
64 * #define MAX_BUFFER_COUNT 3
66 * class AudioOutSample
67 * : public Tizen::Media::IAudioOutEventListener
74 * virtual void OnAudioOutBufferEndReached(Tizen::Media::AudioOut& src);
75 * virtual void OnAudioOutErrorOccurred(Tizen::Media::AudioOut& src, result r) {}
76 * virtual void OnAudioOutInterrupted(Tizen::Media::AudioOut& src) {}
77 * virtual void OnAudioOutReleased(Tizen::Media::AudioOut& src) {}
78 * virtual void OnAudioOutAudioFocusChanged(Tizen::Media::AudioOut& src) {}
81 * AudioOut __audioOut;
83 * ByteBuffer __buffer[MAX_BUFFER_COUNT];
88 * AudioOutSample::Start(void)
90 * FileAttributes attr;
91 * String filePath = Tizen::App::App::GetInstance()->GetAppRootPath() + L"data/test.pcm";
95 * // Opens the input file
96 * __file.Construct(filePath, L"rb");
98 * // Constructs the AudioOut instance with a listener
99 * r = __audioOut.Construct(*this);
105 * // Prepares the AudioOut instance
106 * // Considers the input data as signed 16-bit, stereo, 44100 Hz PCM data
107 * __audioOut.Prepare(AUDIO_TYPE_PCM_S16_LE, AUDIO_CHANNEL_TYPE_STEREO, 44100);
108 * minBufferSize = __audioOut.GetMinBufferSize();
110 * // Constructs the pcm buffer and enqueue the buffer to the __audioOut
111 * for (int i = 0; i < MAX_BUFFER_COUNT; i++)
113 * __buffer[i].Construct(minBufferSize);
114 * __file.Read(__buffer[i]);
115 * __audioOut.WriteBuffer(__buffer[i]);
120 * r = __audioOut.Start();
130 * AudioOutSample::Stop(void)
133 * __audioOut.Unprepare();
137 * AudioOutSample::OnAudioOutBufferEndReached(Tizen::Media::AudioOut& src)
139 * result r = E_SUCCESS;
141 * r = __file.Read(__buffer[__bufIndex % MAX_BUFFER_COUNT]);
144 * // Handles end of file event
149 * src.WriteBuffer(__buffer[__bufIndex % MAX_BUFFER_COUNT]);
157 class _OSP_EXPORT_ AudioOut
158 : public Tizen::Base::Object
162 * 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.
166 * @remarks After creating an instance of this class, the Construct() method must be called explicitly to initialize this instance.
171 * This destructor overrides Tizen::Base::Object::~Object().
172 * All allocated resources are released by this method.
173 * This method must be called in the same thread as the Construct() method.
179 virtual ~AudioOut(void);
183 * Initializes this instance of %AudioOut with the specified listener.
187 * @return An error code
188 * @param[in] listener An instance of IAudioOutEventListener
189 * @exception E_SUCCESS The method is successful.
190 * @exception E_SYSTEM A system error has occurred.
191 * @exception E_OUT_OF_MEMORY The memory is insufficient.
192 * @exception E_RESOURCE_UNAVAILABLE The %AudioOut's resources are unavailable.
194 result Construct(IAudioOutEventListener& listener);
197 * Prepares an audio output device with the defined settings.
201 * @return An error code
202 * @param[in] audioSampleType The type of the audio sample
203 * @param[in] audioChannelType The type of the audio channel
204 * @param[in] audioSampleRate The audio sample rate in Hertz (Hz)
205 * @exception E_SUCCESS The method is successful.
206 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
207 * @exception E_SYSTEM A system error has occurred.
208 * @exception E_INVALID_ARG A specified input parameter is invalid.
209 * @exception E_UNSUPPORTED_FORMAT The specified audio sample type is not supported.
212 result Prepare(AudioSampleType audioSampleType, AudioChannelType audioChannelType, int audioSampleRate);
215 * Prepares an audio output device with the defined settings with the audio stream type.
219 * @return An error code
220 * @param[in] audioStreamType The type of the audio stream
221 * @param[in] audioSampleType The type of the audio sample
222 * @param[in] audioChannelType The type of the audio channel
223 * @param[in] audioSampleRate The audio sample rate in Hertz (Hz)
224 * @exception E_SUCCESS The method is successful.
225 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
226 * @exception E_DEVICE_FAILED The device failed with unknown reason.
227 * @exception E_INVALID_ARG A specified input parameter is invalid.
228 * @exception E_UNSUPPORTED_FORMAT The specified audio sample type is not supported.
231 result Prepare(AudioStreamType audioStreamType, AudioSampleType audioSampleType, AudioChannelType audioChannelType, int audioSampleRate);
234 * Closes the audio output device.
238 * @return An error code
239 * @exception E_SUCCESS The method is successful.
240 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
241 * @exception E_SYSTEM A system error has occurred.
244 result Unprepare(void);
247 * Writes into the data buffer containing the audio data to be played to this audio output device. @n
248 * When the end of the buffer is reached, the application gets the notification through IAudioOutEventListener.
252 * @return An error code
253 * @param[in] userData A pointer of the buffer containing the PCM data block
254 * @exception E_SUCCESS The method is successful.
255 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
256 * @exception E_SYSTEM A system error has occurred.
257 * @exception E_INVALID_ARG The specified input parameter is invalid.
258 * @exception E_OVERFLOW The specified input instance has overflowed.
260 * @see IAudioOutEventListener::OnAudioOutBufferEndReached()
262 result WriteBuffer(const Tizen::Base::ByteBuffer& userData);
265 * Starts the specified audio output device.
269 * @return An error code
270 * @exception E_SUCCESS The method is successful.
271 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
272 * @exception E_DEVICE_BUSY The device cannot be approached because of other operations.
273 * @exception E_SYSTEM A system error has occurred.
279 * Stops or pauses the playing of the audio output device. @n
280 * The current position of the playback is stored internally and the playback will restart from this position
281 * when Start() is called again.
285 * @return An error code
286 * @exception E_SUCCESS The method is successful.
287 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
288 * @exception E_SYSTEM A system error has occurred.
289 * @remarks Use Start() to resume the playback from the current playback position.
290 * @see IAudioOutEventListener::OnAudioOutBufferEndReached()
295 * Resets the audio output device. @n
296 * All pending and current data buffers in the queue are removed immediately without any notification. The
297 * state is changed to @c AUDIOOUT_STATE_PREPARED.
301 * @return An error code
302 * @exception E_SUCCESS The method is successful.
303 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
304 * @exception E_SYSTEM A system error has occurred.
309 * Gets the state of the current audio output device.
313 * @return The state of current audio output
314 * @exception E_SUCCESS The method is successful.
315 * @exception E_SYSTEM A system error has occurred.
316 * @remarks The specific error code can be accessed using the GetLastResult() method.
318 AudioOutState GetState(void) const;
321 * Gets the maximum size of buffer that can be used with WriteBuffer(). @n
322 * This maximum value is set by Prepare() and reset to @c 0 by Unprepare().
326 * @return The maximum size of buffer, @n
327 * else @c -1 if an error occurs
328 * @exception E_SUCCESS The method is successful.
329 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
330 * @exception E_SYSTEM A system error has occurred.
331 * @remarks The return value is available after calling the Prepare() method.
332 * @remarks The specific error code can be accessed using the GetLastResult() method.
334 int GetMaxBufferSize(void) const;
337 * Gets the minimum size of buffer that can be used with WriteBuffer(). @n
338 * This minimum value is set by Prepare() and reset to @c 0 by Unprepare().
342 * @return The minimum size of buffer, @n
343 * else @c -1 if an error occurs
344 * @exception E_SUCCESS The method is successful.
345 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
346 * @exception E_SYSTEM A system error has occurred.
347 * @remarks The return value is available after calling the Prepare() method.
348 * @remarks The specific error code can be accessed using the GetLastResult() method.
350 int GetMinBufferSize(void) const;
353 * Gets the optimized sample type of the audio output device.
357 * @return The audio encoding type
358 * @exception E_SUCCESS The method is successful.
359 * @exception E_SYSTEM A system error has occurred.
360 * @remarks The specific error code can be accessed using the GetLastResult() method.
362 AudioSampleType GetOptimizedSampleType(void) const;
365 * Gets the optimized channel type of the audio output device.
369 * @return The audio channel type
370 * @exception E_SUCCESS The method is successful.
371 * @exception E_SYSTEM A system error has occurred.
372 * @remarks The specific error code can be accessed using the GetLastResult() method.
374 AudioChannelType GetOptimizedChannelType(void) const;
377 * Gets the optimized sample rate of the audio output device.
381 * @return The sample rate in Hertz (Hz)
382 * @exception E_SUCCESS The method is successful.
383 * @exception E_SYSTEM A system error has occurred.
384 * @remarks The specific error code can be accessed using the GetLastResult() method.
386 int GetOptimizedSampleRate(void) const;
389 * Sets the volume level of the audio output device.
393 * @return An error code
394 * @param[in] volume The new value for volume @n
395 * The range of this parameter is from @c 0 to @c 100 and it is proportional to the current media sound volume level in setting.
396 * @exception E_SUCCESS The method is successful.
397 * @exception E_OUT_OF_RANGE The specified volume is out of range.
398 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
399 * @remarks This method must be called after Prepare().
402 result SetVolume(int volume);
405 * Gets the current volume level of this audio output.
409 * @return The current volume level, @n
410 * else @c -1 if an error occurs @n
411 * This return value ranges from @c 0 to @c 100.
412 * @exception E_SUCCESS The method is successful.
413 * @exception E_INVALID_STATE This instance is in an invalid state for this method.
414 * @remarks The specific error code can be accessed using the GetLastResult() method.
415 * @remarks This method must be called after calling the Prepare() method.
418 int GetVolume(void) const;
422 * The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
426 AudioOut(const AudioOut& rhs);
429 * The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
433 AudioOut& operator =(const AudioOut& rhs);
435 friend class _AudioOutImpl;
436 class _AudioOutImpl* __pAudioOutImpl;