2 * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 #ifndef __TIZEN_MEDIA_AUDIO_IO_H__
18 #define __TIZEN_MEDIA_AUDIO_IO_H__
20 #include <sys/types.h>
22 #include <sound_manager.h>
30 * @brief This file contains the Audio Input and Audio Output API.
34 * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
39 * @brief The audio input handle.
40 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
42 typedef struct audio_io_s *audio_in_h;
49 * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
54 * @brief The audio output handle.
55 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
57 typedef struct audio_io_s *audio_out_h;
64 * @addtogroup CAPI_MEDIA_AUDIO_IO_MODULE
69 * @brief Enumeration for audio sample type with bit depth.
70 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
73 AUDIO_SAMPLE_TYPE_U8 = 0x70, /**< Unsigned 8-bit audio samples */
74 AUDIO_SAMPLE_TYPE_S16_LE, /**< Signed 16-bit audio samples */
75 AUDIO_SAMPLE_TYPE_S24_LE, /**< Signed 24-bit audio samples (Since 5.0) */
76 AUDIO_SAMPLE_TYPE_S24_32_LE, /**< Signed 24-bit (packed in 32-bit) audio samples (Since 5.0) */
77 AUDIO_SAMPLE_TYPE_S32_LE, /**< Signed 32-bit audio samples (Since 5.5) */
78 } audio_sample_type_e;
81 * @brief Enumeration for audio channel.
82 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
85 AUDIO_CHANNEL_MONO = 0x80, /**< 1 channel, mono */
86 AUDIO_CHANNEL_STEREO, /**< 2 channels, stereo */
87 AUDIO_CHANNEL_MULTI_3, /**< 3 channels (Since 5.5) */
88 AUDIO_CHANNEL_MULTI_4, /**< 4 channels (Since 5.5) */
89 AUDIO_CHANNEL_MULTI_5, /**< 5 channels (Since 5.5) */
90 AUDIO_CHANNEL_MULTI_6, /**< 6 channels (Since 5.5) */
91 AUDIO_CHANNEL_MULTI_7, /**< 7 channels (Since 5.5) */
92 AUDIO_CHANNEL_MULTI_8, /**< 8 channels (Since 5.5) */
96 * @brief Enumeration for audio input and output state.
100 AUDIO_IO_STATE_IDLE, /**< Audio-io handle is created, but not prepared */
101 AUDIO_IO_STATE_RUNNING, /**< Audio-io handle is ready and the stream is running */
102 AUDIO_IO_STATE_PAUSED, /**< Audio-io handle is ready and the stream is paused */
106 * @brief Enumeration for audio input and output error.
107 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
110 AUDIO_IO_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
111 AUDIO_IO_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
112 AUDIO_IO_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
113 AUDIO_IO_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION, /**< Invalid operation */
114 AUDIO_IO_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Device open error by security */
115 AUDIO_IO_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
116 AUDIO_IO_ERROR_DEVICE_POLICY_RESTRICTION = TIZEN_ERROR_DEVICE_POLICY_RESTRICTION, /**< Device policy restriction (Since 3.0) */
117 AUDIO_IO_ERROR_DEVICE_NOT_OPENED = TIZEN_ERROR_AUDIO_IO | 0x01, /**< Device open error */
118 AUDIO_IO_ERROR_DEVICE_NOT_CLOSED = TIZEN_ERROR_AUDIO_IO | 0x02, /**< Device close error */
119 AUDIO_IO_ERROR_INVALID_BUFFER = TIZEN_ERROR_AUDIO_IO | 0x03, /**< Invalid buffer pointer */
120 AUDIO_IO_ERROR_SOUND_POLICY = TIZEN_ERROR_AUDIO_IO | 0x04, /**< Sound policy error */
121 AUDIO_IO_ERROR_INVALID_STATE = TIZEN_ERROR_AUDIO_IO | 0x05, /**< Invalid state (Since 3.0) */
122 AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE = TIZEN_ERROR_AUDIO_IO | 0x06, /**< Not supported stream type (Since 3.0) */
130 * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
135 * @brief Called when audio input data is available in asynchronous(event) mode.
137 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
139 * @remarks Use audio_in_peek() to get audio in data inside callback, use audio_in_drop() after use of peeked data.
141 * @param[in] handle The handle to the audio input
142 * @param[in] nbytes The amount of available audio in data which can be peeked.
143 * @param[in] user_data The user data passed from the callback registration function
145 * @see audio_in_set_stream_cb()
147 typedef void (*audio_in_stream_cb)(audio_in_h handle, size_t nbytes, void *user_data);
150 * @brief Called when the state of audio input is changed.
154 * @param[in] handle The handle of the audio input
155 * @param[in] previous The previous state of the audio input
156 * @param[in] current The current state of the audio input
157 * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
158 * @param[in] user_data The user data passed from the callback registration function
160 * @see audio_in_set_state_changed_cb()
161 * @see audio_in_unset_state_changed_cb()
163 typedef void (*audio_in_state_changed_cb)(audio_in_h handle, audio_io_state_e previous, audio_io_state_e current, bool by_policy, void *user_data);
166 * @brief Creates an audio device instance and returns an input handle to record PCM (pulse-code modulation) data.
168 * @details This function is used for audio input initialization.
170 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
172 * @privilege %http://tizen.org/privilege/recorder
174 * @remarks @a input must be released using audio_in_destroy().
175 * If the channel count of the requested @a channel is different from the system's supported channel count, then channel remapping will be processed internally.
177 * @param[in] sample_rate The audio sample rate \n
178 * Before 5.0: 8000[Hz] ~ 48000[Hz] \n
179 * Since 5.0: 8000[Hz] ~ 192000[Hz]
180 * @param[in] channel The audio channel type \n
181 * Before 5.5: Mono or stereo \n
182 * Since 5.5: Mono, stereo or multi-channels
183 * @param[in] type The type of audio sample \n
184 * Before 5.0: 8 or 16-bit \n
185 * Since 5.0: 8, 16 or 24-bit \n
186 * Since 5.5: 8, 16, 24 or 32-bit
187 * @param[out] input An audio input handle is created on success
188 * @return @c 0 on success,
189 * otherwise a negative error value
190 * @retval #AUDIO_IO_ERROR_NONE Successful
191 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
192 * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
193 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
194 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
195 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
196 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
198 * @post The state will be #AUDIO_IO_STATE_IDLE.\n
199 * audio_in_set_sound_stream_info() is recommended to be called after this API.
200 * @see audio_in_destroy()
202 int audio_in_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_in_h *input);
205 * @brief Releases the audio input handle and all its resources associated with an audio stream.
207 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
209 * @param[in] input The handle to the audio input to destroy
210 * @return @c 0 on success,
211 * otherwise a negative error value
212 * @retval #AUDIO_IO_ERROR_NONE Successful
213 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
214 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
215 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
217 * @see audio_in_create()
219 int audio_in_destroy(audio_in_h input);
222 * @brief Sets the sound stream information to the audio input.
226 * @remarks The sound stream information includes audio routing and volume type.
227 * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
228 * System, Alarm, Notification, Emergency, Voice Information, Ringtone VOIP and Ringtone Call stream types are not supported in this API.
230 * @param[in] input The handle to the audio input
231 * @param[in] stream_info The handle of stream information
232 * @return @c 0 on success,
233 * otherwise a negative error value
234 * @retval #AUDIO_IO_ERROR_NONE Successful
235 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
236 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
237 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
238 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
240 * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
241 * Call audio_in_create() before calling this function.
242 * @post Call audio_in_prepare() after calling this function.
243 * @see sound_manager_create_stream_information()
244 * @see sound_manager_destroy_stream_information()
246 int audio_in_set_sound_stream_info(audio_in_h input, sound_stream_info_h stream_info);
249 * @brief Prepares the audio input for reading audio data by starting buffering of audio data from the device.
251 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
253 * @param[in] input The handle to the audio input
254 * @return @c 0 on success,
255 * otherwise a negative error value
256 * @retval #AUDIO_IO_ERROR_NONE Successful
257 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
258 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
259 * @retval #AUDIO_IO_ERROR_DEVICE_POLICY_RESTRICTION Device policy restriction
260 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
262 * @post The state will be #AUDIO_IO_STATE_RUNNING.
263 * @see audio_in_unprepare()
265 int audio_in_prepare(audio_in_h input);
268 * @brief Unprepares the audio input.
270 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
272 * @param[in] input The handle to the audio input
273 * @return @c 0 on success,
274 * otherwise a negative error value
275 * @retval #AUDIO_IO_ERROR_NONE Successful
276 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
277 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
278 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
280 * @post The state will be #AUDIO_IO_STATE_IDLE.
281 * @see audio_in_prepare()
283 int audio_in_unprepare(audio_in_h input);
286 * @brief Pauses buffering of audio data from the device.
290 * @param[in] input The handle to the audio input
291 * @return @c 0 on success,
292 * otherwise a negative error value
293 * @retval #AUDIO_IO_ERROR_NONE Successful
294 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
295 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
296 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
298 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
299 * @post The state will be #AUDIO_IO_STATE_PAUSED.
300 * @see audio_in_resume()
302 int audio_in_pause(audio_in_h input);
305 * @brief Resumes buffering audio data from the device.
309 * @param[in] input The handle to the audio input
310 * @return @c 0 on success,
311 * otherwise a negative error value
312 * @retval #AUDIO_IO_ERROR_NONE Successful
313 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
314 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
315 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
317 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
318 * @post The state will be #AUDIO_IO_STATE_RUNNING.
319 * @see audio_in_pause()
321 int audio_in_resume(audio_in_h input);
324 * @brief Flushes and discards buffered audio data from the input stream.
326 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
328 * @param[in] input The handle to the audio input
329 * @return @c 0 on success,
330 * otherwise a negative error value
331 * @retval #AUDIO_IO_ERROR_NONE Successful
332 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
333 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
334 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
336 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
338 int audio_in_flush(audio_in_h input);
341 * @brief Reads audio data from the audio input buffer.
343 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
345 * @param[in] input The handle to the audio input
346 * @param[out] buffer The PCM buffer address
347 * @param[in] length The length of the PCM data buffer (in bytes)
348 * @return The number of read bytes on success,
349 * otherwise a negative error value
350 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
351 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
352 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
353 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
354 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
356 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
358 int audio_in_read(audio_in_h input, void *buffer, unsigned int length);
361 * @brief Gets the size to be allocated for the audio input buffer.
363 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
365 * @param[in] input The handle to the audio input
366 * @param[out] size The buffer size (in bytes, the maximum size is 1 MB)
367 * @return @c 0 on success,
368 * otherwise a negative error value
369 * @retval #AUDIO_IO_ERROR_NONE Successful
370 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
371 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
372 * @see audio_in_read()
374 int audio_in_get_buffer_size(audio_in_h input, int *size);
377 * @brief Gets the sample rate of the audio input data stream.
379 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
381 * @param[in] input The handle to the audio input
382 * @param[out] sample_rate The audio sample rate \n
383 * Before 5.0: 8000[Hz] ~ 48000[Hz] \n
384 * Since 5.0: 8000[Hz] ~ 192000[Hz]
385 * @return @c 0 on success,
386 * otherwise a negative error value
387 * @retval #AUDIO_IO_ERROR_NONE Successful
388 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
389 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
391 int audio_in_get_sample_rate(audio_in_h input, int *sample_rate);
394 * @brief Gets the channel type of the audio input data stream.
396 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
398 * @param[in] input The handle to the audio input
399 * @param[out] channel The audio channel type \n
400 * Before 5.5: Mono or stereo \n
401 * Since 5.5: Mono, stereo or multi-channels
402 * @return @c 0 on success,
403 * otherwise a negative error value
404 * @retval #AUDIO_IO_ERROR_NONE Successful
405 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
406 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
408 int audio_in_get_channel(audio_in_h input, audio_channel_e *channel);
411 * @brief Gets the sample audio format of the audio input data stream.
413 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
415 * @param[in] input The handle to the audio input
416 * @param[out] type The type of audio sample \n
417 * Before 5.0: 8 or 16-bit \n
418 * Since 5.0: 8, 16 or 24-bit \n
419 * Since 5.5: 8, 16, 24 or 32-bit
420 * @return @c 0 on success,
421 * otherwise a negative error value
422 * @retval #AUDIO_IO_ERROR_NONE Successful
423 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
424 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
426 int audio_in_get_sample_type(audio_in_h input, audio_sample_type_e *type);
429 * @brief Sets an asynchronous(event) callback function to handle recording PCM (pulse-code modulation) data.
431 * @details @a callback will be called when you can read a PCM data.
432 * It might cause dead lock if change the state of audio handle in callback.
433 * (ex: audio_in_destroy(), audio_in_prepare(), audio_in_unprepare())
434 * Recommend to use as a VOIP only.
435 * Recommend not to hold callback too long.(it affects latency)
437 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
439 * @remarks @a input must be created using audio_in_create().
441 * @param[in] input An audio input handle
442 * @param[in] callback notify stream callback when user can read data (#audio_in_stream_cb)
443 * @param[in] user_data user data to be retrieved when callback is called
444 * @return @c 0 on success,
445 * otherwise a negative error value
446 * @retval #AUDIO_IO_ERROR_NONE Successful
447 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
448 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
449 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
450 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
451 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
453 * @see audio_in_unset_stream_cb()
455 int audio_in_set_stream_cb(audio_in_h input, audio_in_stream_cb callback, void* user_data);
458 * @brief Unregisters the callback function.
460 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
462 * @param[in] input The handle to the audio input
463 * @return @c 0 on success,
464 * otherwise a negative error value
465 * @retval #AUDIO_IO_ERROR_NONE Successful
466 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
467 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
468 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
470 * @see audio_in_set_stream_cb()
472 int audio_in_unset_stream_cb(audio_in_h input);
475 * @brief peeks from audio in buffer.
477 * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
479 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
481 * @remarks Works only in asynchronous(event) mode. This will just retrieve buffer pointer from audio in buffer. Drop after use.
483 * @param[in] input The handle to the audio input
484 * @param[out] buffer start buffer pointer of peeked audio in data
485 * @param[out] length amount of audio in data to be peeked
486 * @return @c 0 on success,
487 * otherwise a negative error value
488 * @retval #AUDIO_IO_ERROR_NONE Successful
489 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
490 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
491 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
492 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
494 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
495 * @see audio_in_drop()
497 int audio_in_peek(audio_in_h input, const void **buffer, unsigned int *length);
500 * @brief Drops peeked audio buffer.
502 * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
504 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
506 * @remarks 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.
508 * @param[in] input The handle to the audio input
509 * @return 0 on success, otherwise a negative error value
510 * @retval #AUDIO_IO_ERROR_NONE Successful
511 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
512 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
513 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
514 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
516 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
517 * @see audio_in_peek()
519 int audio_in_drop(audio_in_h input);
522 * @brief Sets the state changed callback function to the audio input handle.
526 * @remarks @a input must be created using audio_in_create().
528 * @param[in] input The audio input handle
529 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_in_state_changed_cb)
530 * @param[in] user_data user data to be retrieved when callback is called
531 * @return @c 0 on success,
532 * otherwise a negative error value
533 * @retval #AUDIO_IO_ERROR_NONE Successful
534 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
535 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
537 * @see audio_in_unset_state_changed_cb()
539 int audio_in_set_state_changed_cb(audio_in_h input, audio_in_state_changed_cb callback, void* user_data);
542 * @brief Unregisters the state changed callback function of the audio input handle.
546 * @param[in] input The handle to the audio input
547 * @return @c 0 on success,
548 * otherwise a negative error value
549 * @retval #AUDIO_IO_ERROR_NONE Successful
550 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
551 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
553 * @see audio_in_set_state_changed_cb()
555 int audio_in_unset_state_changed_cb(audio_in_h input);
562 * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
567 * @brief Called when audio out data can be written in asynchronous(event) mode.
569 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
571 * @remarks Use audio_out_write() to write pcm data inside this callback.
572 * @param[in] handle The handle to the audio output
573 * @param[in] nbytes The amount of audio in data which can be written.
574 * @param[in] user_data The user data passed from the callback registration function
576 * @see audio_out_set_stream_cb()
578 typedef void (*audio_out_stream_cb)(audio_out_h handle, size_t nbytes, void *user_data);
581 * @brief Called when the state of audio output is changed.
585 * @param[in] handle The handle of the audio output
586 * @param[in] previous The previous state of the audio output
587 * @param[in] current The current state of the audio output
588 * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
589 * @param[in] user_data The user data passed from the callback registration function
591 * @see audio_out_set_state_changed_cb()
592 * @see audio_out_unset_state_changed_cb()
594 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);
597 * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
599 * @details This function is used for audio output initialization.
603 * @remarks @a output must be released by audio_out_destroy().
604 * It is recommended to call audio_out_set_sound_stream_info() after this API.
605 * Multi-channel playback is not supported.
607 * @param[in] sample_rate The audio sample rate \n
608 * Before 5.0: 8000[Hz] ~ 48000[Hz] \n
609 * Since 5.0: 8000[Hz] ~ 192000[Hz]
610 * @param[in] channel The audio channel type (mono or stereo)
611 * @param[in] type The type of audio sample \n
612 * Before 5.0: 8 or 16-bit \n
613 * Since 5.0: 8, 16 or 24-bit \n
614 * Since 5.5: 8, 16, 24 or 32-bit
615 * @param[out] output An audio output handle is created on success
616 * @return @c 0 on success,
617 * otherwise a negative error value
618 * @retval #AUDIO_IO_ERROR_NONE Successful
619 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
620 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
621 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
622 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
624 * @post The state will be #AUDIO_IO_STATE_IDLE.\n
625 * audio_out_set_sound_stream_info() is recommended to be called after this API.
626 * @see audio_out_destroy()
628 int audio_out_create_new(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_out_h *output);
631 * @brief Releases the audio output handle, along with all its resources.
633 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
635 * @param[in] output The handle to the audio output to destroy
636 * @return @c 0 on success,
637 * otherwise a negative error value
638 * @retval #AUDIO_IO_ERROR_NONE Successful
639 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
640 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
641 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
643 * @see audio_out_create_new()
645 int audio_out_destroy(audio_out_h output);
648 * @brief Sets the sound stream information to the audio output.
652 * @remarks The sound stream information includes audio routing and volume type.
653 * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
654 * Voice Recognition and Loopback stream types are not supported in this API.
656 * @param[in] output The handle to the audio output
657 * @param[in] stream_info The handle of stream information
658 * @return @c 0 on success,
659 * otherwise a negative error value
660 * @retval #AUDIO_IO_ERROR_NONE Successful
661 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
662 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
663 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
664 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
666 * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
667 * Call audio_out_create_new() before calling this function.
668 * @post Call audio_out_prepare() after calling this function.
669 * @see sound_manager_create_stream_information()
670 * @see sound_manager_destroy_stream_information()
672 int audio_out_set_sound_stream_info(audio_out_h output, sound_stream_info_h stream_info);
675 * @brief Prepares the audio output for playback, this must be called before audio_out_write().
677 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
679 * @param[in] output The handle to the audio output
680 * @return @c 0 on success,
681 * otherwise a negative error value
682 * @retval #AUDIO_IO_ERROR_NONE Successful
683 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
684 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
686 * @post The state will be #AUDIO_IO_STATE_RUNNING.
687 * @see audio_out_unprepare()
689 int audio_out_prepare(audio_out_h output);
692 * @brief Unprepares the audio output.
694 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
696 * @param[in] output The handle to the audio output
697 * @return @c 0 on success,
698 * otherwise a negative error value
699 * @retval #AUDIO_IO_ERROR_NONE Successful
700 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
701 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
703 * @post The state will be #AUDIO_IO_STATE_IDLE.
704 * @see audio_out_prepare()
706 int audio_out_unprepare(audio_out_h output);
709 * @brief Pauses feeding of audio data to the device.
713 * @param[in] output The handle to the audio output
714 * @return @c 0 on success,
715 * otherwise a negative error value
716 * @retval #AUDIO_IO_ERROR_NONE Successful
717 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
718 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
720 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
721 * @post The state will be #AUDIO_IO_STATE_PAUSED.
722 * @see audio_out_resume()
724 int audio_out_pause(audio_out_h output);
727 * @brief Resumes feeding of audio data to the device.
731 * @param[in] output The handle to the audio output
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_INVALID_STATE Invalid state
738 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
739 * @post The state will be #AUDIO_IO_STATE_RUNNING.
740 * @see audio_out_pause()
742 int audio_out_resume(audio_out_h output);
745 * @brief Drains buffered audio data from the output stream.
747 * @details This function waits until drains stream buffer completely. (e.g end of playback)
749 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
751 * @param[in] output The handle to the audio output
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_INVALID_STATE Invalid state
758 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
759 * @see audio_out_flush()
761 int audio_out_drain(audio_out_h output);
764 * @brief Flushes and discards buffered audio data from the output stream.
766 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
768 * @param[in] output The handle to the audio output
769 * @return @c 0 on success,
770 * otherwise a negative error value
771 * @retval #AUDIO_IO_ERROR_NONE Successful
772 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
773 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
775 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
776 * @see audio_out_drain()
778 int audio_out_flush(audio_out_h output);
781 * @brief Starts writing the audio data to the device.
783 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
785 * @param[in] output The handle to the audio output
786 * @param[in,out] buffer The PCM buffer address
787 * @param[in] length The length of the PCM buffer (in bytes)
788 * @return The written data size on success,
789 * otherwise a negative error value
790 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
791 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
792 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
793 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
795 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
797 int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
800 * @brief Gets the size to be allocated for the audio output buffer.
802 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
804 * @param[in] output The handle to the audio output
805 * @param[out] size The suggested buffer size (in bytes, the maximum size is 1 MB)
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
811 * @see audio_out_write()
813 int audio_out_get_buffer_size(audio_out_h output, int *size);
816 * @brief Gets the sample rate of the audio output data stream.
818 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
820 * @param[in] output The handle to the audio output
821 * @param[out] sample_rate The audio sample rate \n
822 * Before 5.0: 8000[Hz] ~ 48000[Hz] \n
823 * Since 5.0: 8000[Hz] ~ 192000[Hz]
824 * @return @c 0 on success,
825 * otherwise a negative error value
826 * @retval #AUDIO_IO_ERROR_NONE Successful
827 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
829 int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
832 * @brief Gets the channel type of the audio output data stream.
834 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
836 * @param[in] output The handle to the audio output
837 * @param[out] channel The audio channel type (mono or stereo)
838 * @return @c 0 on success,
839 * otherwise a negative error value
840 * @retval #AUDIO_IO_ERROR_NONE Successful
841 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
843 int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
846 * @brief Gets the sample audio format of the audio output data stream.
848 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
850 * @param[in] output The handle to the audio output
851 * @param[out] type The type of audio sample \n
852 * Before 5.0: 8 or 16-bit \n
853 * Since 5.0: 8, 16 or 24-bit \n
854 * Since 5.5: 8, 16, 24 or 32-bit
855 * @return @c 0 on success,
856 * otherwise a negative error value
857 * @retval #AUDIO_IO_ERROR_NONE Successful
858 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
860 int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
863 * @brief Gets the sound type supported by the audio output device.
865 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
867 * @param[in] output The handle to the audio output
868 * @param[out] type The sound type
869 * @return @c 0 on success,
870 * otherwise a negative error value
871 * @retval #AUDIO_IO_ERROR_NONE Successful
872 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
874 int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
877 * @brief Sets an asynchronous(event) callback function to handle playing PCM (pulse-code modulation) data.
879 * @details @a callback will be called when you can write a PCM data.
880 * It might cause dead lock if change the state of audio handle in callback.
881 * (ex: audio_out_destroy(), audio_out_prepare(), audio_out_unprepare())
882 * Recommend to use as a VOIP only.
883 * Recommend not to hold callback too long.(it affects latency)
885 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
887 * @remarks @a output must be created using audio_out_create_new().
889 * @param[in] output An audio output handle
890 * @param[in] callback notify stream callback when user can write data (#audio_out_stream_cb)
891 * @param[in] user_data user data to be retrieved when callback is called
892 * @return 0 on success, otherwise a negative error value
893 * @retval #AUDIO_IO_ERROR_NONE Successful
894 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
895 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
896 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
897 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
899 * @see audio_out_unset_stream_cb()
901 int audio_out_set_stream_cb(audio_out_h output, audio_out_stream_cb callback, void* user_data);
904 * @brief Unregisters the callback function.
906 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
908 * @param[in] output The handle to the audio output
909 * @return 0 on success, otherwise a negative error value
910 * @retval #AUDIO_IO_ERROR_NONE Successful
911 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
912 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
914 * @see audio_out_set_stream_cb()
916 int audio_out_unset_stream_cb(audio_out_h output);
919 * @brief Sets the state changed callback function to the audio output handle.
923 * @remarks @a input must be created using audio_out_create_new().
925 * @param[in] output The audio output handle
926 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_out_state_changed_cb)
927 * @param[in] user_data user data to be retrieved when callback is called
928 * @return @c 0 on success,
929 * otherwise a negative error value
930 * @retval #AUDIO_IO_ERROR_NONE Successful
931 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
933 * @see audio_out_unset_state_changed_cb()
935 int audio_out_set_state_changed_cb(audio_out_h output, audio_out_state_changed_cb callback, void* user_data);
938 * @brief Unregisters the state changed callback function of the audio output handle.
942 * @param[in] output The handle to the audio output
943 * @return @c 0 on success,
944 * otherwise a negative error value
945 * @retval #AUDIO_IO_ERROR_NONE Successful
946 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
948 * @see audio_out_set_state_changed_cb()
950 int audio_out_unset_state_changed_cb(audio_out_h output);
960 #endif /* __TIZEN_MEDIA_AUDIO_IO_H__ */