2 * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 #ifndef __TIZEN_MEDIA_AUDIO_IO_H__
18 #define __TIZEN_MEDIA_AUDIO_IO_H__
20 #include <sys/types.h>
22 #include <sound_manager.h>
30 * @brief This file contains the Audio Input and Audio Output API.
34 * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
39 * @brief The audio input handle.
40 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
42 typedef struct audio_io_s *audio_in_h;
49 * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
54 * @brief The audio output handle.
55 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
57 typedef struct audio_io_s *audio_out_h;
64 * @addtogroup CAPI_MEDIA_AUDIO_IO_MODULE
69 * @brief Enumeration for audio sample type with bit depth.
70 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
73 AUDIO_SAMPLE_TYPE_U8 = 0x70, /**< Unsigned 8-bit audio samples */
74 AUDIO_SAMPLE_TYPE_S16_LE, /**< Signed 16-bit audio samples */
75 } audio_sample_type_e;
78 * @brief Enumeration for audio channel.
79 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
82 AUDIO_CHANNEL_MONO = 0x80, /**< 1 channel, mono */
83 AUDIO_CHANNEL_STEREO, /**< 2 channel, stereo */
87 * @brief Enumeration for audio input and output state.
91 AUDIO_IO_STATE_IDLE, /**< Audio-io handle is created, but not prepared */
92 AUDIO_IO_STATE_RUNNING, /**< Audio-io handle is ready and the stream is running */
93 AUDIO_IO_STATE_PAUSED, /**< Audio-io handle is ready and the stream is paused */
97 * @brief Enumeration for audio input and output error.
98 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
101 AUDIO_IO_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
102 AUDIO_IO_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
103 AUDIO_IO_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
104 AUDIO_IO_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION, /**< Invalid operation */
105 AUDIO_IO_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Device open error by security */
106 AUDIO_IO_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
107 AUDIO_IO_ERROR_DEVICE_POLICY_RESTRICTION = TIZEN_ERROR_DEVICE_POLICY_RESTRICTION, /**< Device policy restriction (Since 3.0) */
108 AUDIO_IO_ERROR_DEVICE_NOT_OPENED = TIZEN_ERROR_AUDIO_IO | 0x01, /**< Device open error */
109 AUDIO_IO_ERROR_DEVICE_NOT_CLOSED = TIZEN_ERROR_AUDIO_IO | 0x02, /**< Device close error */
110 AUDIO_IO_ERROR_INVALID_BUFFER = TIZEN_ERROR_AUDIO_IO | 0x03, /**< Invalid buffer pointer */
111 AUDIO_IO_ERROR_SOUND_POLICY = TIZEN_ERROR_AUDIO_IO | 0x04, /**< Sound policy error */
112 AUDIO_IO_ERROR_INVALID_STATE = TIZEN_ERROR_AUDIO_IO | 0x05, /**< Invalid state (Since 3.0) */
113 AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE = TIZEN_ERROR_AUDIO_IO | 0x06, /**< Not supported stream type (Since 3.0) */
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_DEVICE_POLICY_RESTRICTION Device policy restriction
304 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
306 * @post The state will be #AUDIO_IO_STATE_RUNNING.
307 * @see audio_in_unprepare()
309 int audio_in_prepare(audio_in_h input);
312 * @brief Unprepares the audio input.
314 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
316 * @param[in] input The handle to the audio input
317 * @return @c 0 on success,
318 * otherwise a negative error value
319 * @retval #AUDIO_IO_ERROR_NONE Successful
320 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
321 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
322 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
324 * @post The state will be #AUDIO_IO_STATE_IDLE.
325 * @see audio_in_prepare()
327 int audio_in_unprepare(audio_in_h input);
330 * @brief Pauses buffering of audio data from the device.
334 * @param[in] input The handle to the audio input
335 * @return @c 0 on success,
336 * otherwise a negative error value
337 * @retval #AUDIO_IO_ERROR_NONE Successful
338 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
339 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
340 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
342 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
343 * @post The state will be #AUDIO_IO_STATE_PAUSED.
344 * @see audio_in_resume()
346 int audio_in_pause(audio_in_h input);
349 * @brief Resumes buffering audio data from the device.
353 * @param[in] input The handle to the audio input
354 * @return @c 0 on success,
355 * otherwise a negative error value
356 * @retval #AUDIO_IO_ERROR_NONE Successful
357 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
358 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
359 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
361 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
362 * @post The state will be #AUDIO_IO_STATE_RUNNING.
363 * @see audio_in_pause()
365 int audio_in_resume(audio_in_h input);
368 * @brief Flushes and discards buffered audio data from the input stream.
370 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
372 * @param[in] input The handle to the audio input
373 * @return @c 0 on success,
374 * otherwise a negative error value
375 * @retval #AUDIO_IO_ERROR_NONE Successful
376 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
377 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
378 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
380 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
382 int audio_in_flush(audio_in_h input);
385 * @brief Reads audio data from the audio input buffer.
387 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
389 * @param[in] input The handle to the audio input
390 * @param[out] buffer The PCM buffer address
391 * @param[in] length The length of the PCM data buffer (in bytes)
392 * @return The number of read bytes on success,
393 * otherwise a negative error value
394 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
395 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
396 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
397 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
398 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
400 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
402 int audio_in_read(audio_in_h input, void *buffer, unsigned int length);
405 * @brief Gets the size to be allocated for the audio input buffer.
407 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
409 * @param[in] input The handle to the audio input
410 * @param[out] size The buffer size (in bytes, the maximum size is 1 MB)
411 * @return @c 0 on success,
412 * otherwise a negative error value
413 * @retval #AUDIO_IO_ERROR_NONE Successful
414 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
415 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
416 * @see audio_in_read()
418 int audio_in_get_buffer_size(audio_in_h input, int *size);
421 * @brief Gets the sample rate of the audio input data stream.
423 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
425 * @param[in] input The handle to the audio input
426 * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
427 * @return @c 0 on success,
428 * otherwise a negative error value
429 * @retval #AUDIO_IO_ERROR_NONE Successful
430 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
431 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
433 int audio_in_get_sample_rate(audio_in_h input, int *sample_rate);
436 * @brief Gets the channel type of the audio input data stream.
438 * @details The audio channel type defines whether the audio is mono or stereo.
440 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
442 * @param[in] input The handle to the audio input
443 * @param[out] channel The audio channel type
444 * @return @c 0 on success,
445 * otherwise a negative error value
446 * @retval #AUDIO_IO_ERROR_NONE Successful
447 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
448 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
450 int audio_in_get_channel(audio_in_h input, audio_channel_e *channel);
453 * @brief Gets the sample audio format (8-bit or 16-bit) of the audio input data stream.
455 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
457 * @param[in] input The handle to the audio input
458 * @param[out] type The audio sample type
459 * @return @c 0 on success,
460 * otherwise a negative error value
461 * @retval #AUDIO_IO_ERROR_NONE Successful
462 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
463 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
465 int audio_in_get_sample_type(audio_in_h input, audio_sample_type_e *type);
468 * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
469 * @brief Registers a callback function to be invoked when the audio input handle is interrupted or the interrupt is completed.
471 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
473 * @param[in] input The handle to the audio input
474 * @param[in] callback The callback function to register
475 * @param[in] user_data The user data to be passed to the callback function
476 * @return @c 0 on success,
477 * otherwise a negative error value
478 * @retval #AUDIO_IO_ERROR_NONE Successful
479 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
480 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
481 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
482 * @post audio_io_interrupted_cb() will be invoked.
484 * @see audio_in_unset_interrupted_cb()
485 * @see audio_io_interrupted_cb()
487 int audio_in_set_interrupted_cb(audio_in_h input, audio_io_interrupted_cb callback, void *user_data);
490 * @deprecated Deprecated since 3.0
491 * @brief Unregisters the callback function.
493 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
495 * @param[in] input The handle to the audio input
496 * @return @c 0 on success,
497 * otherwise a negative error value
498 * @retval #AUDIO_IO_ERROR_NONE Successful
499 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
500 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
501 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
503 * @see audio_in_set_interrupted_cb()
505 int audio_in_unset_interrupted_cb(audio_in_h input);
508 * @deprecated Deprecated since 3.0
509 * @brief Ignores session for input.
511 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
513 * @param[in] input The handle to the audio input
514 * @return @c 0 on success,
515 * otherwise a negative error value
516 * @retval #AUDIO_IO_ERROR_NONE Successful
517 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
518 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
519 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
521 int audio_in_ignore_session(audio_in_h input);
524 * @brief Sets an asynchronous(event) callback function to handle recording PCM (pulse-code modulation) data.
526 * @details @a callback will be called when you can read a PCM data.
527 * It might cause dead lock if change the state of audio handle in callback.
528 * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare)
529 * Recommend to use as a VOIP only.
530 * Recommend not to hold callback too long.(it affects latency)
532 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
534 * @remarks @a input must be created using audio_in_create().
536 * @param[in] input An audio input handle
537 * @param[in] callback notify stream callback when user can read data (#audio_in_stream_cb)
538 * @param[in] user_data user data to be retrieved when callback is called
539 * @return @c 0 on success,
540 * otherwise a negative error value
541 * @retval #AUDIO_IO_ERROR_NONE Successful
542 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
543 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
544 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
545 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
546 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
548 * @see audio_out_set_stream_cb()
550 int audio_in_set_stream_cb(audio_in_h input, audio_in_stream_cb callback, void* user_data);
553 * @brief Unregisters the callback function.
555 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
557 * @param[in] input The handle to the audio input
558 * @return @c 0 on success,
559 * otherwise a negative error value
560 * @retval #AUDIO_IO_ERROR_NONE Successful
561 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
562 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
563 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
565 * @see audio_in_set_interrupted_cb()
567 int audio_in_unset_stream_cb(audio_in_h input);
570 * @brief peek from audio in buffer
572 * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
574 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
576 * @remarks @a Works only in asynchronous(event) mode. This will just retrieve buffer pointer from audio in buffer. Drop after use.
578 * @param[in] input The handle to the audio input
579 * @param[out] buffer start buffer pointer of peeked audio in data
580 * @param[in,out] length amount of audio in data to be peeked
581 * @return @c 0 on success,
582 * otherwise a negative error value
583 * @retval #AUDIO_IO_ERROR_NONE Successful
584 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
585 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
586 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
587 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
589 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
590 * @see audio_in_drop()
592 int audio_in_peek(audio_in_h input, const void **buffer, unsigned int *length);
595 * @brief drop peeked audio buffer.
597 * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
599 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
601 * @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.
603 * @param[in] input The handle to the audio input
604 * @return 0 on success, otherwise a negative error value
605 * @retval #AUDIO_IO_ERROR_NONE Successful
606 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
607 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
608 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
609 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
611 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
612 * @see audio_in_peek()
614 int audio_in_drop(audio_in_h input);
617 * @brief Sets the state changed callback function to the audio input handle.
621 * @remarks @a input must be created using audio_in_create().
623 * @param[in] input The audio input handle
624 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_in_state_changed_cb)
625 * @param[in] user_data user data to be retrieved when callback is called
626 * @return @c 0 on success,
627 * otherwise a negative error value
628 * @retval #AUDIO_IO_ERROR_NONE Successful
629 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
630 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
632 * @see audio_in_unset_state_changed_cb()
634 int audio_in_set_state_changed_cb(audio_in_h input, audio_in_state_changed_cb callback, void* user_data);
637 * @brief Unregisters the state changed callback function of the audio input handle.
641 * @param[in] input The handle to the audio input
642 * @return @c 0 on success,
643 * otherwise a negative error value
644 * @retval #AUDIO_IO_ERROR_NONE Successful
645 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
646 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
648 * @see audio_in_set_state_changed_cb()
650 int audio_in_unset_state_changed_cb(audio_in_h input);
657 * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
662 * @brief Called when audio out data can be written in asynchronous(event) mode.
664 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
666 * @remarks @a use audio_out_write() to write pcm data inside this callback.
667 * @param[in] handle The handle to the audio output
668 * @param[in] nbytes The amount of audio in data which can be written.
669 * @param[in] user_data The user data passed from the callback registration function
671 * @see audio_out_set_stream_cb()
673 typedef void (*audio_out_stream_cb)(audio_out_h handle, size_t nbytes, void *user_data);
676 * @brief Called when the state of audio output is changed.
680 * @param[in] handle The handle of the audio output
681 * @param[in] previous The previous state of the audio output
682 * @param[in] current The current state of the audio output
683 * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
684 * @param[in] user_data The user data passed from the callback registration function
686 * @see audio_out_set_state_changed_cb()
687 * @see audio_out_unset_state_changed_cb()
689 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);
692 * @deprecated Deprecated since 3.0. Use audio_out_create_new() instead.
693 * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
695 * @details This function is used for audio output initialization.
697 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
699 * @remarks @a output must be released by audio_out_destroy().
701 * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
702 * @param[in] channel The audio channel type (mono or stereo)
703 * @param[in] type The type of audio sample (8-bit or 16-bit)
704 * @param[in] sound_type The type of sound (#sound_type_e)
705 * @param[out] output An audio output handle is created on success
706 * @return @c 0 on success,
707 * otherwise a negative error value
708 * @retval #AUDIO_IO_ERROR_NONE Successful
709 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
710 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
711 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
712 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
714 * @see audio_out_destroy()
716 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);
719 * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
721 * @details This function is used for audio output initialization.
725 * @remarks @a output must be released by audio_out_destroy().
726 * It is recommended to call audio_out_set_stream_info() after this API.
728 * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
729 * @param[in] channel The audio channel type (mono or stereo)
730 * @param[in] type The type of audio sample (8-bit or 16-bit)
731 * @param[out] output An audio output handle is created on success
732 * @return @c 0 on success,
733 * otherwise a negative error value
734 * @retval #AUDIO_IO_ERROR_NONE Successful
735 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
736 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
737 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
738 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
740 * @post The state will be #AUDIO_IO_STATE_IDLE.\n
741 * audio_out_set_stream_info() is recommended to be called after this API.
742 * @see audio_out_destroy()
744 int audio_out_create_new(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_out_h *output);
747 * @brief Releases the audio output handle, along with all its resources.
749 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
751 * @param[in] output The handle to the audio output to destroy
752 * @return @c 0 on success,
753 * otherwise a negative error value
754 * @retval #AUDIO_IO_ERROR_NONE Successful
755 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
756 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
757 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
759 * @see audio_out_create()
761 int audio_out_destroy(audio_out_h output);
764 * @brief Sets the sound stream information to the audio output.
768 * @remarks @a the sound stream information includes audio routing and volume type.
769 * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
770 * Voice Recognition and Loopback stream types are not supported in this API.
772 * @param[in] output The handle to the audio output
773 * @param[in] stream_info The handle of stream information
774 * @return @c 0 on success,
775 * otherwise a negative error value
776 * @retval #AUDIO_IO_ERROR_NONE Successful
777 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
778 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
779 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
780 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
782 * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
783 * Call audio_out_create_new() before calling this function.
784 * @post Call audio_out_prepare() after calling this function.
785 * @see sound_manager_create_stream_information()
786 * @see sound_manager_destroy_stream_information()
788 int audio_out_set_stream_info(audio_out_h output, sound_stream_info_h stream_info);
791 * @brief Prepares the audio output for playback, this must be called before audio_out_write().
793 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
795 * @param[in] output The handle to the audio output
796 * @return @c 0 on success,
797 * otherwise a negative error value
798 * @retval #AUDIO_IO_ERROR_NONE Successful
799 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
800 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
802 * @post The state will be #AUDIO_IO_STATE_RUNNING.
803 * @see audio_out_unprepare()
805 int audio_out_prepare(audio_out_h output);
808 * @brief Unprepares the audio output.
810 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
812 * @param[in] output The handle to the audio output
813 * @return @c 0 on success,
814 * otherwise a negative error value
815 * @retval #AUDIO_IO_ERROR_NONE Successful
816 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
817 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
819 * @post The state will be #AUDIO_IO_STATE_IDLE.
820 * @see audio_out_prepare()
822 int audio_out_unprepare(audio_out_h output);
825 * @brief Pauses feeding of audio data to the device.
829 * @param[in] output The handle to the audio output
830 * @return @c 0 on success,
831 * otherwise a negative error value
832 * @retval #AUDIO_IO_ERROR_NONE Successful
833 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
834 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
836 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
837 * @post The state will be #AUDIO_IO_STATE_PAUSED.
838 * @see audio_out_resume()
840 int audio_out_pause(audio_out_h output);
843 * @brief Resumes feeding of audio data to the device.
847 * @param[in] output The handle to the audio output
848 * @return @c 0 on success,
849 * otherwise a negative error value
850 * @retval #AUDIO_IO_ERROR_NONE Successful
851 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
852 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
854 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
855 * @post The state will be #AUDIO_IO_STATE_RUNNING.
856 * @see audio_out_pause()
858 int audio_out_resume(audio_out_h output);
861 * @brief Drains buffered audio data from the output stream.
863 * @details This function waits until drains stream buffer completely. (e.g end of playback)
865 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
867 * @param[in] output The handle to the audio output
868 * @return @c 0 on success,
869 * otherwise a negative error value
870 * @retval #AUDIO_IO_ERROR_NONE Successful
871 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
872 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
874 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
875 * @see audio_out_flush()
877 int audio_out_drain(audio_out_h output);
880 * @brief Flushes and discards buffered audio data from the output stream.
882 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
884 * @param[in] output The handle to the audio output
885 * @return @c 0 on success,
886 * otherwise a negative error value
887 * @retval #AUDIO_IO_ERROR_NONE Successful
888 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
889 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
891 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
892 * @see audio_out_drain()
894 int audio_out_flush(audio_out_h output);
897 * @brief Starts writing the audio data to the device.
899 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
901 * @param[in] output The handle to the audio output
902 * @param[in,out] buffer The PCM buffer address
903 * @param[in] length The length of the PCM buffer (in bytes)
904 * @return The written data size on success,
905 * otherwise a negative error value
906 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
907 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
908 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
909 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
911 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
913 int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
916 * @brief Gets the size to be allocated for the audio output buffer.
918 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
920 * @param[in] output The handle to the audio output
921 * @param[out] size The suggested buffer size (in bytes, the maximum size is 1 MB)
922 * @return @c 0 on success,
923 * otherwise a negative error value
924 * @retval #AUDIO_IO_ERROR_NONE Successful
925 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
927 * @see audio_out_write()
929 int audio_out_get_buffer_size(audio_out_h output, int *size);
932 * @brief Gets the sample rate of the audio output data stream.
934 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
936 * @param[in] output The handle to the audio output
937 * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
938 * @return @c 0 on success,
939 * otherwise a negative error value
940 * @retval #AUDIO_IO_ERROR_NONE Successful
941 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
943 int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
946 * @brief Gets the channel type of the audio output data stream.
948 * @details The audio channel type defines whether the audio is mono or stereo.
950 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
952 * @param[in] output The handle to the audio output
953 * @param[out] channel The audio channel type
954 * @return @c 0 on success,
955 * otherwise a negative error value
956 * @retval #AUDIO_IO_ERROR_NONE Successful
957 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
959 int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
962 * @brief Gets the sample audio format (8-bit or 16-bit) of the audio output data stream.
964 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
966 * @param[in] output The handle to the audio output
967 * @param[out] type The audio sample type
968 * @return @c 0 on success,
969 * otherwise a negative error value
970 * @retval #AUDIO_IO_ERROR_NONE Successful
971 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
973 int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
976 * @brief Gets the sound type supported by the audio output device.
978 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
980 * @param[in] output The handle to the audio output
981 * @param[out] type The sound type
982 * @return @c 0 on success,
983 * otherwise a negative error value
984 * @retval #AUDIO_IO_ERROR_NONE Successful
985 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
987 int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
990 * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead.
991 * @brief Registers a callback function to be invoked when the audio output handle is interrupted or the interrupt is completed.
993 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
995 * @param[in] output The handle to the audio output
996 * @param[in] callback The callback function to register
997 * @param[in] user_data The user data to be passed to the callback function
998 * @return @c 0 on success,
999 * otherwise a negative error value
1000 * @retval #AUDIO_IO_ERROR_NONE Successful
1001 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1002 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1004 * @post audio_io_interrupted_cb() will be invoked.
1005 * @see audio_out_unset_interrupted_cb()
1006 * @see audio_io_interrupted_cb()
1008 int audio_out_set_interrupted_cb(audio_out_h output, audio_io_interrupted_cb callback, void *user_data);
1011 * @deprecated Deprecated since 3.0
1012 * @brief Unregisters the callback function.
1014 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1016 * @param[in] output The handle to the audio output
1017 * @return @c 0 on success,
1018 * otherwise a negative error value
1019 * @retval #AUDIO_IO_ERROR_NONE Successful
1020 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1021 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1023 * @see audio_out_set_interrupted_cb()
1025 int audio_out_unset_interrupted_cb(audio_out_h output);
1028 * @deprecated Deprecated since 3.0
1029 * @brief Ignores session for output.
1031 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1033 * @param[in] output The handle to the audio output
1034 * @return @c 0 on success,
1035 * otherwise a negative error value
1036 * @retval #AUDIO_IO_ERROR_NONE Successful
1037 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1038 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1040 int audio_out_ignore_session(audio_out_h output);
1043 * @brief Sets an asynchronous(event) callback function to handle playing PCM (pulse-code modulation) data.
1045 * @details @a callback will be called when you can write a PCM data.
1046 * It might cause dead lock if change the state of audio handle in callback.
1047 * (ex: audio_out_destroy, audio_out_prepare, audio_out_unprepare)
1048 * Recommend to use as a VOIP only.
1049 * Recommend not to hold callback too long.(it affects latency)
1051 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1053 * @remarks @a output must be created using audio_out_create().
1055 * @param[in] output An audio output handle
1056 * @param[in] callback notify stream callback when user can write data (#audio_out_stream_cb)
1057 * @param[in] user_data user data to be retrieved when callback is called
1058 * @return 0 on success, otherwise a negative error value
1059 * @retval #AUDIO_IO_ERROR_NONE Successful
1060 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1061 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
1062 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
1063 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
1065 * @see audio_out_unset_stream_cb()
1067 int audio_out_set_stream_cb(audio_out_h output, audio_out_stream_cb callback, void* user_data);
1070 * @brief Unregisters the callback function.
1072 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
1074 * @param[in] output The handle to the audio output
1075 * @return 0 on success, otherwise a negative error value
1076 * @retval #AUDIO_IO_ERROR_NONE Successful
1077 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1078 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
1080 * @see audio_out_set_stream_cb()
1082 int audio_out_unset_stream_cb(audio_out_h output);
1085 * @brief Sets the state changed callback function to the audio output handle.
1089 * @remarks @a input must be created using audio_out_create_new().
1091 * @param[in] output The audio output handle
1092 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_out_state_changed_cb)
1093 * @param[in] user_data user data to be retrieved when callback is called
1094 * @return @c 0 on success,
1095 * otherwise a negative error value
1096 * @retval #AUDIO_IO_ERROR_NONE Successful
1097 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1099 * @see audio_out_unset_state_changed_cb()
1101 int audio_out_set_state_changed_cb(audio_out_h output, audio_out_state_changed_cb callback, void* user_data);
1104 * @brief Unregisters the state changed callback function of the audio output handle.
1108 * @param[in] output The handle to the audio output
1109 * @return @c 0 on success,
1110 * otherwise a negative error value
1111 * @retval #AUDIO_IO_ERROR_NONE Successful
1112 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1114 * @see audio_out_set_state_changed_cb()
1116 int audio_out_unset_state_changed_cb(audio_out_h output);
1126 #endif /* __TIZEN_MEDIA_AUDIO_IO_H__ */