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__
21 #include <sound_manager.h>
22 #include <sys/types.h>
31 * @brief This file contains the Audio Input and Audio Output API.
35 * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
40 * @brief The audio input handle.
41 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
43 typedef struct audio_io_s *audio_in_h;
50 * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
55 * @brief The audio output handle.
56 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
58 typedef struct audio_io_s *audio_out_h;
65 * @addtogroup CAPI_MEDIA_AUDIO_IO_MODULE
70 * @brief Enumeration for audio sample type with bit depth.
71 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
75 AUDIO_SAMPLE_TYPE_U8 = 0x70, /**< Unsigned 8-bit audio samples */
76 AUDIO_SAMPLE_TYPE_S16_LE, /**< Signed 16-bit audio samples */
77 } audio_sample_type_e;
80 * @brief Enumeration for audio channel.
81 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
84 AUDIO_CHANNEL_MONO = 0x80, /**< 1 channel, mono */
85 AUDIO_CHANNEL_STEREO, /**< 2 channel, stereo */
89 * @brief Enumeration for audio input and output state.
94 AUDIO_IO_STATE_IDLE, /**< Audio-io handle is created, but not prepared */
95 AUDIO_IO_STATE_RUNNING, /**< Audio-io handle is ready and the stream is running */
96 AUDIO_IO_STATE_PAUSED, /**< Audio-io handle is ready and the stream is paused */
100 * @brief Enumeration for audio input and output error.
101 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
104 AUDIO_IO_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
105 AUDIO_IO_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
106 AUDIO_IO_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
107 AUDIO_IO_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION, /**< Invalid operation */
108 AUDIO_IO_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Device open error by security */
109 AUDIO_IO_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
110 AUDIO_IO_ERROR_DEVICE_NOT_OPENED = TIZEN_ERROR_AUDIO_IO | 0x01, /**< Device open error */
111 AUDIO_IO_ERROR_DEVICE_NOT_CLOSED = TIZEN_ERROR_AUDIO_IO | 0x02, /**< Device close error */
112 AUDIO_IO_ERROR_INVALID_BUFFER = TIZEN_ERROR_AUDIO_IO | 0x03, /**< Invalid buffer pointer */
113 AUDIO_IO_ERROR_SOUND_POLICY = TIZEN_ERROR_AUDIO_IO | 0x04, /**< Sound policy error */
114 AUDIO_IO_ERROR_INVALID_STATE = TIZEN_ERROR_AUDIO_IO | 0x05, /**< Invalid state (Since 3.0) */
118 * @deprecated Deprecated since 3.0
119 * @brief Enumeration for audio IO interrupted messages.
120 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
124 AUDIO_IO_INTERRUPTED_COMPLETED = 0, /**< Interrupt completed */
125 AUDIO_IO_INTERRUPTED_BY_MEDIA, /**< Interrupted by a media application */
126 AUDIO_IO_INTERRUPTED_BY_CALL, /**< Interrupted by an incoming call */
127 AUDIO_IO_INTERRUPTED_BY_EARJACK_UNPLUG, /**< Interrupted by unplugging headphones */
128 AUDIO_IO_INTERRUPTED_BY_RESOURCE_CONFLICT, /**< Interrupted by a resource conflict */
129 AUDIO_IO_INTERRUPTED_BY_ALARM, /**< Interrupted by an alarm */
130 AUDIO_IO_INTERRUPTED_BY_EMERGENCY, /**< Interrupted by an emergency */
131 AUDIO_IO_INTERRUPTED_BY_NOTIFICATION, /**< Interrupted by a notification */
132 } audio_io_interrupted_code_e;
135 * @deprecated Deprecated since 3.0. Use sound_stream_focus_state_changed_cb instead.
136 * @brief Called when audio input or output is interrupted.
138 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
139 * @param[in] error_code The interrupted error code
140 * @param[in] user_data The user data passed from the callback registration function
142 * @see audio_in_set_interrupted_cb()
143 * @see audio_out_set_interrupted_cb()
144 * @see audio_in_unset_interrupted_cb()
145 * @see audio_out_unset_interrupted_cb()
147 typedef void (*audio_io_interrupted_cb)(audio_io_interrupted_code_e code, void *user_data);
154 * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
163 * @brief Called when audio input data is available in asynchronous(event) mode.
165 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
167 * @remarks @a use audio_in_peek() to get audio in data inside callback, use audio_in_drop() after use of peeked data.
169 * @param[in] handle The handle to the audio input
170 * @param[in] nbytes The amount of available audio in data which can be peeked.
171 * @param[in] user_data The user data passed from the callback registration function
173 * @see audio_in_set_stream_cb()
175 typedef void (*audio_in_stream_cb)(audio_in_h handle, size_t nbytes, void *user_data);
178 * @brief Called when the state of audio input is changed.
182 * @param[in] handle The handle of the audio input
183 * @param[in] previous The previous state of the audio input
184 * @param[in] current The current state of the audio input
185 * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
186 * @param[in] user_data The user data passed from the callback registration function
188 * @see audio_in_set_state_changed_cb()
189 * @see audio_in_unset_state_changed_cb()
191 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);
194 * @brief Creates an audio device instance and returns an input handle to record PCM (pulse-code modulation) data.
196 * @details This function is used for audio input initialization.
198 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
200 * @privilege %http://tizen.org/privilege/recorder
202 * @remarks @a input must be released using audio_in_destroy().
204 * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
205 * @param[in] channel The audio channel type (mono or stereo)
206 * @param[in] type The type of audio sample (8- or 16-bit)
207 * @param[out] input An audio input handle is created on success
208 * @return @c 0 on success,
209 * otherwise a negative error value
210 * @retval #AUDIO_IO_ERROR_NONE Successful
211 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
212 * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
213 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
214 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
215 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
216 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
218 * @post The state will be #AUDIO_IO_STATE_IDLE.\n
219 * audio_in_set_stream_info() is recommended to be called after this API.
220 * @see audio_in_destroy()
222 int audio_in_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_in_h *input);
225 * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
226 * @brief Creates an audio loopback device instance and returns an input handle to record PCM (pulse-code modulation) data.
228 * @details This function is used for audio loopback input initialization.
230 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
232 * @privilege %http://tizen.org/privilege/recorder
234 * @remarks @a input must be released using audio_in_destroy().
236 * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
237 * @param[in] channel The audio channel type, mono, or stereo
238 * @param[in] type The type of audio sample (8- or 16-bit)
239 * @param[out] input An audio input handle will be created, if successful
240 * @return @c 0 on success,
241 * otherwise a negative error value
242 * @retval #AUDIO_IO_ERROR_NONE Successful
243 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
244 * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
245 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
246 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
247 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
248 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
250 * @see audio_in_destroy()
252 int audio_in_create_loopback(int sample_rate, audio_channel_e channel, audio_sample_type_e type , audio_in_h* input);
255 * @brief Releases the audio input handle and all its resources associated with an audio stream.
257 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
259 * @param[in] input The handle to the audio input to destroy
260 * @return @c 0 on success,
261 * otherwise a negative error value
262 * @retval #AUDIO_IO_ERROR_NONE Successful
263 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
264 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
265 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
267 * @see audio_in_create()
269 int audio_in_destroy(audio_in_h input);
272 * @brief Sets the sound stream information to the audio input.
276 * @remarks @a the sound stream information includes audio routing and volume type.
277 * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
279 * @param[in] input The handle to the audio input
280 * @param[in] stream_info The handle of stream information
281 * @return @c 0 on success,
282 * otherwise a negative error value
283 * @retval #AUDIO_IO_ERROR_NONE Successful
284 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
285 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
286 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
288 * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
289 * Call audio_in_create() before calling this function.
290 * @post Call audio_in_prepare() after calling this function.
291 * @see sound_manager_create_stream_information()
292 * @see sound_manager_destroy_stream_information()
294 int audio_in_set_stream_info(audio_in_h input, sound_stream_info_h stream_info);
297 * @brief Prepares the audio input for reading audio data by starting buffering of audio data from the device.
299 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
301 * @param[in] input The handle to the audio input
302 * @return @c 0 on success,
303 * otherwise a negative error value
304 * @retval #AUDIO_IO_ERROR_NONE Successful
305 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
306 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
307 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
309 * @post The state will be #AUDIO_IO_STATE_RUNNING.
310 * @see audio_in_unprepare()
312 int audio_in_prepare(audio_in_h input);
315 * @brief Unprepares the audio input.
317 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
319 * @param[in] input The handle to the audio input
320 * @return @c 0 on success,
321 * otherwise a negative error value
322 * @retval #AUDIO_IO_ERROR_NONE Successful
323 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
324 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
325 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
327 * @post The state will be #AUDIO_IO_STATE_IDLE.
328 * @see audio_in_prepare()
330 int audio_in_unprepare(audio_in_h input);
333 * @brief Pauses buffering of audio data from the device.
337 * @param[in] input The handle to the audio input
338 * @return @c 0 on success,
339 * otherwise a negative error value
340 * @retval #AUDIO_IO_ERROR_NONE Successful
341 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
342 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
343 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
345 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
346 * @post The state will be #AUDIO_IO_STATE_PAUSED.
347 * @see audio_in_resume()
349 int audio_in_pause(audio_in_h input);
352 * @brief Resumes buffering audio data from the device.
356 * @param[in] input The handle to the audio input
357 * @return @c 0 on success,
358 * otherwise a negative error value
359 * @retval #AUDIO_IO_ERROR_NONE Successful
360 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
361 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
362 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
364 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
365 * @post The state will be #AUDIO_IO_STATE_RUNNING.
366 * @see audio_in_pause()
368 int audio_in_resume(audio_in_h input);
371 * @brief Flushes and discards buffered audio data from the input stream.
375 * @param[in] input The handle to the audio input
376 * @return @c 0 on success,
377 * otherwise a negative error value
378 * @retval #AUDIO_IO_ERROR_NONE Successful
379 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
380 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
381 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
383 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
385 int audio_in_flush(audio_in_h input);
388 * @brief Reads audio data from the audio input buffer.
390 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
392 * @param[in] input The handle to the audio input
393 * @param[out] buffer The PCM buffer address
394 * @param[in] length The length of the PCM data buffer (in bytes)
395 * @return The number of read bytes on success,
396 * otherwise a negative error value
397 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
398 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
399 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
400 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
401 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
403 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
405 int audio_in_read(audio_in_h input, void *buffer, unsigned int length);
408 * @brief Gets the size to be allocated for the audio input buffer.
410 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
412 * @param[in] input The handle to the audio input
413 * @param[out] size The buffer size (in bytes, the maximum size is 1 MB)
414 * @return @c 0 on success,
415 * otherwise a negative error value
416 * @retval #AUDIO_IO_ERROR_NONE Successful
417 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
418 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
419 * @see audio_in_read()
421 int audio_in_get_buffer_size(audio_in_h input, int *size);
424 * @brief Gets the sample rate of the audio input data stream.
426 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
428 * @param[in] input The handle to the audio input
429 * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
430 * @return @c 0 on success,
431 * otherwise a negative error value
432 * @retval #AUDIO_IO_ERROR_NONE Successful
433 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
434 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
436 int audio_in_get_sample_rate(audio_in_h input, int *sample_rate);
439 * @brief Gets the channel type of the audio input data stream.
441 * @details The audio channel type defines whether the audio is mono or stereo.
443 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
445 * @param[in] input The handle to the audio input
446 * @param[out] channel The audio channel type
447 * @return @c 0 on success,
448 * otherwise a negative error value
449 * @retval #AUDIO_IO_ERROR_NONE Successful
450 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
451 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
453 int audio_in_get_channel(audio_in_h input, audio_channel_e *channel);
456 * @brief Gets the sample audio format (8-bit or 16-bit) of the audio input data stream.
458 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
460 * @param[in] input The handle to the audio input
461 * @param[out] type The audio sample type
462 * @return @c 0 on success,
463 * otherwise a negative error value
464 * @retval #AUDIO_IO_ERROR_NONE Successful
465 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
466 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
468 int audio_in_get_sample_type(audio_in_h input, audio_sample_type_e *type);
471 * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
472 * @brief Registers a callback function to be invoked when the audio input handle is interrupted or the interrupt is completed.
474 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
476 * @param[in] input The handle to the audio input
477 * @param[in] callback The callback function to register
478 * @param[in] user_data The user data to be passed to the callback function
479 * @return @c 0 on success,
480 * otherwise a negative error value
481 * @retval #AUDIO_IO_ERROR_NONE Successful
482 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
483 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
484 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
485 * @post audio_io_interrupted_cb() will be invoked.
487 * @see audio_in_unset_interrupted_cb()
488 * @see audio_io_interrupted_cb()
490 int audio_in_set_interrupted_cb(audio_in_h input, audio_io_interrupted_cb callback, void *user_data);
493 * @deprecated Deprecated since 3.0
494 * @brief Unregisters the callback function.
496 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
498 * @param[in] input The handle to the audio input
499 * @return @c 0 on success,
500 * otherwise a negative error value
501 * @retval #AUDIO_IO_ERROR_NONE Successful
502 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
503 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
504 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
506 * @see audio_in_set_interrupted_cb()
508 int audio_in_unset_interrupted_cb(audio_in_h input);
511 * @deprecated Deprecated since 3.0
512 * @brief Ignores session for input.
514 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
516 * @param[in] input The handle to the audio input
517 * @return @c 0 on success,
518 * otherwise a negative error value
519 * @retval #AUDIO_IO_ERROR_NONE Successful
520 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
521 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
522 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
524 int audio_in_ignore_session(audio_in_h input);
527 * @brief Sets an asynchronous(event) callback function to handle recording PCM (pulse-code modulation) data.
529 * @details @a callback will be called when you can read a PCM data.
530 * It might cause dead lock if change the state of audio handle in callback.
531 * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare)
532 * Recommend to use as a VOIP only.
533 * Recommend not to hold callback too long.(it affects latency)
535 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
537 * @remarks @a input must be created using audio_in_create().
539 * @param[in] input An audio input handle
540 * @param[in] callback notify stream callback when user can read data (#audio_in_stream_cb)
541 * @param[in] user_data user data to be retrieved when callback is called
542 * @return @c 0 on success,
543 * otherwise a negative error value
544 * @retval #AUDIO_IO_ERROR_NONE Successful
545 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
546 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
547 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
548 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
549 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
551 * @see audio_out_set_stream_cb()
553 int audio_in_set_stream_cb(audio_in_h input, audio_in_stream_cb callback, void* user_data);
556 * @brief Unregisters the callback function.
558 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
560 * @param[in] input The handle to the audio input
561 * @return @c 0 on success,
562 * otherwise a negative error value
563 * @retval #AUDIO_IO_ERROR_NONE Successful
564 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
565 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
566 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
568 * @see audio_in_set_interrupted_cb()
570 int audio_in_unset_stream_cb(audio_in_h input);
573 * @brief peek from audio in buffer
575 * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
577 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
579 * @remarks @a Works only in asynchronous(event) mode. This will just retrieve buffer pointer from audio in buffer. Drop after use.
581 * @param[in] input The handle to the audio input
582 * @param[out] buffer start buffer pointer of peeked audio in data
583 * @param[in,out] length amount of audio in data to be peeked
584 * @return @c 0 on success,
585 * otherwise a negative error value
586 * @retval #AUDIO_IO_ERROR_NONE Successful
587 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
588 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
589 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
590 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
592 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
593 * @see audio_in_drop()
595 int audio_in_peek(audio_in_h input, const void **buffer, unsigned int *length);
598 * @brief drop peeked audio buffer.
600 * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
602 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
604 * @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.
606 * @param[in] input The handle to the audio input
607 * @return 0 on success, otherwise a negative error value
608 * @retval #AUDIO_IO_ERROR_NONE Successful
609 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
610 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
611 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
612 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
614 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
615 * @see audio_in_peek()
617 int audio_in_drop(audio_in_h input);
620 * @brief Sets the state changed callback function to the audio input handle.
624 * @remarks @a input must be created using audio_in_create().
626 * @param[in] input The audio input handle
627 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_in_state_changed_cb)
628 * @param[in] user_data user data to be retrieved when callback is called
629 * @return @c 0 on success,
630 * otherwise a negative error value
631 * @retval #AUDIO_IO_ERROR_NONE Successful
632 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
633 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
635 * @see audio_in_unset_state_changed_cb()
637 int audio_in_set_state_changed_cb(audio_in_h input, audio_in_state_changed_cb callback, void* user_data);
640 * @brief Unregisters the state changed callback function of the audio input handle.
644 * @param[in] input The handle to the audio input
645 * @return @c 0 on success,
646 * otherwise a negative error value
647 * @retval #AUDIO_IO_ERROR_NONE Successful
648 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
649 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
651 * @see audio_in_set_state_changed_cb()
653 int audio_in_unset_state_changed_cb(audio_in_h input);
664 * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
669 * @brief Called when audio out data can be written in asynchronous(event) mode.
671 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
673 * @remarks @a use audio_out_write() to write pcm data inside this callback.
674 * @param[in] handle The handle to the audio output
675 * @param[in] nbytes The amount of audio in data which can be written.
676 * @param[in] user_data The user data passed from the callback registration function
678 * @see audio_out_set_stream_cb()
680 typedef void (*audio_out_stream_cb)(audio_out_h handle, size_t nbytes, void *user_data);
683 * @brief Called when the state of audio output is changed.
687 * @param[in] handle The handle of the audio output
688 * @param[in] previous The previous state of the audio output
689 * @param[in] current The current state of the audio output
690 * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
691 * @param[in] user_data The user data passed from the callback registration function
693 * @see audio_out_set_state_changed_cb()
694 * @see audio_out_unset_state_changed_cb()
696 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);
699 * @deprecated Deprecated since 3.0. Use audio_out_create_new() instead.
700 * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
702 * @details This function is used for audio output initialization.
704 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
706 * @remarks @a output must be released by audio_out_destroy().
708 * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
709 * @param[in] channel The audio channel type (mono or stereo)
710 * @param[in] type The type of audio sample (8-bit or 16-bit)
711 * @param[in] sound_type The type of sound (#sound_type_e)
712 * @param[out] output An audio output handle is created on success
713 * @return @c 0 on success,
714 * otherwise a negative error value
715 * @retval #AUDIO_IO_ERROR_NONE Successful
716 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
717 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
718 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
719 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
721 * @see audio_out_destroy()
723 int audio_out_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type, sound_type_e sound_type, audio_out_h *output);
726 * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
728 * @details This function is used for audio output initialization.
732 * @remarks @a output must be released by audio_out_destroy().
733 * It is recommended to call audio_out_set_stream_info() after this API.
735 * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
736 * @param[in] channel The audio channel type (mono or stereo)
737 * @param[in] type The type of audio sample (8-bit or 16-bit)
738 * @param[out] output An audio output handle is created on success
739 * @return @c 0 on success,
740 * otherwise a negative error value
741 * @retval #AUDIO_IO_ERROR_NONE Successful
742 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
743 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
744 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
745 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
747 * @post The state will be #AUDIO_IO_STATE_IDLE.\n
748 * audio_out_set_stream_info() is recommended to be called after this API.
749 * @see audio_out_destroy()
751 int audio_out_create_new(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_out_h *output);
754 * @brief Releases the audio output handle, along with all its resources.
756 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
758 * @param[in] output The handle to the audio output to destroy
759 * @return @c 0 on success,
760 * otherwise a negative error value
761 * @retval #AUDIO_IO_ERROR_NONE Successful
762 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
763 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
764 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
766 * @see audio_out_create()
768 int audio_out_destroy(audio_out_h output);
771 * @brief Sets the sound stream information to the audio output.
775 * @remarks @a the sound stream information includes audio routing and volume type.
776 * For more details, you can refer to sound_manager.h
778 * @param[in] output The handle to the audio output
779 * @param[in] stream_info The handle of stream information
780 * @return @c 0 on success,
781 * otherwise a negative error value
782 * @retval #AUDIO_IO_ERROR_NONE Successful
783 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
784 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
785 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
787 * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
788 * Call audio_out_create_new() before calling this function.
789 * @post Call audio_out_prepare() after calling this function.
790 * @see sound_manager_create_stream_information()
791 * @see sound_manager_destroy_stream_information()
793 int audio_out_set_stream_info(audio_out_h output, sound_stream_info_h stream_info);
796 * @brief Prepares the audio output for playback, this must be called before audio_out_write().
798 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
800 * @param[in] output The handle to the audio output
801 * @return @c 0 on success,
802 * otherwise a negative error value
803 * @retval #AUDIO_IO_ERROR_NONE Successful
804 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
805 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
807 * @post The state will be #AUDIO_IO_STATE_RUNNING.
808 * @see audio_out_unprepare()
810 int audio_out_prepare(audio_out_h output);
813 * @brief Unprepares the audio output.
815 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
817 * @param[in] output The handle to the audio output
818 * @return @c 0 on success,
819 * otherwise a negative error value
820 * @retval #AUDIO_IO_ERROR_NONE Successful
821 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
822 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
824 * @post The state will be #AUDIO_IO_STATE_IDLE.
825 * @see audio_out_prepare()
827 int audio_out_unprepare(audio_out_h output);
830 * @brief Pauses feeding of audio data to the device.
834 * @param[in] output The handle to the audio output
835 * @return @c 0 on success,
836 * otherwise a negative error value
837 * @retval #AUDIO_IO_ERROR_NONE Successful
838 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
839 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
841 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
842 * @post The state will be #AUDIO_IO_STATE_PAUSED.
843 * @see audio_out_resume()
845 int audio_out_pause(audio_out_h output);
848 * @brief Resumes feeding of audio data to the device.
852 * @param[in] output The handle to the audio output
853 * @return @c 0 on success,
854 * otherwise a negative error value
855 * @retval #AUDIO_IO_ERROR_NONE Successful
856 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
857 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
859 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
860 * @post The state will be #AUDIO_IO_STATE_RUNNING.
861 * @see audio_out_pause()
863 int audio_out_resume(audio_out_h output);
866 * @brief Drains buffered audio data from the output stream.
868 * @details This function waits until drains stream buffer completely. (e.g end of playback)
872 * @param[in] output The handle to the audio output
873 * @return @c 0 on success,
874 * otherwise a negative error value
875 * @retval #AUDIO_IO_ERROR_NONE Successful
876 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
877 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
879 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
880 * @see audio_out_flush()
882 int audio_out_drain(audio_out_h output);
885 * @brief Flushes and discards buffered audio data from the output stream.
889 * @param[in] output The handle to the audio output
890 * @return @c 0 on success,
891 * otherwise a negative error value
892 * @retval #AUDIO_IO_ERROR_NONE Successful
893 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
894 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
896 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
897 * @see audio_out_drain()
899 int audio_out_flush(audio_out_h output);
902 * @brief Starts writing the audio data to the device.
904 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
906 * @param[in] output The handle to the audio output
907 * @param[in,out] buffer The PCM buffer address
908 * @param[in] length The length of the PCM buffer (in bytes)
909 * @return The written data size on success,
910 * otherwise a negative error value
911 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
912 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
913 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
914 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
916 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
918 int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
921 * @brief Gets the size to be allocated for the audio output buffer.
923 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
925 * @param[in] output The handle to the audio output
926 * @param[out] size The suggested buffer size (in bytes, the maximum size is 1 MB)
927 * @return @c 0 on success,
928 * otherwise a negative error value
929 * @retval #AUDIO_IO_ERROR_NONE Successful
930 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
932 * @see audio_out_write()
934 int audio_out_get_buffer_size(audio_out_h output, int *size);
937 * @brief Gets the sample rate of the audio output data stream.
939 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
941 * @param[in] output The handle to the audio output
942 * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
943 * @return @c 0 on success,
944 * otherwise a negative error value
945 * @retval #AUDIO_IO_ERROR_NONE Successful
946 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
948 int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
951 * @brief Gets the channel type of the audio output data stream.
953 * @details The audio channel type defines whether the audio is mono or stereo.
955 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
957 * @param[in] output The handle to the audio output
958 * @param[out] channel The audio channel type
959 * @return @c 0 on success,
960 * otherwise a negative error value
961 * @retval #AUDIO_IO_ERROR_NONE Successful
962 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
964 int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
967 * @brief Gets the sample audio format (8-bit or 16-bit) of the audio output data stream.
969 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
971 * @param[in] output The handle to the audio output
972 * @param[out] type The audio sample type
973 * @return @c 0 on success,
974 * otherwise a negative error value
975 * @retval #AUDIO_IO_ERROR_NONE Successful
976 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
978 int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
981 * @brief Gets the sound type supported by the audio output device.
983 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
985 * @param[in] output The handle to the audio output
986 * @param[out] type The sound type
987 * @return @c 0 on success,
988 * otherwise a negative error value
989 * @retval #AUDIO_IO_ERROR_NONE Successful
990 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
992 int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
995 * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
996 * @brief Registers a callback function to be invoked when the audio output handle is interrupted or the interrupt is completed.
998 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1000 * @param[in] output The handle to the audio output
1001 * @param[in] callback The callback function to register
1002 * @param[in] user_data The user data to be passed to the callback function
1003 * @return @c 0 on success,
1004 * otherwise a negative error value
1005 * @retval #AUDIO_IO_ERROR_NONE Successful
1006 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1007 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1009 * @post audio_io_interrupted_cb() will be invoked.
1010 * @see audio_out_unset_interrupted_cb()
1011 * @see audio_io_interrupted_cb()
1013 int audio_out_set_interrupted_cb(audio_out_h output, audio_io_interrupted_cb callback, void *user_data);
1016 * @deprecated Deprecated since 3.0
1017 * @brief Unregisters the callback function.
1019 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1021 * @param[in] output The handle to the audio output
1022 * @return @c 0 on success,
1023 * otherwise a negative error value
1024 * @retval #AUDIO_IO_ERROR_NONE Successful
1025 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1026 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1028 * @see audio_out_set_interrupted_cb()
1030 int audio_out_unset_interrupted_cb(audio_out_h output);
1033 * @deprecated Deprecated since 3.0
1034 * @brief Ignores session for output.
1036 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1038 * @param[in] output The handle to the audio output
1039 * @return @c 0 on success,
1040 * otherwise a negative error value
1041 * @retval #AUDIO_IO_ERROR_NONE Successful
1042 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1043 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1045 int audio_out_ignore_session(audio_out_h output);
1048 * @brief Sets an asynchronous(event) callback function to handle playing PCM (pulse-code modulation) data.
1050 * @details @a callback will be called when you can write a PCM data.
1051 * It might cause dead lock if change the state of audio handle in callback.
1052 * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare)
1053 * Recommend to use as a VOIP only.
1054 * Recommend not to hold callback too long.(it affects latency)
1056 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1058 * @remarks @a output must be created using audio_out_create().
1060 * @param[in] output An audio output handle
1061 * @param[in] callback notify stream callback when user can write data (#audio_out_stream_cb)
1062 * @param[in] user_data user data to be retrieved when callback is called
1063 * @return 0 on success, otherwise a negative error value
1064 * @retval #AUDIO_IO_ERROR_NONE Successful
1065 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1066 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
1067 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
1068 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
1070 * @see audio_in_set_stream_cb()
1072 int audio_out_set_stream_cb(audio_out_h output, audio_out_stream_cb callback, void* user_data);
1075 * @brief Unregisters the callback function.
1077 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1079 * @param[in] output The handle to the audio output
1080 * @return 0 on success, otherwise a negative error value
1081 * @retval #AUDIO_IO_ERROR_NONE Successful
1082 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1083 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1085 * @see audio_out_set_stream_cb()
1087 int audio_out_unset_stream_cb(audio_out_h output);
1090 * @brief Sets the state changed callback function to the audio output handle.
1094 * @remarks @a input must be created using audio_out_create_new().
1096 * @param[in] output The audio output handle
1097 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_out_state_changed_cb)
1098 * @param[in] user_data user data to be retrieved when callback is called
1099 * @return @c 0 on success,
1100 * otherwise a negative error value
1101 * @retval #AUDIO_IO_ERROR_NONE Successful
1102 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1104 * @see audio_out_unset_state_changed_cb()
1106 int audio_out_set_state_changed_cb(audio_out_h output, audio_out_state_changed_cb callback, void* user_data);
1109 * @brief Unregisters the state changed callback function of the audio output handle.
1113 * @param[in] output The handle to the audio output
1114 * @return @c 0 on success,
1115 * otherwise a negative error value
1116 * @retval #AUDIO_IO_ERROR_NONE Successful
1117 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1119 * @see audio_out_set_state_changed_cb()
1121 int audio_out_unset_state_changed_cb(audio_out_h output);
1131 #endif /* __TIZEN_MEDIA_AUDIO_IO_H__ */