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>
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) */
115 AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE = TIZEN_ERROR_AUDIO_IO | 0x06, /**< Not supported stream type (Since 3.0) */
119 * @deprecated Deprecated since 3.0
120 * @brief Enumeration for audio IO interrupted messages.
121 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
125 AUDIO_IO_INTERRUPTED_COMPLETED = 0, /**< Interrupt completed */
126 AUDIO_IO_INTERRUPTED_BY_MEDIA, /**< Interrupted by a media application */
127 AUDIO_IO_INTERRUPTED_BY_CALL, /**< Interrupted by an incoming call */
128 AUDIO_IO_INTERRUPTED_BY_EARJACK_UNPLUG, /**< Interrupted by unplugging headphones */
129 AUDIO_IO_INTERRUPTED_BY_RESOURCE_CONFLICT, /**< Interrupted by a resource conflict */
130 AUDIO_IO_INTERRUPTED_BY_ALARM, /**< Interrupted by an alarm */
131 AUDIO_IO_INTERRUPTED_BY_EMERGENCY, /**< Interrupted by an emergency */
132 AUDIO_IO_INTERRUPTED_BY_NOTIFICATION, /**< Interrupted by a notification */
133 } audio_io_interrupted_code_e;
136 * @deprecated Deprecated since 3.0. Use sound_stream_focus_state_changed_cb instead.
137 * @brief Called when audio input or output is interrupted.
139 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
140 * @param[in] error_code The interrupted error code
141 * @param[in] user_data The user data passed from the callback registration function
143 * @see audio_in_set_interrupted_cb()
144 * @see audio_out_set_interrupted_cb()
145 * @see audio_in_unset_interrupted_cb()
146 * @see audio_out_unset_interrupted_cb()
148 typedef void (*audio_io_interrupted_cb)(audio_io_interrupted_code_e code, void *user_data);
155 * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
164 * @brief Called when audio input data is available in asynchronous(event) mode.
166 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
168 * @remarks @a use audio_in_peek() to get audio in data inside callback, use audio_in_drop() after use of peeked data.
170 * @param[in] handle The handle to the audio input
171 * @param[in] nbytes The amount of available audio in data which can be peeked.
172 * @param[in] user_data The user data passed from the callback registration function
174 * @see audio_in_set_stream_cb()
176 typedef void (*audio_in_stream_cb)(audio_in_h handle, size_t nbytes, void *user_data);
179 * @brief Called when the state of audio input is changed.
183 * @param[in] handle The handle of the audio input
184 * @param[in] previous The previous state of the audio input
185 * @param[in] current The current state of the audio input
186 * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
187 * @param[in] user_data The user data passed from the callback registration function
189 * @see audio_in_set_state_changed_cb()
190 * @see audio_in_unset_state_changed_cb()
192 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);
195 * @brief Creates an audio device instance and returns an input handle to record PCM (pulse-code modulation) data.
197 * @details This function is used for audio input initialization.
199 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
201 * @privilege %http://tizen.org/privilege/recorder
203 * @remarks @a input must be released using audio_in_destroy().
205 * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
206 * @param[in] channel The audio channel type (mono or stereo)
207 * @param[in] type The type of audio sample (8- or 16-bit)
208 * @param[out] input An audio input handle is created on success
209 * @return @c 0 on success,
210 * otherwise a negative error value
211 * @retval #AUDIO_IO_ERROR_NONE Successful
212 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
213 * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
214 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
215 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
216 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
217 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
219 * @post The state will be #AUDIO_IO_STATE_IDLE.\n
220 * audio_in_set_stream_info() is recommended to be called after this API.
221 * @see audio_in_destroy()
223 int audio_in_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_in_h *input);
226 * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
227 * @brief Creates an audio loopback device instance and returns an input handle to record PCM (pulse-code modulation) data.
229 * @details This function is used for audio loopback input initialization.
231 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
233 * @privilege %http://tizen.org/privilege/recorder
235 * @remarks @a input must be released using audio_in_destroy().
237 * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
238 * @param[in] channel The audio channel type, mono, or stereo
239 * @param[in] type The type of audio sample (8- or 16-bit)
240 * @param[out] input An audio input handle will be created, if successful
241 * @return @c 0 on success,
242 * otherwise a negative error value
243 * @retval #AUDIO_IO_ERROR_NONE Successful
244 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
245 * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
246 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
247 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
248 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
249 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
251 * @see audio_in_destroy()
253 int audio_in_create_loopback(int sample_rate, audio_channel_e channel, audio_sample_type_e type , audio_in_h* input);
256 * @brief Releases the audio input handle and all its resources associated with an audio stream.
258 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
260 * @param[in] input The handle to the audio input to destroy
261 * @return @c 0 on success,
262 * otherwise a negative error value
263 * @retval #AUDIO_IO_ERROR_NONE Successful
264 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
265 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
266 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
268 * @see audio_in_create()
270 int audio_in_destroy(audio_in_h input);
273 * @brief Sets the sound stream information to the audio input.
277 * @remarks @a the sound stream information includes audio routing and volume type.
278 * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
279 * System, Alarm, Notification, Emergency, Voice Information, Ringtone VOIP and Ringtone Call stream types are not supported in this API.
281 * @param[in] input The handle to the audio input
282 * @param[in] stream_info The handle of stream information
283 * @return @c 0 on success,
284 * otherwise a negative error value
285 * @retval #AUDIO_IO_ERROR_NONE Successful
286 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
287 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
288 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
289 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
291 * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
292 * Call audio_in_create() before calling this function.
293 * @post Call audio_in_prepare() after calling this function.
294 * @see sound_manager_create_stream_information()
295 * @see sound_manager_destroy_stream_information()
297 int audio_in_set_stream_info(audio_in_h input, sound_stream_info_h stream_info);
300 * @brief Prepares the audio input for reading audio data by starting buffering of audio data from the device.
302 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
304 * @param[in] input The handle to the audio input
305 * @return @c 0 on success,
306 * otherwise a negative error value
307 * @retval #AUDIO_IO_ERROR_NONE Successful
308 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
309 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
310 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
312 * @post The state will be #AUDIO_IO_STATE_RUNNING.
313 * @see audio_in_unprepare()
315 int audio_in_prepare(audio_in_h input);
318 * @brief Unprepares the audio input.
320 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
322 * @param[in] input The handle to the audio input
323 * @return @c 0 on success,
324 * otherwise a negative error value
325 * @retval #AUDIO_IO_ERROR_NONE Successful
326 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
327 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
328 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
330 * @post The state will be #AUDIO_IO_STATE_IDLE.
331 * @see audio_in_prepare()
333 int audio_in_unprepare(audio_in_h input);
336 * @brief Pauses buffering of audio data from the device.
340 * @param[in] input The handle to the audio input
341 * @return @c 0 on success,
342 * otherwise a negative error value
343 * @retval #AUDIO_IO_ERROR_NONE Successful
344 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
345 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
346 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
348 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
349 * @post The state will be #AUDIO_IO_STATE_PAUSED.
350 * @see audio_in_resume()
352 int audio_in_pause(audio_in_h input);
355 * @brief Resumes buffering audio data from the device.
359 * @param[in] input The handle to the audio input
360 * @return @c 0 on success,
361 * otherwise a negative error value
362 * @retval #AUDIO_IO_ERROR_NONE Successful
363 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
364 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
365 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
367 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
368 * @post The state will be #AUDIO_IO_STATE_RUNNING.
369 * @see audio_in_pause()
371 int audio_in_resume(audio_in_h input);
374 * @brief Flushes and discards buffered audio data from the input stream.
378 * @param[in] input The handle to the audio input
379 * @return @c 0 on success,
380 * otherwise a negative error value
381 * @retval #AUDIO_IO_ERROR_NONE Successful
382 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
383 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
384 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
386 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
388 int audio_in_flush(audio_in_h input);
391 * @brief Reads audio data from the audio input buffer.
393 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
395 * @param[in] input The handle to the audio input
396 * @param[out] buffer The PCM buffer address
397 * @param[in] length The length of the PCM data buffer (in bytes)
398 * @return The number of read bytes on success,
399 * otherwise a negative error value
400 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
401 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
402 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
403 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
404 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
406 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
408 int audio_in_read(audio_in_h input, void *buffer, unsigned int length);
411 * @brief Gets the size to be allocated for the audio input buffer.
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] size The buffer size (in bytes, the maximum size is 1 MB)
417 * @return @c 0 on success,
418 * otherwise a negative error value
419 * @retval #AUDIO_IO_ERROR_NONE Successful
420 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
421 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
422 * @see audio_in_read()
424 int audio_in_get_buffer_size(audio_in_h input, int *size);
427 * @brief Gets the sample rate of the audio input data stream.
429 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
431 * @param[in] input The handle to the audio input
432 * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
433 * @return @c 0 on success,
434 * otherwise a negative error value
435 * @retval #AUDIO_IO_ERROR_NONE Successful
436 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
437 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
439 int audio_in_get_sample_rate(audio_in_h input, int *sample_rate);
442 * @brief Gets the channel type of the audio input data stream.
444 * @details The audio channel type defines whether the audio is mono or stereo.
446 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
448 * @param[in] input The handle to the audio input
449 * @param[out] channel The audio channel type
450 * @return @c 0 on success,
451 * otherwise a negative error value
452 * @retval #AUDIO_IO_ERROR_NONE Successful
453 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
454 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
456 int audio_in_get_channel(audio_in_h input, audio_channel_e *channel);
459 * @brief Gets the sample audio format (8-bit or 16-bit) of the audio input data stream.
461 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
463 * @param[in] input The handle to the audio input
464 * @param[out] type The audio sample type
465 * @return @c 0 on success,
466 * otherwise a negative error value
467 * @retval #AUDIO_IO_ERROR_NONE Successful
468 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
469 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
471 int audio_in_get_sample_type(audio_in_h input, audio_sample_type_e *type);
474 * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
475 * @brief Registers a callback function to be invoked when the audio input handle is interrupted or the interrupt is completed.
477 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
479 * @param[in] input The handle to the audio input
480 * @param[in] callback The callback function to register
481 * @param[in] user_data The user data to be passed to the callback function
482 * @return @c 0 on success,
483 * otherwise a negative error value
484 * @retval #AUDIO_IO_ERROR_NONE Successful
485 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
486 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
487 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
488 * @post audio_io_interrupted_cb() will be invoked.
490 * @see audio_in_unset_interrupted_cb()
491 * @see audio_io_interrupted_cb()
493 int audio_in_set_interrupted_cb(audio_in_h input, audio_io_interrupted_cb callback, void *user_data);
496 * @deprecated Deprecated since 3.0
497 * @brief Unregisters the callback function.
499 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
501 * @param[in] input The handle to the audio input
502 * @return @c 0 on success,
503 * otherwise a negative error value
504 * @retval #AUDIO_IO_ERROR_NONE Successful
505 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
506 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
507 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
509 * @see audio_in_set_interrupted_cb()
511 int audio_in_unset_interrupted_cb(audio_in_h input);
514 * @deprecated Deprecated since 3.0
515 * @brief Ignores session for input.
517 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
519 * @param[in] input The handle to the audio input
520 * @return @c 0 on success,
521 * otherwise a negative error value
522 * @retval #AUDIO_IO_ERROR_NONE Successful
523 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
524 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
525 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
527 int audio_in_ignore_session(audio_in_h input);
530 * @brief Sets an asynchronous(event) callback function to handle recording PCM (pulse-code modulation) data.
532 * @details @a callback will be called when you can read a PCM data.
533 * It might cause dead lock if change the state of audio handle in callback.
534 * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare)
535 * Recommend to use as a VOIP only.
536 * Recommend not to hold callback too long.(it affects latency)
538 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
540 * @remarks @a input must be created using audio_in_create().
542 * @param[in] input An audio input handle
543 * @param[in] callback notify stream callback when user can read data (#audio_in_stream_cb)
544 * @param[in] user_data user data to be retrieved when callback is called
545 * @return @c 0 on success,
546 * otherwise a negative error value
547 * @retval #AUDIO_IO_ERROR_NONE Successful
548 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
549 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
550 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
551 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
552 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
554 * @see audio_out_set_stream_cb()
556 int audio_in_set_stream_cb(audio_in_h input, audio_in_stream_cb callback, void* user_data);
559 * @brief Unregisters the callback function.
561 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
563 * @param[in] input The handle to the audio input
564 * @return @c 0 on success,
565 * otherwise a negative error value
566 * @retval #AUDIO_IO_ERROR_NONE Successful
567 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
568 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
569 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
571 * @see audio_in_set_interrupted_cb()
573 int audio_in_unset_stream_cb(audio_in_h input);
576 * @brief peek from audio in buffer
578 * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
580 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
582 * @remarks @a Works only in asynchronous(event) mode. This will just retrieve buffer pointer from audio in buffer. Drop after use.
584 * @param[in] input The handle to the audio input
585 * @param[out] buffer start buffer pointer of peeked audio in data
586 * @param[in,out] length amount of audio in data to be peeked
587 * @return @c 0 on success,
588 * otherwise a negative error value
589 * @retval #AUDIO_IO_ERROR_NONE Successful
590 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
591 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
592 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
593 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
595 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
596 * @see audio_in_drop()
598 int audio_in_peek(audio_in_h input, const void **buffer, unsigned int *length);
601 * @brief drop peeked audio buffer.
603 * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
605 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
607 * @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.
609 * @param[in] input The handle to the audio input
610 * @return 0 on success, otherwise a negative error value
611 * @retval #AUDIO_IO_ERROR_NONE Successful
612 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
613 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
614 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
615 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
617 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
618 * @see audio_in_peek()
620 int audio_in_drop(audio_in_h input);
623 * @brief Sets the state changed callback function to the audio input handle.
627 * @remarks @a input must be created using audio_in_create().
629 * @param[in] input The audio input handle
630 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_in_state_changed_cb)
631 * @param[in] user_data user data to be retrieved when callback is called
632 * @return @c 0 on success,
633 * otherwise a negative error value
634 * @retval #AUDIO_IO_ERROR_NONE Successful
635 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
636 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
638 * @see audio_in_unset_state_changed_cb()
640 int audio_in_set_state_changed_cb(audio_in_h input, audio_in_state_changed_cb callback, void* user_data);
643 * @brief Unregisters the state changed callback function of the audio input handle.
647 * @param[in] input The handle to the audio input
648 * @return @c 0 on success,
649 * otherwise a negative error value
650 * @retval #AUDIO_IO_ERROR_NONE Successful
651 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
652 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
654 * @see audio_in_set_state_changed_cb()
656 int audio_in_unset_state_changed_cb(audio_in_h input);
667 * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
672 * @brief Called when audio out data can be written in asynchronous(event) mode.
674 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
676 * @remarks @a use audio_out_write() to write pcm data inside this callback.
677 * @param[in] handle The handle to the audio output
678 * @param[in] nbytes The amount of audio in data which can be written.
679 * @param[in] user_data The user data passed from the callback registration function
681 * @see audio_out_set_stream_cb()
683 typedef void (*audio_out_stream_cb)(audio_out_h handle, size_t nbytes, void *user_data);
686 * @brief Called when the state of audio output is changed.
690 * @param[in] handle The handle of the audio output
691 * @param[in] previous The previous state of the audio output
692 * @param[in] current The current state of the audio output
693 * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
694 * @param[in] user_data The user data passed from the callback registration function
696 * @see audio_out_set_state_changed_cb()
697 * @see audio_out_unset_state_changed_cb()
699 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);
702 * @deprecated Deprecated since 3.0. Use audio_out_create_new() instead.
703 * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
705 * @details This function is used for audio output initialization.
707 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
709 * @remarks @a output must be released by audio_out_destroy().
711 * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
712 * @param[in] channel The audio channel type (mono or stereo)
713 * @param[in] type The type of audio sample (8-bit or 16-bit)
714 * @param[in] sound_type The type of sound (#sound_type_e)
715 * @param[out] output An audio output handle is created on success
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_OUT_OF_MEMORY Out of memory
721 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
722 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
724 * @see audio_out_destroy()
726 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);
729 * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
731 * @details This function is used for audio output initialization.
735 * @remarks @a output must be released by audio_out_destroy().
736 * It is recommended to call audio_out_set_stream_info() after this API.
738 * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
739 * @param[in] channel The audio channel type (mono or stereo)
740 * @param[in] type The type of audio sample (8-bit or 16-bit)
741 * @param[out] output An audio output handle is created on success
742 * @return @c 0 on success,
743 * otherwise a negative error value
744 * @retval #AUDIO_IO_ERROR_NONE Successful
745 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
746 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
747 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
748 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
750 * @post The state will be #AUDIO_IO_STATE_IDLE.\n
751 * audio_out_set_stream_info() is recommended to be called after this API.
752 * @see audio_out_destroy()
754 int audio_out_create_new(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_out_h *output);
757 * @brief Releases the audio output handle, along with all its resources.
759 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
761 * @param[in] output The handle to the audio output to destroy
762 * @return @c 0 on success,
763 * otherwise a negative error value
764 * @retval #AUDIO_IO_ERROR_NONE Successful
765 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
766 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
767 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
769 * @see audio_out_create()
771 int audio_out_destroy(audio_out_h output);
774 * @brief Sets the sound stream information to the audio output.
778 * @remarks @a the sound stream information includes audio routing and volume type.
779 * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
780 * Voice Recognition and Loopback stream types are not supported in this API.
782 * @param[in] output The handle to the audio output
783 * @param[in] stream_info The handle of stream information
784 * @return @c 0 on success,
785 * otherwise a negative error value
786 * @retval #AUDIO_IO_ERROR_NONE Successful
787 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
788 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
789 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
790 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
792 * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
793 * Call audio_out_create_new() before calling this function.
794 * @post Call audio_out_prepare() after calling this function.
795 * @see sound_manager_create_stream_information()
796 * @see sound_manager_destroy_stream_information()
798 int audio_out_set_stream_info(audio_out_h output, sound_stream_info_h stream_info);
801 * @brief Prepares the audio output for playback, this must be called before audio_out_write().
803 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
805 * @param[in] output The handle to the audio output
806 * @return @c 0 on success,
807 * otherwise a negative error value
808 * @retval #AUDIO_IO_ERROR_NONE Successful
809 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
810 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
812 * @post The state will be #AUDIO_IO_STATE_RUNNING.
813 * @see audio_out_unprepare()
815 int audio_out_prepare(audio_out_h output);
818 * @brief Unprepares the audio output.
820 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
822 * @param[in] output The handle to the audio output
823 * @return @c 0 on success,
824 * otherwise a negative error value
825 * @retval #AUDIO_IO_ERROR_NONE Successful
826 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
827 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
829 * @post The state will be #AUDIO_IO_STATE_IDLE.
830 * @see audio_out_prepare()
832 int audio_out_unprepare(audio_out_h output);
835 * @brief Pauses feeding of audio data to the device.
839 * @param[in] output The handle to the audio output
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
844 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
846 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
847 * @post The state will be #AUDIO_IO_STATE_PAUSED.
848 * @see audio_out_resume()
850 int audio_out_pause(audio_out_h output);
853 * @brief Resumes feeding of audio data to the device.
857 * @param[in] output The handle to the audio output
858 * @return @c 0 on success,
859 * otherwise a negative error value
860 * @retval #AUDIO_IO_ERROR_NONE Successful
861 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
862 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
864 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
865 * @post The state will be #AUDIO_IO_STATE_RUNNING.
866 * @see audio_out_pause()
868 int audio_out_resume(audio_out_h output);
871 * @brief Drains buffered audio data from the output stream.
873 * @details This function waits until drains stream buffer completely. (e.g end of playback)
877 * @param[in] output The handle to the audio output
878 * @return @c 0 on success,
879 * otherwise a negative error value
880 * @retval #AUDIO_IO_ERROR_NONE Successful
881 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
882 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
884 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
885 * @see audio_out_flush()
887 int audio_out_drain(audio_out_h output);
890 * @brief Flushes and discards buffered audio data from the output stream.
894 * @param[in] output The handle to the audio output
895 * @return @c 0 on success,
896 * otherwise a negative error value
897 * @retval #AUDIO_IO_ERROR_NONE Successful
898 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
899 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
901 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
902 * @see audio_out_drain()
904 int audio_out_flush(audio_out_h output);
907 * @brief Starts writing the audio data to the device.
909 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
911 * @param[in] output The handle to the audio output
912 * @param[in,out] buffer The PCM buffer address
913 * @param[in] length The length of the PCM buffer (in bytes)
914 * @return The written data size on success,
915 * otherwise a negative error value
916 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
917 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
918 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
919 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
921 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
923 int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
926 * @brief Gets the size to be allocated for the audio output buffer.
928 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
930 * @param[in] output The handle to the audio output
931 * @param[out] size The suggested buffer size (in bytes, the maximum size is 1 MB)
932 * @return @c 0 on success,
933 * otherwise a negative error value
934 * @retval #AUDIO_IO_ERROR_NONE Successful
935 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
937 * @see audio_out_write()
939 int audio_out_get_buffer_size(audio_out_h output, int *size);
942 * @brief Gets the sample rate of the audio output data stream.
944 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
946 * @param[in] output The handle to the audio output
947 * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
948 * @return @c 0 on success,
949 * otherwise a negative error value
950 * @retval #AUDIO_IO_ERROR_NONE Successful
951 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
953 int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
956 * @brief Gets the channel type of the audio output data stream.
958 * @details The audio channel type defines whether the audio is mono or stereo.
960 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
962 * @param[in] output The handle to the audio output
963 * @param[out] channel The audio channel type
964 * @return @c 0 on success,
965 * otherwise a negative error value
966 * @retval #AUDIO_IO_ERROR_NONE Successful
967 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
969 int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
972 * @brief Gets the sample audio format (8-bit or 16-bit) of the audio output data stream.
974 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
976 * @param[in] output The handle to the audio output
977 * @param[out] type The audio sample type
978 * @return @c 0 on success,
979 * otherwise a negative error value
980 * @retval #AUDIO_IO_ERROR_NONE Successful
981 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
983 int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
986 * @brief Gets the sound type supported by the audio output device.
988 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
990 * @param[in] output The handle to the audio output
991 * @param[out] type The sound type
992 * @return @c 0 on success,
993 * otherwise a negative error value
994 * @retval #AUDIO_IO_ERROR_NONE Successful
995 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
997 int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
1000 * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
1001 * @brief Registers a callback function to be invoked when the audio output handle is interrupted or the interrupt is completed.
1003 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1005 * @param[in] output The handle to the audio output
1006 * @param[in] callback The callback function to register
1007 * @param[in] user_data The user data to be passed to the callback function
1008 * @return @c 0 on success,
1009 * otherwise a negative error value
1010 * @retval #AUDIO_IO_ERROR_NONE Successful
1011 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1012 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1014 * @post audio_io_interrupted_cb() will be invoked.
1015 * @see audio_out_unset_interrupted_cb()
1016 * @see audio_io_interrupted_cb()
1018 int audio_out_set_interrupted_cb(audio_out_h output, audio_io_interrupted_cb callback, void *user_data);
1021 * @deprecated Deprecated since 3.0
1022 * @brief Unregisters the callback function.
1024 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1026 * @param[in] output The handle to the audio output
1027 * @return @c 0 on success,
1028 * otherwise a negative error value
1029 * @retval #AUDIO_IO_ERROR_NONE Successful
1030 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1031 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1033 * @see audio_out_set_interrupted_cb()
1035 int audio_out_unset_interrupted_cb(audio_out_h output);
1038 * @deprecated Deprecated since 3.0
1039 * @brief Ignores session for output.
1041 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1043 * @param[in] output The handle to the audio output
1044 * @return @c 0 on success,
1045 * otherwise a negative error value
1046 * @retval #AUDIO_IO_ERROR_NONE Successful
1047 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1048 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1050 int audio_out_ignore_session(audio_out_h output);
1053 * @brief Sets an asynchronous(event) callback function to handle playing PCM (pulse-code modulation) data.
1055 * @details @a callback will be called when you can write a PCM data.
1056 * It might cause dead lock if change the state of audio handle in callback.
1057 * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare)
1058 * Recommend to use as a VOIP only.
1059 * Recommend not to hold callback too long.(it affects latency)
1061 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1063 * @remarks @a output must be created using audio_out_create().
1065 * @param[in] output An audio output handle
1066 * @param[in] callback notify stream callback when user can write data (#audio_out_stream_cb)
1067 * @param[in] user_data user data to be retrieved when callback is called
1068 * @return 0 on success, otherwise a negative error value
1069 * @retval #AUDIO_IO_ERROR_NONE Successful
1070 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1071 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
1072 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
1073 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
1075 * @see audio_in_set_stream_cb()
1077 int audio_out_set_stream_cb(audio_out_h output, audio_out_stream_cb callback, void* user_data);
1080 * @brief Unregisters the callback function.
1082 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1084 * @param[in] output The handle to the audio output
1085 * @return 0 on success, otherwise a negative error value
1086 * @retval #AUDIO_IO_ERROR_NONE Successful
1087 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1088 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1090 * @see audio_out_set_stream_cb()
1092 int audio_out_unset_stream_cb(audio_out_h output);
1095 * @brief Sets the state changed callback function to the audio output handle.
1099 * @remarks @a input must be created using audio_out_create_new().
1101 * @param[in] output The audio output handle
1102 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_out_state_changed_cb)
1103 * @param[in] user_data user data to be retrieved when callback is called
1104 * @return @c 0 on success,
1105 * otherwise a negative error value
1106 * @retval #AUDIO_IO_ERROR_NONE Successful
1107 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1109 * @see audio_out_unset_state_changed_cb()
1111 int audio_out_set_state_changed_cb(audio_out_h output, audio_out_state_changed_cb callback, void* user_data);
1114 * @brief Unregisters the state changed callback function of the audio output handle.
1118 * @param[in] output The handle to the audio output
1119 * @return @c 0 on success,
1120 * otherwise a negative error value
1121 * @retval #AUDIO_IO_ERROR_NONE Successful
1122 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1124 * @see audio_out_set_state_changed_cb()
1126 int audio_out_unset_state_changed_cb(audio_out_h output);
1136 #endif /* __TIZEN_MEDIA_AUDIO_IO_H__ */