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_S24_LE, /**< Signed 24-bit audio samples (Since 5.0) */
76 AUDIO_SAMPLE_TYPE_S24_32_LE, /**< Signed 24-bit (packed in 32-bit) audio samples (Since 5.0) */
77 AUDIO_SAMPLE_TYPE_S32_LE, /**< Signed 32-bit audio samples (Since 5.5) */
78 } audio_sample_type_e;
81 * @brief Enumeration for audio channel.
82 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
85 AUDIO_CHANNEL_MONO = 0x80, /**< 1 channel, mono */
86 AUDIO_CHANNEL_STEREO, /**< 2 channels, stereo */
87 AUDIO_CHANNEL_MULTI_3, /**< 3 channels (Since 5.5) */
88 AUDIO_CHANNEL_MULTI_4, /**< 4 channels (Since 5.5) */
89 AUDIO_CHANNEL_MULTI_5, /**< 5 channels (Since 5.5) */
90 AUDIO_CHANNEL_MULTI_6, /**< 6 channels (Since 5.5) */
91 AUDIO_CHANNEL_MULTI_7, /**< 7 channels (Since 5.5) */
92 AUDIO_CHANNEL_MULTI_8, /**< 8 channels (Since 5.5) */
96 * @brief Enumeration for audio input and output state.
100 AUDIO_IO_STATE_IDLE, /**< Audio-io handle is created, but not prepared */
101 AUDIO_IO_STATE_RUNNING, /**< Audio-io handle is ready and the stream is running */
102 AUDIO_IO_STATE_PAUSED, /**< Audio-io handle is ready and the stream is paused */
106 * @brief Enumeration for audio input and output error.
107 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
110 AUDIO_IO_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
111 AUDIO_IO_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
112 AUDIO_IO_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
113 AUDIO_IO_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION, /**< Invalid operation */
114 AUDIO_IO_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Device open error by security */
115 AUDIO_IO_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
116 AUDIO_IO_ERROR_DEVICE_POLICY_RESTRICTION = TIZEN_ERROR_DEVICE_POLICY_RESTRICTION, /**< Device policy restriction (Since 3.0) */
117 AUDIO_IO_ERROR_DEVICE_NOT_OPENED = TIZEN_ERROR_AUDIO_IO | 0x01, /**< Device open error */
118 AUDIO_IO_ERROR_DEVICE_NOT_CLOSED = TIZEN_ERROR_AUDIO_IO | 0x02, /**< Device close error */
119 AUDIO_IO_ERROR_INVALID_BUFFER = TIZEN_ERROR_AUDIO_IO | 0x03, /**< Invalid buffer pointer */
120 AUDIO_IO_ERROR_SOUND_POLICY = TIZEN_ERROR_AUDIO_IO | 0x04, /**< Sound policy error */
121 AUDIO_IO_ERROR_INVALID_STATE = TIZEN_ERROR_AUDIO_IO | 0x05, /**< Invalid state (Since 3.0) */
122 AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE = TIZEN_ERROR_AUDIO_IO | 0x06, /**< Not supported stream type (Since 3.0) */
130 * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
135 * @brief Called when audio input data is available in asynchronous (event) mode.
137 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
139 * @remarks Use audio_in_peek() to get 'audio in' data inside callback, use audio_in_drop() after use of peeked data.
141 * @param[in] handle The handle to the audio input
142 * @param[in] nbytes The amount of available 'audio in' data which can be peeked.
143 * @param[in] user_data The user data passed from the callback registration function
145 * @see audio_in_set_stream_cb()
147 typedef void (*audio_in_stream_cb)(audio_in_h handle, size_t nbytes, void *user_data);
150 * @brief Called when the state of audio input is changed.
154 * @param[in] handle The handle of the audio input
155 * @param[in] previous The previous state of the audio input
156 * @param[in] current The current state of the audio input
157 * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
158 * @param[in] user_data The user data passed from the callback registration function
160 * @see audio_in_set_state_changed_cb()
161 * @see audio_in_unset_state_changed_cb()
163 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);
166 * @brief Creates an audio device instance and returns an input handle to record PCM (pulse-code modulation) data.
168 * @details This function is used for audio input initialization.
170 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
172 * @privilege %http://tizen.org/privilege/recorder
174 * @remarks @a input must be released using audio_in_destroy().
175 * If the channel count of the requested @a channel is different from the system's supported channel count, then channel remapping will be processed internally.
177 * @param[in] sample_rate The audio sample rate \n
178 * Before 5.0: 8000[Hz] ~ 48000[Hz] \n
179 * Since 5.0: 8000[Hz] ~ 192000[Hz]
180 * @param[in] channel The audio channel type \n
181 * Before 5.5: Mono or stereo \n
182 * Since 5.5: Mono, stereo or multi-channels
183 * @param[in] type The type of audio sample \n
184 * Before 5.0: 8 or 16-bit \n
185 * Since 5.0: 8, 16 or 24-bit \n
186 * Since 5.5: 8, 16, 24 or 32-bit
187 * @param[out] input An audio input handle is created on success
188 * @return @c 0 on success,
189 * otherwise a negative error value
190 * @retval #AUDIO_IO_ERROR_NONE Successful
191 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
192 * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
193 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
194 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
195 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
196 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
198 * @post The state will be #AUDIO_IO_STATE_IDLE.\n
199 * audio_in_set_sound_stream_info() is recommended to be called after this API.
200 * @see audio_in_destroy()
202 int audio_in_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_in_h *input);
205 * @brief Releases the audio input handle and all its resources associated with an audio stream.
207 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
209 * @param[in] input The handle to the audio input to destroy
210 * @return @c 0 on success,
211 * otherwise a negative error value
212 * @retval #AUDIO_IO_ERROR_NONE Successful
213 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
214 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
215 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
217 * @see audio_in_create()
219 int audio_in_destroy(audio_in_h input);
222 * @brief Sets the sound stream information to the audio input.
226 * @remarks The sound stream information includes audio routing and volume type.
227 * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
228 * System, Alarm, Notification, Emergency, Voice Information, Ringtone VOIP and Ringtone Call stream types are not supported in this API.
230 * @param[in] input The handle to the audio input
231 * @param[in] stream_info The handle of stream information
232 * @return @c 0 on success,
233 * otherwise a negative error value
234 * @retval #AUDIO_IO_ERROR_NONE Successful
235 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
236 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
237 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
238 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
240 * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
241 * Call audio_in_create() before calling this function.
242 * @post Call audio_in_prepare() after calling this function.
243 * @see sound_manager_create_stream_information()
244 * @see sound_manager_destroy_stream_information()
246 int audio_in_set_sound_stream_info(audio_in_h input, sound_stream_info_h stream_info);
249 * @brief Prepares the audio input for reading audio data by starting buffering of audio data from the device.
251 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
253 * @param[in] input The handle to the audio input
254 * @return @c 0 on success,
255 * otherwise a negative error value
256 * @retval #AUDIO_IO_ERROR_NONE Successful
257 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
258 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
259 * @retval #AUDIO_IO_ERROR_DEVICE_POLICY_RESTRICTION Device policy restriction
260 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
262 * @post The state will be #AUDIO_IO_STATE_RUNNING.
263 * @see audio_in_unprepare()
265 int audio_in_prepare(audio_in_h input);
268 * @brief Unprepares the audio input.
270 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
272 * @param[in] input The handle to the audio input
273 * @return @c 0 on success,
274 * otherwise a negative error value
275 * @retval #AUDIO_IO_ERROR_NONE Successful
276 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
277 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
278 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
280 * @post The state will be #AUDIO_IO_STATE_IDLE.
281 * @see audio_in_prepare()
283 int audio_in_unprepare(audio_in_h input);
286 * @brief Pauses buffering of audio data from the device.
290 * @param[in] input The handle to the audio input
291 * @return @c 0 on success,
292 * otherwise a negative error value
293 * @retval #AUDIO_IO_ERROR_NONE Successful
294 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
295 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
296 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
298 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
299 * @post The state will be #AUDIO_IO_STATE_PAUSED.
300 * @see audio_in_resume()
302 int audio_in_pause(audio_in_h input);
305 * @brief Resumes buffering audio data from the device.
309 * @param[in] input The handle to the audio input
310 * @return @c 0 on success,
311 * otherwise a negative error value
312 * @retval #AUDIO_IO_ERROR_NONE Successful
313 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
314 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
315 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
317 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
318 * @post The state will be #AUDIO_IO_STATE_RUNNING.
319 * @see audio_in_pause()
321 int audio_in_resume(audio_in_h input);
324 * @brief Flushes and discards buffered audio data from the input stream.
326 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
328 * @param[in] input The handle to the audio input
329 * @return @c 0 on success,
330 * otherwise a negative error value
331 * @retval #AUDIO_IO_ERROR_NONE Successful
332 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
333 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
334 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
336 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
338 int audio_in_flush(audio_in_h input);
341 * @brief Reads audio data from the audio input buffer.
343 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
345 * @param[in] input The handle to the audio input
346 * @param[out] buffer The PCM buffer address
347 * @param[in] length The length of the PCM data buffer (in bytes)
348 * @return The number of read bytes on success,
349 * otherwise a negative error value
350 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
351 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
352 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
353 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
354 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
356 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
358 int audio_in_read(audio_in_h input, void *buffer, unsigned int length);
361 * @brief Gets the size to be allocated for the audio input buffer.
363 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
365 * @param[in] input The handle to the audio input
366 * @param[out] size The buffer size (in bytes, the maximum size is 1 MB)
367 * @return @c 0 on success,
368 * otherwise a negative error value
369 * @retval #AUDIO_IO_ERROR_NONE Successful
370 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
371 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
372 * @see audio_in_read()
374 int audio_in_get_buffer_size(audio_in_h input, int *size);
377 * @brief Gets the sample rate of the audio input data stream.
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] sample_rate The audio sample rate \n
383 * Before 5.0: 8000[Hz] ~ 48000[Hz] \n
384 * Since 5.0: 8000[Hz] ~ 192000[Hz]
385 * @return @c 0 on success,
386 * otherwise a negative error value
387 * @retval #AUDIO_IO_ERROR_NONE Successful
388 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
389 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
391 int audio_in_get_sample_rate(audio_in_h input, int *sample_rate);
394 * @brief Gets the channel type of the audio input data stream.
396 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
398 * @param[in] input The handle to the audio input
399 * @param[out] channel The audio channel type \n
400 * Before 5.5: Mono or stereo \n
401 * Since 5.5: Mono, stereo or multi-channels
402 * @return @c 0 on success,
403 * otherwise a negative error value
404 * @retval #AUDIO_IO_ERROR_NONE Successful
405 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
406 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
408 int audio_in_get_channel(audio_in_h input, audio_channel_e *channel);
411 * @brief Gets the sample audio format of the audio input data stream.
413 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
415 * @param[in] input The handle to the audio input
416 * @param[out] type The type of audio sample \n
417 * Before 5.0: 8 or 16-bit \n
418 * Since 5.0: 8, 16 or 24-bit \n
419 * Since 5.5: 8, 16, 24 or 32-bit
420 * @return @c 0 on success,
421 * otherwise a negative error value
422 * @retval #AUDIO_IO_ERROR_NONE Successful
423 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
424 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
426 int audio_in_get_sample_type(audio_in_h input, audio_sample_type_e *type);
429 * @brief Sets an asynchronous (event) callback function to handle recording PCM (pulse-code modulation) data.
431 * @details @a callback will be called when you can read a PCM data.
432 * It might cause dead lock if change the state of audio handle in callback.
433 * (ex: audio_in_destroy(), audio_in_prepare(), audio_in_unprepare())
434 * Recommend to use as a VOIP only.
435 * Recommend not to hold callback too long.(it affects latency)
437 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
439 * @remarks @a input must be created using audio_in_create().
441 * @param[in] input An audio input handle
442 * @param[in] callback notify stream callback when user can read data (#audio_in_stream_cb)
443 * @param[in] user_data user data to be retrieved when callback is called
444 * @return @c 0 on success,
445 * otherwise a negative error value
446 * @retval #AUDIO_IO_ERROR_NONE Successful
447 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
448 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
449 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
450 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
451 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
453 * @see audio_in_unset_stream_cb()
455 int audio_in_set_stream_cb(audio_in_h input, audio_in_stream_cb callback, void* user_data);
458 * @brief Unregisters the callback function.
460 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
462 * @param[in] input The handle to the audio input
463 * @return @c 0 on success,
464 * otherwise a negative error value
465 * @retval #AUDIO_IO_ERROR_NONE Successful
466 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
467 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
468 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
470 * @see audio_in_set_stream_cb()
472 int audio_in_unset_stream_cb(audio_in_h input);
475 * @brief Peeks into the 'audio in' buffer.
477 * @details This function works correctly only with read callback. Otherwise it won't operate as intended.
479 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
481 * @remarks Works only in asynchronous (event) mode.
482 * This function provides the pointer to the 'audio in' buffer. The pointed memory is owned by the platform, therefore the @a buffer should not be released by the application.
483 * When the data in the @a buffer is not needed anymore, use audio_in_drop() with the @a input for which audio_in_peek() was called.
485 * @param[in] input The handle to the audio input
486 * @param[out] buffer start buffer pointer of peeked 'audio in' data
487 * @param[out] length amount of 'audio in' data to be peeked
488 * @return @c 0 on success,
489 * otherwise a negative error value
490 * @retval #AUDIO_IO_ERROR_NONE Successful
491 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
492 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
493 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
494 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
496 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
497 * @see audio_in_drop()
499 int audio_in_peek(audio_in_h input, const void **buffer, unsigned int *length);
502 * @brief Drops the 'audio in' buffer that was peeked into.
504 * @details This function works correctly only with read callback. Otherwise it won't operate as intended.
506 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
508 * @remarks Works only in asynchronous (event) mode. This will remove 'audio in' data from the actual stream buffer. Use this if peeked data is not needed anymore.
510 * @param[in] input The handle to the audio input
511 * @return 0 on success, otherwise a negative error value
512 * @retval #AUDIO_IO_ERROR_NONE Successful
513 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
514 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
515 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
516 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
518 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
519 * @see audio_in_peek()
521 int audio_in_drop(audio_in_h input);
524 * @brief Sets the state changed callback function to the audio input handle.
528 * @remarks @a input must be created using audio_in_create().
530 * @param[in] input The audio input handle
531 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_in_state_changed_cb)
532 * @param[in] user_data user data to be retrieved when callback is called
533 * @return @c 0 on success,
534 * otherwise a negative error value
535 * @retval #AUDIO_IO_ERROR_NONE Successful
536 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
537 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
539 * @see audio_in_unset_state_changed_cb()
541 int audio_in_set_state_changed_cb(audio_in_h input, audio_in_state_changed_cb callback, void* user_data);
544 * @brief Unregisters the state changed callback function of the audio input handle.
548 * @param[in] input The handle to the audio input
549 * @return @c 0 on success,
550 * otherwise a negative error value
551 * @retval #AUDIO_IO_ERROR_NONE Successful
552 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
553 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
555 * @see audio_in_set_state_changed_cb()
557 int audio_in_unset_state_changed_cb(audio_in_h input);
564 * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
569 * @brief Called when 'audio out' data can be written in asynchronous (event) mode.
571 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
573 * @remarks Use audio_out_write() to write pcm data inside this callback.
574 * @param[in] handle The handle to the audio output
575 * @param[in] nbytes The amount of 'audio in' data which can be written.
576 * @param[in] user_data The user data passed from the callback registration function
578 * @see audio_out_set_stream_cb()
580 typedef void (*audio_out_stream_cb)(audio_out_h handle, size_t nbytes, void *user_data);
583 * @brief Called when the state of audio output is changed.
587 * @param[in] handle The handle of the audio output
588 * @param[in] previous The previous state of the audio output
589 * @param[in] current The current state of the audio output
590 * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
591 * @param[in] user_data The user data passed from the callback registration function
593 * @see audio_out_set_state_changed_cb()
594 * @see audio_out_unset_state_changed_cb()
596 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);
599 * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
601 * @details This function is used for audio output initialization.
605 * @remarks @a output must be released by audio_out_destroy().
606 * It is recommended to call audio_out_set_sound_stream_info() after this API.
607 * Multi-channel playback is not supported.
609 * @param[in] sample_rate The audio sample rate \n
610 * Before 5.0: 8000[Hz] ~ 48000[Hz] \n
611 * Since 5.0: 8000[Hz] ~ 192000[Hz]
612 * @param[in] channel The audio channel type (mono or stereo)
613 * @param[in] type The type of audio sample \n
614 * Before 5.0: 8 or 16-bit \n
615 * Since 5.0: 8, 16 or 24-bit \n
616 * Since 5.5: 8, 16, 24 or 32-bit
617 * @param[out] output An audio output handle is created on success
618 * @return @c 0 on success,
619 * otherwise a negative error value
620 * @retval #AUDIO_IO_ERROR_NONE Successful
621 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
622 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
623 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
624 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
626 * @post The state will be #AUDIO_IO_STATE_IDLE.\n
627 * audio_out_set_sound_stream_info() is recommended to be called after this API.
628 * @see audio_out_destroy()
630 int audio_out_create_new(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_out_h *output);
633 * @brief Releases the audio output handle, along with all its resources.
635 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
637 * @param[in] output The handle to the audio output to destroy
638 * @return @c 0 on success,
639 * otherwise a negative error value
640 * @retval #AUDIO_IO_ERROR_NONE Successful
641 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
642 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
643 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
645 * @see audio_out_create_new()
647 int audio_out_destroy(audio_out_h output);
650 * @brief Sets the sound stream information to the audio output.
654 * @remarks The sound stream information includes audio routing and volume type.
655 * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
656 * Voice Recognition and Loopback stream types are not supported in this API.
658 * @param[in] output The handle to the audio output
659 * @param[in] stream_info The handle of stream information
660 * @return @c 0 on success,
661 * otherwise a negative error value
662 * @retval #AUDIO_IO_ERROR_NONE Successful
663 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
664 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
665 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
666 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
668 * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
669 * Call audio_out_create_new() before calling this function.
670 * @post Call audio_out_prepare() after calling this function.
671 * @see sound_manager_create_stream_information()
672 * @see sound_manager_destroy_stream_information()
674 int audio_out_set_sound_stream_info(audio_out_h output, sound_stream_info_h stream_info);
677 * @brief Prepares the audio output for playback, this must be called before audio_out_write().
679 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
681 * @param[in] output The handle to the audio output
682 * @return @c 0 on success,
683 * otherwise a negative error value
684 * @retval #AUDIO_IO_ERROR_NONE Successful
685 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
686 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
688 * @post The state will be #AUDIO_IO_STATE_RUNNING.
689 * @see audio_out_unprepare()
691 int audio_out_prepare(audio_out_h output);
694 * @brief Unprepares the audio output.
696 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
698 * @param[in] output The handle to the audio output
699 * @return @c 0 on success,
700 * otherwise a negative error value
701 * @retval #AUDIO_IO_ERROR_NONE Successful
702 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
703 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
705 * @post The state will be #AUDIO_IO_STATE_IDLE.
706 * @see audio_out_prepare()
708 int audio_out_unprepare(audio_out_h output);
711 * @brief Pauses feeding of audio data to the device.
715 * @param[in] output The handle to the audio output
716 * @return @c 0 on success,
717 * otherwise a negative error value
718 * @retval #AUDIO_IO_ERROR_NONE Successful
719 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
720 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
722 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
723 * @post The state will be #AUDIO_IO_STATE_PAUSED.
724 * @see audio_out_resume()
726 int audio_out_pause(audio_out_h output);
729 * @brief Resumes feeding of audio data to the device.
733 * @param[in] output The handle to the audio output
734 * @return @c 0 on success,
735 * otherwise a negative error value
736 * @retval #AUDIO_IO_ERROR_NONE Successful
737 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
738 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
740 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
741 * @post The state will be #AUDIO_IO_STATE_RUNNING.
742 * @see audio_out_pause()
744 int audio_out_resume(audio_out_h output);
747 * @brief Drains buffered audio data from the output stream.
749 * @details This function waits until drains stream buffer completely. (e.g end of playback)
751 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
753 * @param[in] output The handle to the audio output
754 * @return @c 0 on success,
755 * otherwise a negative error value
756 * @retval #AUDIO_IO_ERROR_NONE Successful
757 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
758 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
760 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
761 * @see audio_out_flush()
763 int audio_out_drain(audio_out_h output);
766 * @brief Flushes and discards buffered audio data from the output stream.
768 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
770 * @param[in] output The handle to the audio output
771 * @return @c 0 on success,
772 * otherwise a negative error value
773 * @retval #AUDIO_IO_ERROR_NONE Successful
774 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
775 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
777 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
778 * @see audio_out_drain()
780 int audio_out_flush(audio_out_h output);
783 * @brief Starts writing the audio data to the device.
785 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
787 * @param[in] output The handle to the audio output
788 * @param[in,out] buffer The PCM buffer address
789 * @param[in] length The length of the PCM buffer (in bytes)
790 * @return The written data size on success,
791 * otherwise a negative error value
792 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
793 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
794 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
795 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
797 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
799 int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
802 * @brief Gets the size to be allocated for the audio output buffer.
804 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
806 * @param[in] output The handle to the audio output
807 * @param[out] size The suggested buffer size (in bytes, the maximum size is 1 MB)
808 * @return @c 0 on success,
809 * otherwise a negative error value
810 * @retval #AUDIO_IO_ERROR_NONE Successful
811 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
813 * @see audio_out_write()
815 int audio_out_get_buffer_size(audio_out_h output, int *size);
818 * @brief Gets the sample rate 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] sample_rate The audio sample rate \n
824 * Before 5.0: 8000[Hz] ~ 48000[Hz] \n
825 * Since 5.0: 8000[Hz] ~ 192000[Hz]
826 * @return @c 0 on success,
827 * otherwise a negative error value
828 * @retval #AUDIO_IO_ERROR_NONE Successful
829 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
831 int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
834 * @brief Gets the channel type of the audio output data stream.
836 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
838 * @param[in] output The handle to the audio output
839 * @param[out] channel The audio channel type (mono or stereo)
840 * @return @c 0 on success,
841 * otherwise a negative error value
842 * @retval #AUDIO_IO_ERROR_NONE Successful
843 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
845 int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
848 * @brief Gets the sample audio format of the audio output data stream.
850 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
852 * @param[in] output The handle to the audio output
853 * @param[out] type The type of audio sample \n
854 * Before 5.0: 8 or 16-bit \n
855 * Since 5.0: 8, 16 or 24-bit \n
856 * Since 5.5: 8, 16, 24 or 32-bit
857 * @return @c 0 on success,
858 * otherwise a negative error value
859 * @retval #AUDIO_IO_ERROR_NONE Successful
860 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
862 int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
865 * @brief Gets the sound type supported by the audio output device.
867 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
869 * @param[in] output The handle to the audio output
870 * @param[out] type The sound type
871 * @return @c 0 on success,
872 * otherwise a negative error value
873 * @retval #AUDIO_IO_ERROR_NONE Successful
874 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
876 int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
879 * @brief Sets an asynchronous (event) callback function to handle playing PCM (pulse-code modulation) data.
881 * @details @a callback will be called when you can write a PCM data.
882 * It might cause dead lock if change the state of audio handle in callback.
883 * (ex: audio_out_destroy(), audio_out_prepare(), audio_out_unprepare())
884 * Recommend to use as a VOIP only.
885 * Recommend not to hold callback too long.(it affects latency)
887 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
889 * @remarks @a output must be created using audio_out_create_new().
891 * @param[in] output An audio output handle
892 * @param[in] callback notify stream callback when user can write data (#audio_out_stream_cb)
893 * @param[in] user_data user data to be retrieved when callback is called
894 * @return 0 on success, otherwise a negative error value
895 * @retval #AUDIO_IO_ERROR_NONE Successful
896 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
897 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
898 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
899 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
901 * @see audio_out_unset_stream_cb()
903 int audio_out_set_stream_cb(audio_out_h output, audio_out_stream_cb callback, void* user_data);
906 * @brief Unregisters the callback function.
908 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
910 * @param[in] output The handle to the audio output
911 * @return 0 on success, otherwise a negative error value
912 * @retval #AUDIO_IO_ERROR_NONE Successful
913 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
914 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
916 * @see audio_out_set_stream_cb()
918 int audio_out_unset_stream_cb(audio_out_h output);
921 * @brief Sets the state changed callback function to the audio output handle.
925 * @remarks @a input must be created using audio_out_create_new().
927 * @param[in] output The audio output handle
928 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_out_state_changed_cb)
929 * @param[in] user_data user data to be retrieved when callback is called
930 * @return @c 0 on success,
931 * otherwise a negative error value
932 * @retval #AUDIO_IO_ERROR_NONE Successful
933 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
935 * @see audio_out_unset_state_changed_cb()
937 int audio_out_set_state_changed_cb(audio_out_h output, audio_out_state_changed_cb callback, void* user_data);
940 * @brief Unregisters the state changed callback function of the audio output handle.
944 * @param[in] output The handle to the audio output
945 * @return @c 0 on success,
946 * otherwise a negative error value
947 * @retval #AUDIO_IO_ERROR_NONE Successful
948 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
950 * @see audio_out_set_state_changed_cb()
952 int audio_out_unset_state_changed_cb(audio_out_h output);
962 #endif /* __TIZEN_MEDIA_AUDIO_IO_H__ */