2 * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 #ifndef __TIZEN_MEDIA_AUDIO_IO_H__
18 #define __TIZEN_MEDIA_AUDIO_IO_H__
20 #include <sys/types.h>
22 #include <sound_manager.h>
30 * @brief This file contains the Audio Input and Audio Output API.
34 * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
39 * @brief The audio input handle.
40 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
42 typedef struct audio_io_s *audio_in_h;
49 * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
54 * @brief The audio output handle.
55 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
57 typedef struct audio_io_s *audio_out_h;
64 * @addtogroup CAPI_MEDIA_AUDIO_IO_MODULE
69 * @brief Enumeration for audio sample type with bit depth.
70 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
73 AUDIO_SAMPLE_TYPE_U8 = 0x70, /**< Unsigned 8-bit audio samples */
74 AUDIO_SAMPLE_TYPE_S16_LE, /**< Signed 16-bit audio samples */
75 } audio_sample_type_e;
78 * @brief Enumeration for audio channel.
79 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
82 AUDIO_CHANNEL_MONO = 0x80, /**< 1 channel, mono */
83 AUDIO_CHANNEL_STEREO, /**< 2 channel, stereo */
87 * @brief Enumeration for audio input and output state.
91 AUDIO_IO_STATE_IDLE, /**< Audio-io handle is created, but not prepared */
92 AUDIO_IO_STATE_RUNNING, /**< Audio-io handle is ready and the stream is running */
93 AUDIO_IO_STATE_PAUSED, /**< Audio-io handle is ready and the stream is paused */
97 * @brief Enumeration for audio input and output error.
98 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
101 AUDIO_IO_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
102 AUDIO_IO_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
103 AUDIO_IO_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
104 AUDIO_IO_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION, /**< Invalid operation */
105 AUDIO_IO_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Device open error by security */
106 AUDIO_IO_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
107 AUDIO_IO_ERROR_DEVICE_POLICY_RESTRICTION = TIZEN_ERROR_DEVICE_POLICY_RESTRICTION, /**< Device policy restriction (Since 3.0) */
108 AUDIO_IO_ERROR_DEVICE_NOT_OPENED = TIZEN_ERROR_AUDIO_IO | 0x01, /**< Device open error */
109 AUDIO_IO_ERROR_DEVICE_NOT_CLOSED = TIZEN_ERROR_AUDIO_IO | 0x02, /**< Device close error */
110 AUDIO_IO_ERROR_INVALID_BUFFER = TIZEN_ERROR_AUDIO_IO | 0x03, /**< Invalid buffer pointer */
111 AUDIO_IO_ERROR_SOUND_POLICY = TIZEN_ERROR_AUDIO_IO | 0x04, /**< Sound policy error */
112 AUDIO_IO_ERROR_INVALID_STATE = TIZEN_ERROR_AUDIO_IO | 0x05, /**< Invalid state (Since 3.0) */
113 AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE = TIZEN_ERROR_AUDIO_IO | 0x06, /**< Not supported stream type (Since 3.0) */
121 * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
126 * @brief Called when audio input data is available in asynchronous(event) mode.
128 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
130 * @remarks @a use audio_in_peek() to get audio in data inside callback, use audio_in_drop() after use of peeked data.
132 * @param[in] handle The handle to the audio input
133 * @param[in] nbytes The amount of available audio in data which can be peeked.
134 * @param[in] user_data The user data passed from the callback registration function
136 * @see audio_in_set_stream_cb()
138 typedef void (*audio_in_stream_cb)(audio_in_h handle, size_t nbytes, void *user_data);
141 * @brief Called when the state of audio input is changed.
145 * @param[in] handle The handle of the audio input
146 * @param[in] previous The previous state of the audio input
147 * @param[in] current The current state of the audio input
148 * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
149 * @param[in] user_data The user data passed from the callback registration function
151 * @see audio_in_set_state_changed_cb()
152 * @see audio_in_unset_state_changed_cb()
154 typedef void (*audio_in_state_changed_cb)(audio_in_h handle, audio_io_state_e previous, audio_io_state_e current, bool by_policy, void *user_data);
157 * @brief Creates an audio device instance and returns an input handle to record PCM (pulse-code modulation) data.
159 * @details This function is used for audio input initialization.
161 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
163 * @privilege %http://tizen.org/privilege/recorder
165 * @remarks @a input must be released using audio_in_destroy().
167 * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
168 * @param[in] channel The audio channel type (mono or stereo)
169 * @param[in] type The type of audio sample (8- or 16-bit)
170 * @param[out] input An audio input handle is created on success
171 * @return @c 0 on success,
172 * otherwise a negative error value
173 * @retval #AUDIO_IO_ERROR_NONE Successful
174 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
175 * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
176 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
177 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
178 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
179 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
181 * @post The state will be #AUDIO_IO_STATE_IDLE.\n
182 * audio_in_set_sound_stream_info() is recommended to be called after this API.
183 * @see audio_in_destroy()
185 int audio_in_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_in_h *input);
188 * @brief Releases the audio input handle and all its resources associated with an audio stream.
190 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
192 * @param[in] input The handle to the audio input to destroy
193 * @return @c 0 on success,
194 * otherwise a negative error value
195 * @retval #AUDIO_IO_ERROR_NONE Successful
196 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
197 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
198 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
200 * @see audio_in_create()
202 int audio_in_destroy(audio_in_h input);
205 * @brief Sets the sound stream information to the audio input.
209 * @remarks @a the sound stream information includes audio routing and volume type.
210 * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
211 * System, Alarm, Notification, Emergency, Voice Information, Ringtone VOIP and Ringtone Call stream types are not supported in this API.
213 * @param[in] input The handle to the audio input
214 * @param[in] stream_info The handle of stream information
215 * @return @c 0 on success,
216 * otherwise a negative error value
217 * @retval #AUDIO_IO_ERROR_NONE Successful
218 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
219 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
220 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
221 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
223 * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
224 * Call audio_in_create() before calling this function.
225 * @post Call audio_in_prepare() after calling this function.
226 * @see sound_manager_create_stream_information()
227 * @see sound_manager_destroy_stream_information()
229 int audio_in_set_sound_stream_info(audio_in_h input, sound_stream_info_h stream_info);
232 * @brief Prepares the audio input for reading audio data by starting buffering of audio data from the device.
234 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
236 * @param[in] input The handle to the audio input
237 * @return @c 0 on success,
238 * otherwise a negative error value
239 * @retval #AUDIO_IO_ERROR_NONE Successful
240 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
241 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
242 * @retval #AUDIO_IO_ERROR_DEVICE_POLICY_RESTRICTION Device policy restriction
243 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
245 * @post The state will be #AUDIO_IO_STATE_RUNNING.
246 * @see audio_in_unprepare()
248 int audio_in_prepare(audio_in_h input);
251 * @brief Unprepares the audio input.
253 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
255 * @param[in] input The handle to the audio input
256 * @return @c 0 on success,
257 * otherwise a negative error value
258 * @retval #AUDIO_IO_ERROR_NONE Successful
259 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
260 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
261 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
263 * @post The state will be #AUDIO_IO_STATE_IDLE.
264 * @see audio_in_prepare()
266 int audio_in_unprepare(audio_in_h input);
269 * @brief Pauses buffering of audio data from the device.
273 * @param[in] input The handle to the audio input
274 * @return @c 0 on success,
275 * otherwise a negative error value
276 * @retval #AUDIO_IO_ERROR_NONE Successful
277 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
278 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
279 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
281 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
282 * @post The state will be #AUDIO_IO_STATE_PAUSED.
283 * @see audio_in_resume()
285 int audio_in_pause(audio_in_h input);
288 * @brief Resumes buffering audio data from the device.
292 * @param[in] input The handle to the audio input
293 * @return @c 0 on success,
294 * otherwise a negative error value
295 * @retval #AUDIO_IO_ERROR_NONE Successful
296 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
297 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
298 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
300 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
301 * @post The state will be #AUDIO_IO_STATE_RUNNING.
302 * @see audio_in_pause()
304 int audio_in_resume(audio_in_h input);
307 * @brief Flushes and discards buffered audio data from the input stream.
309 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
311 * @param[in] input The handle to the audio input
312 * @return @c 0 on success,
313 * otherwise a negative error value
314 * @retval #AUDIO_IO_ERROR_NONE Successful
315 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
316 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
317 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
319 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
321 int audio_in_flush(audio_in_h input);
324 * @brief Reads audio data from the audio input buffer.
326 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
328 * @param[in] input The handle to the audio input
329 * @param[out] buffer The PCM buffer address
330 * @param[in] length The length of the PCM data buffer (in bytes)
331 * @return The number of read bytes on success,
332 * otherwise a negative error value
333 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
334 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
335 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
336 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
337 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
339 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
341 int audio_in_read(audio_in_h input, void *buffer, unsigned int length);
344 * @brief Gets the size to be allocated for the audio input buffer.
346 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
348 * @param[in] input The handle to the audio input
349 * @param[out] size The buffer size (in bytes, the maximum size is 1 MB)
350 * @return @c 0 on success,
351 * otherwise a negative error value
352 * @retval #AUDIO_IO_ERROR_NONE Successful
353 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
354 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
355 * @see audio_in_read()
357 int audio_in_get_buffer_size(audio_in_h input, int *size);
360 * @brief Gets the sample rate of the audio input data stream.
362 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
364 * @param[in] input The handle to the audio input
365 * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
366 * @return @c 0 on success,
367 * otherwise a negative error value
368 * @retval #AUDIO_IO_ERROR_NONE Successful
369 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
370 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
372 int audio_in_get_sample_rate(audio_in_h input, int *sample_rate);
375 * @brief Gets the channel type of the audio input data stream.
377 * @details The audio channel type defines whether the audio is mono or stereo.
379 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
381 * @param[in] input The handle to the audio input
382 * @param[out] channel The audio channel type
383 * @return @c 0 on success,
384 * otherwise a negative error value
385 * @retval #AUDIO_IO_ERROR_NONE Successful
386 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
387 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
389 int audio_in_get_channel(audio_in_h input, audio_channel_e *channel);
392 * @brief Gets the sample audio format (8-bit or 16-bit) of the audio input data stream.
394 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
396 * @param[in] input The handle to the audio input
397 * @param[out] type The audio sample type
398 * @return @c 0 on success,
399 * otherwise a negative error value
400 * @retval #AUDIO_IO_ERROR_NONE Successful
401 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
402 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
404 int audio_in_get_sample_type(audio_in_h input, audio_sample_type_e *type);
407 * @brief Sets an asynchronous(event) callback function to handle recording PCM (pulse-code modulation) data.
409 * @details @a callback will be called when you can read a PCM data.
410 * It might cause dead lock if change the state of audio handle in callback.
411 * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare)
412 * Recommend to use as a VOIP only.
413 * Recommend not to hold callback too long.(it affects latency)
415 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
417 * @remarks @a input must be created using audio_in_create().
419 * @param[in] input An audio input handle
420 * @param[in] callback notify stream callback when user can read data (#audio_in_stream_cb)
421 * @param[in] user_data user data to be retrieved when callback is called
422 * @return @c 0 on success,
423 * otherwise a negative error value
424 * @retval #AUDIO_IO_ERROR_NONE Successful
425 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
426 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
427 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
428 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
429 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
431 * @see audio_in_unset_stream_cb()
433 int audio_in_set_stream_cb(audio_in_h input, audio_in_stream_cb callback, void* user_data);
436 * @brief Unregisters the callback function.
438 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
440 * @param[in] input The handle to the audio input
441 * @return @c 0 on success,
442 * otherwise a negative error value
443 * @retval #AUDIO_IO_ERROR_NONE Successful
444 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
445 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
446 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
448 * @see audio_in_set_stream_cb()
450 int audio_in_unset_stream_cb(audio_in_h input);
453 * @brief peek from audio in buffer
455 * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
457 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
459 * @remarks @a Works only in asynchronous(event) mode. This will just retrieve buffer pointer from audio in buffer. Drop after use.
461 * @param[in] input The handle to the audio input
462 * @param[out] buffer start buffer pointer of peeked audio in data
463 * @param[out] length amount of audio in data to be peeked
464 * @return @c 0 on success,
465 * otherwise a negative error value
466 * @retval #AUDIO_IO_ERROR_NONE Successful
467 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
468 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
469 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
470 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
472 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
473 * @see audio_in_drop()
475 int audio_in_peek(audio_in_h input, const void **buffer, unsigned int *length);
478 * @brief drop peeked audio buffer.
480 * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
482 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
484 * @remarks @a Works only in asynchronous(event) mode. This will remove audio in data from actual stream buffer. Use this if peeked data is not needed anymore.
486 * @param[in] input The handle to the audio input
487 * @return 0 on success, otherwise a negative error value
488 * @retval #AUDIO_IO_ERROR_NONE Successful
489 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
490 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
491 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
492 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
494 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
495 * @see audio_in_peek()
497 int audio_in_drop(audio_in_h input);
500 * @brief Sets the state changed callback function to the audio input handle.
504 * @remarks @a input must be created using audio_in_create().
506 * @param[in] input The audio input handle
507 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_in_state_changed_cb)
508 * @param[in] user_data user data to be retrieved when callback is called
509 * @return @c 0 on success,
510 * otherwise a negative error value
511 * @retval #AUDIO_IO_ERROR_NONE Successful
512 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
513 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
515 * @see audio_in_unset_state_changed_cb()
517 int audio_in_set_state_changed_cb(audio_in_h input, audio_in_state_changed_cb callback, void* user_data);
520 * @brief Unregisters the state changed callback function of the audio input handle.
524 * @param[in] input The handle to the audio input
525 * @return @c 0 on success,
526 * otherwise a negative error value
527 * @retval #AUDIO_IO_ERROR_NONE Successful
528 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
529 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
531 * @see audio_in_set_state_changed_cb()
533 int audio_in_unset_state_changed_cb(audio_in_h input);
540 * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
545 * @brief Called when audio out data can be written in asynchronous(event) mode.
547 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
549 * @remarks @a use audio_out_write() to write pcm data inside this callback.
550 * @param[in] handle The handle to the audio output
551 * @param[in] nbytes The amount of audio in data which can be written.
552 * @param[in] user_data The user data passed from the callback registration function
554 * @see audio_out_set_stream_cb()
556 typedef void (*audio_out_stream_cb)(audio_out_h handle, size_t nbytes, void *user_data);
559 * @brief Called when the state of audio output is changed.
563 * @param[in] handle The handle of the audio output
564 * @param[in] previous The previous state of the audio output
565 * @param[in] current The current state of the audio output
566 * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
567 * @param[in] user_data The user data passed from the callback registration function
569 * @see audio_out_set_state_changed_cb()
570 * @see audio_out_unset_state_changed_cb()
572 typedef void (*audio_out_state_changed_cb)(audio_out_h handle, audio_io_state_e previous, audio_io_state_e current, bool by_policy, void *user_data);
575 * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
577 * @details This function is used for audio output initialization.
581 * @remarks @a output must be released by audio_out_destroy().
582 * It is recommended to call audio_out_set_sound_stream_info() after this API.
584 * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
585 * @param[in] channel The audio channel type (mono or stereo)
586 * @param[in] type The type of audio sample (8-bit or 16-bit)
587 * @param[out] output An audio output handle is created on success
588 * @return @c 0 on success,
589 * otherwise a negative error value
590 * @retval #AUDIO_IO_ERROR_NONE Successful
591 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
592 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
593 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
594 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
596 * @post The state will be #AUDIO_IO_STATE_IDLE.\n
597 * audio_out_set_sound_stream_info() is recommended to be called after this API.
598 * @see audio_out_destroy()
600 int audio_out_create_new(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_out_h *output);
603 * @brief Releases the audio output handle, along with all its resources.
605 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
607 * @param[in] output The handle to the audio output to destroy
608 * @return @c 0 on success,
609 * otherwise a negative error value
610 * @retval #AUDIO_IO_ERROR_NONE Successful
611 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
612 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
613 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
615 * @see audio_out_create_new()
617 int audio_out_destroy(audio_out_h output);
620 * @brief Sets the sound stream information to the audio output.
624 * @remarks @a the sound stream information includes audio routing and volume type.
625 * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
626 * Voice Recognition and Loopback stream types are not supported in this API.
628 * @param[in] output The handle to the audio output
629 * @param[in] stream_info The handle of stream information
630 * @return @c 0 on success,
631 * otherwise a negative error value
632 * @retval #AUDIO_IO_ERROR_NONE Successful
633 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
634 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
635 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
636 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
638 * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
639 * Call audio_out_create_new() before calling this function.
640 * @post Call audio_out_prepare() after calling this function.
641 * @see sound_manager_create_stream_information()
642 * @see sound_manager_destroy_stream_information()
644 int audio_out_set_sound_stream_info(audio_out_h output, sound_stream_info_h stream_info);
647 * @brief Prepares the audio output for playback, this must be called before audio_out_write().
649 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
651 * @param[in] output The handle to the audio output
652 * @return @c 0 on success,
653 * otherwise a negative error value
654 * @retval #AUDIO_IO_ERROR_NONE Successful
655 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
656 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
658 * @post The state will be #AUDIO_IO_STATE_RUNNING.
659 * @see audio_out_unprepare()
661 int audio_out_prepare(audio_out_h output);
664 * @brief Unprepares the audio output.
666 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
668 * @param[in] output The handle to the audio output
669 * @return @c 0 on success,
670 * otherwise a negative error value
671 * @retval #AUDIO_IO_ERROR_NONE Successful
672 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
673 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
675 * @post The state will be #AUDIO_IO_STATE_IDLE.
676 * @see audio_out_prepare()
678 int audio_out_unprepare(audio_out_h output);
681 * @brief Pauses feeding of audio data to the device.
685 * @param[in] output The handle to the audio output
686 * @return @c 0 on success,
687 * otherwise a negative error value
688 * @retval #AUDIO_IO_ERROR_NONE Successful
689 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
690 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
692 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
693 * @post The state will be #AUDIO_IO_STATE_PAUSED.
694 * @see audio_out_resume()
696 int audio_out_pause(audio_out_h output);
699 * @brief Resumes feeding of audio data to the device.
703 * @param[in] output The handle to the audio output
704 * @return @c 0 on success,
705 * otherwise a negative error value
706 * @retval #AUDIO_IO_ERROR_NONE Successful
707 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
708 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
710 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
711 * @post The state will be #AUDIO_IO_STATE_RUNNING.
712 * @see audio_out_pause()
714 int audio_out_resume(audio_out_h output);
717 * @brief Drains buffered audio data from the output stream.
719 * @details This function waits until drains stream buffer completely. (e.g end of playback)
721 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
723 * @param[in] output The handle to the audio output
724 * @return @c 0 on success,
725 * otherwise a negative error value
726 * @retval #AUDIO_IO_ERROR_NONE Successful
727 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
728 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
730 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
731 * @see audio_out_flush()
733 int audio_out_drain(audio_out_h output);
736 * @brief Flushes and discards buffered audio data from the output stream.
738 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
740 * @param[in] output The handle to the audio output
741 * @return @c 0 on success,
742 * otherwise a negative error value
743 * @retval #AUDIO_IO_ERROR_NONE Successful
744 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
745 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
747 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
748 * @see audio_out_drain()
750 int audio_out_flush(audio_out_h output);
753 * @brief Starts writing the audio data to the device.
755 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
757 * @param[in] output The handle to the audio output
758 * @param[in,out] buffer The PCM buffer address
759 * @param[in] length The length of the PCM buffer (in bytes)
760 * @return The written data size on success,
761 * otherwise a negative error value
762 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
763 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
764 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
765 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
767 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
769 int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
772 * @brief Gets the size to be allocated for the audio output buffer.
774 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
776 * @param[in] output The handle to the audio output
777 * @param[out] size The suggested buffer size (in bytes, the maximum size is 1 MB)
778 * @return @c 0 on success,
779 * otherwise a negative error value
780 * @retval #AUDIO_IO_ERROR_NONE Successful
781 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
783 * @see audio_out_write()
785 int audio_out_get_buffer_size(audio_out_h output, int *size);
788 * @brief Gets the sample rate of the audio output data stream.
790 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
792 * @param[in] output The handle to the audio output
793 * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
794 * @return @c 0 on success,
795 * otherwise a negative error value
796 * @retval #AUDIO_IO_ERROR_NONE Successful
797 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
799 int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
802 * @brief Gets the channel type of the audio output data stream.
804 * @details The audio channel type defines whether the audio is mono or stereo.
806 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
808 * @param[in] output The handle to the audio output
809 * @param[out] channel The audio channel type
810 * @return @c 0 on success,
811 * otherwise a negative error value
812 * @retval #AUDIO_IO_ERROR_NONE Successful
813 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
815 int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
818 * @brief Gets the sample audio format (8-bit or 16-bit) of the audio output data stream.
820 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
822 * @param[in] output The handle to the audio output
823 * @param[out] type The audio sample type
824 * @return @c 0 on success,
825 * otherwise a negative error value
826 * @retval #AUDIO_IO_ERROR_NONE Successful
827 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
829 int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
832 * @brief Gets the sound type supported by the audio output device.
834 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
836 * @param[in] output The handle to the audio output
837 * @param[out] type The sound type
838 * @return @c 0 on success,
839 * otherwise a negative error value
840 * @retval #AUDIO_IO_ERROR_NONE Successful
841 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
843 int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
846 * @brief Sets an asynchronous(event) callback function to handle playing PCM (pulse-code modulation) data.
848 * @details @a callback will be called when you can write a PCM data.
849 * It might cause dead lock if change the state of audio handle in callback.
850 * (ex: audio_out_destroy, audio_out_prepare, audio_out_unprepare)
851 * Recommend to use as a VOIP only.
852 * Recommend not to hold callback too long.(it affects latency)
854 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
856 * @remarks @a output must be created using audio_out_create_new().
858 * @param[in] output An audio output handle
859 * @param[in] callback notify stream callback when user can write data (#audio_out_stream_cb)
860 * @param[in] user_data user data to be retrieved when callback is called
861 * @return 0 on success, otherwise a negative error value
862 * @retval #AUDIO_IO_ERROR_NONE Successful
863 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
864 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
865 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
866 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
868 * @see audio_out_unset_stream_cb()
870 int audio_out_set_stream_cb(audio_out_h output, audio_out_stream_cb callback, void* user_data);
873 * @brief Unregisters the callback function.
875 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
877 * @param[in] output The handle to the audio output
878 * @return 0 on success, otherwise a negative error value
879 * @retval #AUDIO_IO_ERROR_NONE Successful
880 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
881 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
883 * @see audio_out_set_stream_cb()
885 int audio_out_unset_stream_cb(audio_out_h output);
888 * @brief Sets the state changed callback function to the audio output handle.
892 * @remarks @a input must be created using audio_out_create_new().
894 * @param[in] output The audio output handle
895 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_out_state_changed_cb)
896 * @param[in] user_data user data to be retrieved when callback is called
897 * @return @c 0 on success,
898 * otherwise a negative error value
899 * @retval #AUDIO_IO_ERROR_NONE Successful
900 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
902 * @see audio_out_unset_state_changed_cb()
904 int audio_out_set_state_changed_cb(audio_out_h output, audio_out_state_changed_cb callback, void* user_data);
907 * @brief Unregisters the state changed callback function of the audio output handle.
911 * @param[in] output The handle to the audio output
912 * @return @c 0 on success,
913 * otherwise a negative error value
914 * @retval #AUDIO_IO_ERROR_NONE Successful
915 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
917 * @see audio_out_set_state_changed_cb()
919 int audio_out_unset_state_changed_cb(audio_out_h output);
929 #endif /* __TIZEN_MEDIA_AUDIO_IO_H__ */