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
74 AUDIO_SAMPLE_TYPE_U8 = 0x70, /**< Unsigned 8-bit audio samples */
75 AUDIO_SAMPLE_TYPE_S16_LE, /**< Signed 16-bit audio samples */
76 } audio_sample_type_e;
79 * @brief Enumeration for audio channel.
80 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
83 AUDIO_CHANNEL_MONO = 0x80, /**< 1 channel, mono */
84 AUDIO_CHANNEL_STEREO, /**< 2 channel, stereo */
88 * @brief Enumeration for audio input and output state.
92 AUDIO_IO_STATE_IDLE, /**< Audio-io handle is created, but not prepared */
93 AUDIO_IO_STATE_RUNNING, /**< Audio-io handle is ready and the stream is running */
94 AUDIO_IO_STATE_PAUSED, /**< Audio-io handle is ready and the stream is paused */
98 * @brief Enumeration for audio input and output error.
99 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
102 AUDIO_IO_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
103 AUDIO_IO_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
104 AUDIO_IO_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
105 AUDIO_IO_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION, /**< Invalid operation */
106 AUDIO_IO_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Device open error by security */
107 AUDIO_IO_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
108 AUDIO_IO_ERROR_DEVICE_NOT_OPENED = TIZEN_ERROR_AUDIO_IO | 0x01, /**< Device open error */
109 AUDIO_IO_ERROR_DEVICE_NOT_CLOSED = TIZEN_ERROR_AUDIO_IO | 0x02, /**< Device close error */
110 AUDIO_IO_ERROR_INVALID_BUFFER = TIZEN_ERROR_AUDIO_IO | 0x03, /**< Invalid buffer pointer */
111 AUDIO_IO_ERROR_SOUND_POLICY = TIZEN_ERROR_AUDIO_IO | 0x04, /**< Sound policy error */
112 AUDIO_IO_ERROR_INVALID_STATE = TIZEN_ERROR_AUDIO_IO | 0x05, /**< Invalid state (Since 3.0) */
113 AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE = TIZEN_ERROR_AUDIO_IO | 0x06, /**< Not supported stream type (Since 3.0) */
117 * @deprecated Deprecated since 3.0
118 * @brief Enumeration for audio IO interrupted messages.
119 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
122 AUDIO_IO_INTERRUPTED_COMPLETED = 0, /**< Interrupt completed */
123 AUDIO_IO_INTERRUPTED_BY_MEDIA, /**< Interrupted by a media application */
124 AUDIO_IO_INTERRUPTED_BY_CALL, /**< Interrupted by an incoming call */
125 AUDIO_IO_INTERRUPTED_BY_EARJACK_UNPLUG, /**< Interrupted by unplugging headphones */
126 AUDIO_IO_INTERRUPTED_BY_RESOURCE_CONFLICT, /**< Interrupted by a resource conflict */
127 AUDIO_IO_INTERRUPTED_BY_ALARM, /**< Interrupted by an alarm */
128 AUDIO_IO_INTERRUPTED_BY_EMERGENCY, /**< Interrupted by an emergency */
129 AUDIO_IO_INTERRUPTED_BY_NOTIFICATION, /**< Interrupted by a notification */
130 } audio_io_interrupted_code_e;
133 * @deprecated Deprecated since 3.0. Use sound_stream_focus_state_changed_cb instead.
134 * @brief Called when audio input or output is interrupted.
136 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
137 * @param[in] error_code The interrupted error code
138 * @param[in] user_data The user data passed from the callback registration function
140 * @see audio_in_set_interrupted_cb()
141 * @see audio_out_set_interrupted_cb()
142 * @see audio_in_unset_interrupted_cb()
143 * @see audio_out_unset_interrupted_cb()
145 typedef void (*audio_io_interrupted_cb)(audio_io_interrupted_code_e code, void *user_data);
152 * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
157 * @brief Called when audio input data is available in asynchronous(event) mode.
159 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
161 * @remarks @a use audio_in_peek() to get audio in data inside callback, use audio_in_drop() after use of peeked data.
163 * @param[in] handle The handle to the audio input
164 * @param[in] nbytes The amount of available audio in data which can be peeked.
165 * @param[in] user_data The user data passed from the callback registration function
167 * @see audio_in_set_stream_cb()
169 typedef void (*audio_in_stream_cb)(audio_in_h handle, size_t nbytes, void *user_data);
172 * @brief Called when the state of audio input is changed.
176 * @param[in] handle The handle of the audio input
177 * @param[in] previous The previous state of the audio input
178 * @param[in] current The current state of the audio input
179 * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
180 * @param[in] user_data The user data passed from the callback registration function
182 * @see audio_in_set_state_changed_cb()
183 * @see audio_in_unset_state_changed_cb()
185 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);
188 * @brief Creates an audio device instance and returns an input handle to record PCM (pulse-code modulation) data.
190 * @details This function is used for audio input initialization.
192 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
194 * @privilege %http://tizen.org/privilege/recorder
196 * @remarks @a input must be released using audio_in_destroy().
198 * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
199 * @param[in] channel The audio channel type (mono or stereo)
200 * @param[in] type The type of audio sample (8- or 16-bit)
201 * @param[out] input An audio input handle is created on success
202 * @return @c 0 on success,
203 * otherwise a negative error value
204 * @retval #AUDIO_IO_ERROR_NONE Successful
205 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
206 * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
207 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
208 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
209 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
210 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
212 * @post The state will be #AUDIO_IO_STATE_IDLE.\n
213 * audio_in_set_stream_info() is recommended to be called after this API.
214 * @see audio_in_destroy()
216 int audio_in_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_in_h *input);
219 * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
220 * @brief Creates an audio loopback device instance and returns an input handle to record PCM (pulse-code modulation) data.
222 * @details This function is used for audio loopback input initialization.
224 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
226 * @privilege %http://tizen.org/privilege/recorder
228 * @remarks @a input must be released using audio_in_destroy().
230 * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
231 * @param[in] channel The audio channel type, mono, or stereo
232 * @param[in] type The type of audio sample (8- or 16-bit)
233 * @param[out] input An audio input handle will be created, if successful
234 * @return @c 0 on success,
235 * otherwise a negative error value
236 * @retval #AUDIO_IO_ERROR_NONE Successful
237 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
238 * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
239 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
240 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
241 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
242 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
244 * @see audio_in_destroy()
246 int audio_in_create_loopback(int sample_rate, audio_channel_e channel, audio_sample_type_e type , audio_in_h* input);
249 * @brief Releases the audio input handle and all its resources associated with an audio stream.
251 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
253 * @param[in] input The handle to the audio input to destroy
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_DEVICE_NOT_CLOSED Device not closed
259 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
261 * @see audio_in_create()
263 int audio_in_destroy(audio_in_h input);
266 * @brief Sets the sound stream information to the audio input.
270 * @remarks @a the sound stream information includes audio routing and volume type.
271 * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
272 * System, Alarm, Notification, Emergency, Voice Information, Ringtone VOIP and Ringtone Call stream types are not supported in this API.
274 * @param[in] input The handle to the audio input
275 * @param[in] stream_info The handle of stream information
276 * @return @c 0 on success,
277 * otherwise a negative error value
278 * @retval #AUDIO_IO_ERROR_NONE Successful
279 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
280 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
281 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
282 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
284 * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
285 * Call audio_in_create() before calling this function.
286 * @post Call audio_in_prepare() after calling this function.
287 * @see sound_manager_create_stream_information()
288 * @see sound_manager_destroy_stream_information()
290 int audio_in_set_stream_info(audio_in_h input, sound_stream_info_h stream_info);
293 * @brief Prepares the audio input for reading audio data by starting buffering of audio data from the device.
295 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
297 * @param[in] input The handle to the audio input
298 * @return @c 0 on success,
299 * otherwise a negative error value
300 * @retval #AUDIO_IO_ERROR_NONE Successful
301 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
302 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
303 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
305 * @post The state will be #AUDIO_IO_STATE_RUNNING.
306 * @see audio_in_unprepare()
308 int audio_in_prepare(audio_in_h input);
311 * @brief Unprepares the audio input.
313 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
315 * @param[in] input The handle to the audio input
316 * @return @c 0 on success,
317 * otherwise a negative error value
318 * @retval #AUDIO_IO_ERROR_NONE Successful
319 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
320 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
321 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
323 * @post The state will be #AUDIO_IO_STATE_IDLE.
324 * @see audio_in_prepare()
326 int audio_in_unprepare(audio_in_h input);
329 * @brief Pauses buffering of audio data from the device.
333 * @param[in] input The handle to the audio input
334 * @return @c 0 on success,
335 * otherwise a negative error value
336 * @retval #AUDIO_IO_ERROR_NONE Successful
337 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
338 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
339 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
341 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
342 * @post The state will be #AUDIO_IO_STATE_PAUSED.
343 * @see audio_in_resume()
345 int audio_in_pause(audio_in_h input);
348 * @brief Resumes buffering audio data from the device.
352 * @param[in] input The handle to the audio input
353 * @return @c 0 on success,
354 * otherwise a negative error value
355 * @retval #AUDIO_IO_ERROR_NONE Successful
356 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
357 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
358 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
360 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
361 * @post The state will be #AUDIO_IO_STATE_RUNNING.
362 * @see audio_in_pause()
364 int audio_in_resume(audio_in_h input);
367 * @brief Flushes and discards buffered audio data from the input stream.
371 * @param[in] input The handle to the audio input
372 * @return @c 0 on success,
373 * otherwise a negative error value
374 * @retval #AUDIO_IO_ERROR_NONE Successful
375 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
376 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
377 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
379 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
381 int audio_in_flush(audio_in_h input);
384 * @brief Reads audio data from the audio input buffer.
386 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
388 * @param[in] input The handle to the audio input
389 * @param[out] buffer The PCM buffer address
390 * @param[in] length The length of the PCM data buffer (in bytes)
391 * @return The number of read bytes on success,
392 * otherwise a negative error value
393 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
394 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
395 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
396 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
397 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
399 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
401 int audio_in_read(audio_in_h input, void *buffer, unsigned int length);
404 * @brief Gets the size to be allocated for the audio input buffer.
406 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
408 * @param[in] input The handle to the audio input
409 * @param[out] size The buffer size (in bytes, the maximum size is 1 MB)
410 * @return @c 0 on success,
411 * otherwise a negative error value
412 * @retval #AUDIO_IO_ERROR_NONE Successful
413 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
414 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
415 * @see audio_in_read()
417 int audio_in_get_buffer_size(audio_in_h input, int *size);
420 * @brief Gets the sample rate of the audio input data stream.
422 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
424 * @param[in] input The handle to the audio input
425 * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
426 * @return @c 0 on success,
427 * otherwise a negative error value
428 * @retval #AUDIO_IO_ERROR_NONE Successful
429 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
430 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
432 int audio_in_get_sample_rate(audio_in_h input, int *sample_rate);
435 * @brief Gets the channel type of the audio input data stream.
437 * @details The audio channel type defines whether the audio is mono or stereo.
439 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
441 * @param[in] input The handle to the audio input
442 * @param[out] channel The audio channel type
443 * @return @c 0 on success,
444 * otherwise a negative error value
445 * @retval #AUDIO_IO_ERROR_NONE Successful
446 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
447 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
449 int audio_in_get_channel(audio_in_h input, audio_channel_e *channel);
452 * @brief Gets the sample audio format (8-bit or 16-bit) of the audio input data stream.
454 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
456 * @param[in] input The handle to the audio input
457 * @param[out] type The audio sample type
458 * @return @c 0 on success,
459 * otherwise a negative error value
460 * @retval #AUDIO_IO_ERROR_NONE Successful
461 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
462 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
464 int audio_in_get_sample_type(audio_in_h input, audio_sample_type_e *type);
467 * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
468 * @brief Registers a callback function to be invoked when the audio input handle is interrupted or the interrupt is completed.
470 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
472 * @param[in] input The handle to the audio input
473 * @param[in] callback The callback function to register
474 * @param[in] user_data The user data to be passed to the callback function
475 * @return @c 0 on success,
476 * otherwise a negative error value
477 * @retval #AUDIO_IO_ERROR_NONE Successful
478 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
479 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
480 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
481 * @post audio_io_interrupted_cb() will be invoked.
483 * @see audio_in_unset_interrupted_cb()
484 * @see audio_io_interrupted_cb()
486 int audio_in_set_interrupted_cb(audio_in_h input, audio_io_interrupted_cb callback, void *user_data);
489 * @deprecated Deprecated since 3.0
490 * @brief Unregisters the callback function.
492 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
494 * @param[in] input The handle to the audio input
495 * @return @c 0 on success,
496 * otherwise a negative error value
497 * @retval #AUDIO_IO_ERROR_NONE Successful
498 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
499 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
500 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
502 * @see audio_in_set_interrupted_cb()
504 int audio_in_unset_interrupted_cb(audio_in_h input);
507 * @deprecated Deprecated since 3.0
508 * @brief Ignores session for input.
510 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
512 * @param[in] input The handle to the audio input
513 * @return @c 0 on success,
514 * otherwise a negative error value
515 * @retval #AUDIO_IO_ERROR_NONE Successful
516 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
517 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
518 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
520 int audio_in_ignore_session(audio_in_h input);
523 * @brief Sets an asynchronous(event) callback function to handle recording PCM (pulse-code modulation) data.
525 * @details @a callback will be called when you can read a PCM data.
526 * It might cause dead lock if change the state of audio handle in callback.
527 * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare)
528 * Recommend to use as a VOIP only.
529 * Recommend not to hold callback too long.(it affects latency)
531 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
533 * @remarks @a input must be created using audio_in_create().
535 * @param[in] input An audio input handle
536 * @param[in] callback notify stream callback when user can read data (#audio_in_stream_cb)
537 * @param[in] user_data user data to be retrieved when callback is called
538 * @return @c 0 on success,
539 * otherwise a negative error value
540 * @retval #AUDIO_IO_ERROR_NONE Successful
541 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
542 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
543 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
544 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
545 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
547 * @see audio_out_set_stream_cb()
549 int audio_in_set_stream_cb(audio_in_h input, audio_in_stream_cb callback, void* user_data);
552 * @brief Unregisters the callback function.
554 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
556 * @param[in] input The handle to the audio input
557 * @return @c 0 on success,
558 * otherwise a negative error value
559 * @retval #AUDIO_IO_ERROR_NONE Successful
560 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
561 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
562 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
564 * @see audio_in_set_interrupted_cb()
566 int audio_in_unset_stream_cb(audio_in_h input);
569 * @brief peek from audio in buffer
571 * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
573 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
575 * @remarks @a Works only in asynchronous(event) mode. This will just retrieve buffer pointer from audio in buffer. Drop after use.
577 * @param[in] input The handle to the audio input
578 * @param[out] buffer start buffer pointer of peeked audio in data
579 * @param[in,out] length amount of audio in data to be peeked
580 * @return @c 0 on success,
581 * otherwise a negative error value
582 * @retval #AUDIO_IO_ERROR_NONE Successful
583 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
584 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
585 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
586 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
588 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
589 * @see audio_in_drop()
591 int audio_in_peek(audio_in_h input, const void **buffer, unsigned int *length);
594 * @brief drop peeked audio buffer.
596 * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
598 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
600 * @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.
602 * @param[in] input The handle to the audio input
603 * @return 0 on success, otherwise a negative error value
604 * @retval #AUDIO_IO_ERROR_NONE Successful
605 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
606 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
607 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
608 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
610 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
611 * @see audio_in_peek()
613 int audio_in_drop(audio_in_h input);
616 * @brief Sets the state changed callback function to the audio input handle.
620 * @remarks @a input must be created using audio_in_create().
622 * @param[in] input The audio input handle
623 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_in_state_changed_cb)
624 * @param[in] user_data user data to be retrieved when callback is called
625 * @return @c 0 on success,
626 * otherwise a negative error value
627 * @retval #AUDIO_IO_ERROR_NONE Successful
628 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
629 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
631 * @see audio_in_unset_state_changed_cb()
633 int audio_in_set_state_changed_cb(audio_in_h input, audio_in_state_changed_cb callback, void* user_data);
636 * @brief Unregisters the state changed callback function of the audio input handle.
640 * @param[in] input The handle to the audio input
641 * @return @c 0 on success,
642 * otherwise a negative error value
643 * @retval #AUDIO_IO_ERROR_NONE Successful
644 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
645 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
647 * @see audio_in_set_state_changed_cb()
649 int audio_in_unset_state_changed_cb(audio_in_h input);
656 * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
661 * @brief Called when audio out data can be written in asynchronous(event) mode.
663 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
665 * @remarks @a use audio_out_write() to write pcm data inside this callback.
666 * @param[in] handle The handle to the audio output
667 * @param[in] nbytes The amount of audio in data which can be written.
668 * @param[in] user_data The user data passed from the callback registration function
670 * @see audio_out_set_stream_cb()
672 typedef void (*audio_out_stream_cb)(audio_out_h handle, size_t nbytes, void *user_data);
675 * @brief Called when the state of audio output is changed.
679 * @param[in] handle The handle of the audio output
680 * @param[in] previous The previous state of the audio output
681 * @param[in] current The current state of the audio output
682 * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
683 * @param[in] user_data The user data passed from the callback registration function
685 * @see audio_out_set_state_changed_cb()
686 * @see audio_out_unset_state_changed_cb()
688 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);
691 * @deprecated Deprecated since 3.0. Use audio_out_create_new() instead.
692 * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
694 * @details This function is used for audio output initialization.
696 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
698 * @remarks @a output must be released by audio_out_destroy().
700 * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
701 * @param[in] channel The audio channel type (mono or stereo)
702 * @param[in] type The type of audio sample (8-bit or 16-bit)
703 * @param[in] sound_type The type of sound (#sound_type_e)
704 * @param[out] output An audio output handle is created on success
705 * @return @c 0 on success,
706 * otherwise a negative error value
707 * @retval #AUDIO_IO_ERROR_NONE Successful
708 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
709 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
710 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
711 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
713 * @see audio_out_destroy()
715 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);
718 * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
720 * @details This function is used for audio output initialization.
724 * @remarks @a output must be released by audio_out_destroy().
725 * It is recommended to call audio_out_set_stream_info() after this API.
727 * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
728 * @param[in] channel The audio channel type (mono or stereo)
729 * @param[in] type The type of audio sample (8-bit or 16-bit)
730 * @param[out] output An audio output handle is created on success
731 * @return @c 0 on success,
732 * otherwise a negative error value
733 * @retval #AUDIO_IO_ERROR_NONE Successful
734 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
735 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
736 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
737 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
739 * @post The state will be #AUDIO_IO_STATE_IDLE.\n
740 * audio_out_set_stream_info() is recommended to be called after this API.
741 * @see audio_out_destroy()
743 int audio_out_create_new(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_out_h *output);
746 * @brief Releases the audio output handle, along with all its resources.
748 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
750 * @param[in] output The handle to the audio output to destroy
751 * @return @c 0 on success,
752 * otherwise a negative error value
753 * @retval #AUDIO_IO_ERROR_NONE Successful
754 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
755 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
756 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
758 * @see audio_out_create()
760 int audio_out_destroy(audio_out_h output);
763 * @brief Sets the sound stream information to the audio output.
767 * @remarks @a the sound stream information includes audio routing and volume type.
768 * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
769 * Voice Recognition and Loopback stream types are not supported in this API.
771 * @param[in] output The handle to the audio output
772 * @param[in] stream_info The handle of stream information
773 * @return @c 0 on success,
774 * otherwise a negative error value
775 * @retval #AUDIO_IO_ERROR_NONE Successful
776 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
777 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
778 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
779 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
781 * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
782 * Call audio_out_create_new() before calling this function.
783 * @post Call audio_out_prepare() after calling this function.
784 * @see sound_manager_create_stream_information()
785 * @see sound_manager_destroy_stream_information()
787 int audio_out_set_stream_info(audio_out_h output, sound_stream_info_h stream_info);
790 * @brief Prepares the audio output for playback, this must be called before audio_out_write().
792 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
794 * @param[in] output The handle to the audio output
795 * @return @c 0 on success,
796 * otherwise a negative error value
797 * @retval #AUDIO_IO_ERROR_NONE Successful
798 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
799 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
801 * @post The state will be #AUDIO_IO_STATE_RUNNING.
802 * @see audio_out_unprepare()
804 int audio_out_prepare(audio_out_h output);
807 * @brief Unprepares the audio output.
809 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
811 * @param[in] output The handle to the audio output
812 * @return @c 0 on success,
813 * otherwise a negative error value
814 * @retval #AUDIO_IO_ERROR_NONE Successful
815 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
816 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
818 * @post The state will be #AUDIO_IO_STATE_IDLE.
819 * @see audio_out_prepare()
821 int audio_out_unprepare(audio_out_h output);
824 * @brief Pauses feeding of audio data to the device.
828 * @param[in] output The handle to the audio output
829 * @return @c 0 on success,
830 * otherwise a negative error value
831 * @retval #AUDIO_IO_ERROR_NONE Successful
832 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
833 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
835 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
836 * @post The state will be #AUDIO_IO_STATE_PAUSED.
837 * @see audio_out_resume()
839 int audio_out_pause(audio_out_h output);
842 * @brief Resumes feeding of audio data to the device.
846 * @param[in] output The handle to the audio output
847 * @return @c 0 on success,
848 * otherwise a negative error value
849 * @retval #AUDIO_IO_ERROR_NONE Successful
850 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
851 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
853 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
854 * @post The state will be #AUDIO_IO_STATE_RUNNING.
855 * @see audio_out_pause()
857 int audio_out_resume(audio_out_h output);
860 * @brief Drains buffered audio data from the output stream.
862 * @details This function waits until drains stream buffer completely. (e.g end of playback)
866 * @param[in] output The handle to the audio output
867 * @return @c 0 on success,
868 * otherwise a negative error value
869 * @retval #AUDIO_IO_ERROR_NONE Successful
870 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
871 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
873 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
874 * @see audio_out_flush()
876 int audio_out_drain(audio_out_h output);
879 * @brief Flushes and discards buffered audio data from the output stream.
883 * @param[in] output The handle to the audio output
884 * @return @c 0 on success,
885 * otherwise a negative error value
886 * @retval #AUDIO_IO_ERROR_NONE Successful
887 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
888 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
890 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
891 * @see audio_out_drain()
893 int audio_out_flush(audio_out_h output);
896 * @brief Starts writing the audio data to the device.
898 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
900 * @param[in] output The handle to the audio output
901 * @param[in,out] buffer The PCM buffer address
902 * @param[in] length The length of the PCM buffer (in bytes)
903 * @return The written data size on success,
904 * otherwise a negative error value
905 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
906 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
907 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
908 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
910 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
912 int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
915 * @brief Gets the size to be allocated for the audio output buffer.
917 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
919 * @param[in] output The handle to the audio output
920 * @param[out] size The suggested buffer size (in bytes, the maximum size is 1 MB)
921 * @return @c 0 on success,
922 * otherwise a negative error value
923 * @retval #AUDIO_IO_ERROR_NONE Successful
924 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
926 * @see audio_out_write()
928 int audio_out_get_buffer_size(audio_out_h output, int *size);
931 * @brief Gets the sample rate of the audio output data stream.
933 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
935 * @param[in] output The handle to the audio output
936 * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
937 * @return @c 0 on success,
938 * otherwise a negative error value
939 * @retval #AUDIO_IO_ERROR_NONE Successful
940 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
942 int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
945 * @brief Gets the channel type of the audio output data stream.
947 * @details The audio channel type defines whether the audio is mono or stereo.
949 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
951 * @param[in] output The handle to the audio output
952 * @param[out] channel The audio channel type
953 * @return @c 0 on success,
954 * otherwise a negative error value
955 * @retval #AUDIO_IO_ERROR_NONE Successful
956 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
958 int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
961 * @brief Gets the sample audio format (8-bit or 16-bit) of the audio output data stream.
963 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
965 * @param[in] output The handle to the audio output
966 * @param[out] type The audio sample type
967 * @return @c 0 on success,
968 * otherwise a negative error value
969 * @retval #AUDIO_IO_ERROR_NONE Successful
970 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
972 int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
975 * @brief Gets the sound type supported by the audio output device.
977 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
979 * @param[in] output The handle to the audio output
980 * @param[out] type The sound type
981 * @return @c 0 on success,
982 * otherwise a negative error value
983 * @retval #AUDIO_IO_ERROR_NONE Successful
984 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
986 int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
989 * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
990 * @brief Registers a callback function to be invoked when the audio output handle is interrupted or the interrupt is completed.
992 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
994 * @param[in] output The handle to the audio output
995 * @param[in] callback The callback function to register
996 * @param[in] user_data The user data to be passed to the callback function
997 * @return @c 0 on success,
998 * otherwise a negative error value
999 * @retval #AUDIO_IO_ERROR_NONE Successful
1000 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1001 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1003 * @post audio_io_interrupted_cb() will be invoked.
1004 * @see audio_out_unset_interrupted_cb()
1005 * @see audio_io_interrupted_cb()
1007 int audio_out_set_interrupted_cb(audio_out_h output, audio_io_interrupted_cb callback, void *user_data);
1010 * @deprecated Deprecated since 3.0
1011 * @brief Unregisters the callback function.
1013 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1015 * @param[in] output The handle to the audio output
1016 * @return @c 0 on success,
1017 * otherwise a negative error value
1018 * @retval #AUDIO_IO_ERROR_NONE Successful
1019 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1020 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1022 * @see audio_out_set_interrupted_cb()
1024 int audio_out_unset_interrupted_cb(audio_out_h output);
1027 * @deprecated Deprecated since 3.0
1028 * @brief Ignores session for output.
1030 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1032 * @param[in] output The handle to the audio output
1033 * @return @c 0 on success,
1034 * otherwise a negative error value
1035 * @retval #AUDIO_IO_ERROR_NONE Successful
1036 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1037 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1039 int audio_out_ignore_session(audio_out_h output);
1042 * @brief Sets an asynchronous(event) callback function to handle playing PCM (pulse-code modulation) data.
1044 * @details @a callback will be called when you can write a PCM data.
1045 * It might cause dead lock if change the state of audio handle in callback.
1046 * (ex: audio_out_destroy, audio_out_prepare, audio_out_unprepare)
1047 * Recommend to use as a VOIP only.
1048 * Recommend not to hold callback too long.(it affects latency)
1050 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1052 * @remarks @a output must be created using audio_out_create().
1054 * @param[in] output An audio output handle
1055 * @param[in] callback notify stream callback when user can write data (#audio_out_stream_cb)
1056 * @param[in] user_data user data to be retrieved when callback is called
1057 * @return 0 on success, otherwise a negative error value
1058 * @retval #AUDIO_IO_ERROR_NONE Successful
1059 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1060 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
1061 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
1062 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
1064 * @see audio_out_unset_stream_cb()
1066 int audio_out_set_stream_cb(audio_out_h output, audio_out_stream_cb callback, void* user_data);
1069 * @brief Unregisters the callback function.
1071 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1073 * @param[in] output The handle to the audio output
1074 * @return 0 on success, otherwise a negative error value
1075 * @retval #AUDIO_IO_ERROR_NONE Successful
1076 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1077 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1079 * @see audio_out_set_stream_cb()
1081 int audio_out_unset_stream_cb(audio_out_h output);
1084 * @brief Sets the state changed callback function to the audio output handle.
1088 * @remarks @a input must be created using audio_out_create_new().
1090 * @param[in] output The audio output handle
1091 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_out_state_changed_cb)
1092 * @param[in] user_data user data to be retrieved when callback is called
1093 * @return @c 0 on success,
1094 * otherwise a negative error value
1095 * @retval #AUDIO_IO_ERROR_NONE Successful
1096 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1098 * @see audio_out_unset_state_changed_cb()
1100 int audio_out_set_state_changed_cb(audio_out_h output, audio_out_state_changed_cb callback, void* user_data);
1103 * @brief Unregisters the state changed callback function of the audio output handle.
1107 * @param[in] output The handle to the audio output
1108 * @return @c 0 on success,
1109 * otherwise a negative error value
1110 * @retval #AUDIO_IO_ERROR_NONE Successful
1111 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1113 * @see audio_out_set_state_changed_cb()
1115 int audio_out_unset_state_changed_cb(audio_out_h output);
1125 #endif /* __TIZEN_MEDIA_AUDIO_IO_H__ */