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 into the 'audio in' buffer.
477 * @details This function works correctly only with read 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.
482 * This function provides the pointer to the 'audio in' buffer. The pointed memory is owned by the platform, therefore the @a buffer should not be released by the application.
483 * When the data in the @a buffer is not needed anymore, use audio_in_drop() with the @a input for which audio_in_peek() was called.
485 * @param[in] input The handle to the audio input
486 * @param[out] buffer start buffer pointer of peeked 'audio in' data
487 * @param[out] length amount of 'audio in' data to be peeked
488 * @return @c 0 on success,
489 * otherwise a negative error value
490 * @retval #AUDIO_IO_ERROR_NONE Successful
491 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
492 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
493 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
494 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
496 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
497 * @see audio_in_drop()
499 int audio_in_peek(audio_in_h input, const void **buffer, unsigned int *length);
502 * @brief Drops the 'audio in' buffer that was peeked into.
504 * @details This function works correctly only with read callback. Otherwise it won't operate as intended.
506 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
508 * @remarks Works only in asynchronous (event) mode. This will remove 'audio in' data from the actual stream buffer. Use this if peeked data is not needed anymore.
510 * @param[in] input The handle to the audio input
511 * @return 0 on success, otherwise a negative error value
512 * @retval #AUDIO_IO_ERROR_NONE Successful
513 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
514 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
515 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
516 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
518 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
519 * @see audio_in_peek()
521 int audio_in_drop(audio_in_h input);
524 * @brief Sets the state changed callback function to the audio input handle.
528 * @remarks @a input must be created using audio_in_create().
530 * @param[in] input The audio input handle
531 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_in_state_changed_cb)
532 * @param[in] user_data user data to be retrieved when callback is called
533 * @return @c 0 on success,
534 * otherwise a negative error value
535 * @retval #AUDIO_IO_ERROR_NONE Successful
536 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
537 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
539 * @see audio_in_unset_state_changed_cb()
541 int audio_in_set_state_changed_cb(audio_in_h input, audio_in_state_changed_cb callback, void* user_data);
544 * @brief Unregisters the state changed callback function of the audio input handle.
548 * @param[in] input The handle to the audio input
549 * @return @c 0 on success,
550 * otherwise a negative error value
551 * @retval #AUDIO_IO_ERROR_NONE Successful
552 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
553 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
555 * @see audio_in_set_state_changed_cb()
557 int audio_in_unset_state_changed_cb(audio_in_h input);
560 * @brief Gets the volume of the audio input data stream.
564 * @remarks The default @a volume of the audio input stream is 1.0.
566 * @param[in] input The handle to the audio input
567 * @param[out] volume The current volume value of the audio input stream
568 * @return @c 0 on success,
569 * otherwise a negative error value
570 * @retval #AUDIO_IO_ERROR_NONE Successful
571 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
572 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
574 * @see audio_in_set_volume()
576 int audio_in_get_volume(audio_in_h input, double *volume);
579 * @brief Sets the volume of the audio input data stream.
583 * @remarks The default @a volume of the audio input stream is 1.0.
584 * If the @a volume is less than 1.0, the loudness of recorded data will be decreased.
585 * If the @a volume is greater than 1.0, the loudness of recorded data will be increased,
586 * which can be useful when the loudness of original recorded data is too low in certain environments.
587 * Note that the volume can be clipped if the @a volume is greater than 1.0 and the loudness of original recorded data is high enough.
589 * @param[in] input The handle to the audio input
590 * @param[in] volume The volume value to be set (0.0 <= volume <= 2.0)
591 * @return @c 0 on success,
592 * otherwise a negative error value
593 * @retval #AUDIO_IO_ERROR_NONE Successful
594 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
595 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
597 * @see audio_in_get_volume()
599 int audio_in_set_volume(audio_in_h input, double volume);
606 * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
611 * @brief Called when 'audio out' data can be written in asynchronous (event) mode.
613 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
615 * @remarks Use audio_out_write() to write pcm data inside this callback.
616 * @param[in] handle The handle to the audio output
617 * @param[in] nbytes The amount of 'audio in' data which can be written.
618 * @param[in] user_data The user data passed from the callback registration function
620 * @see audio_out_set_stream_cb()
622 typedef void (*audio_out_stream_cb)(audio_out_h handle, size_t nbytes, void *user_data);
625 * @brief Called when the state of audio output is changed.
629 * @param[in] handle The handle of the audio output
630 * @param[in] previous The previous state of the audio output
631 * @param[in] current The current state of the audio output
632 * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
633 * @param[in] user_data The user data passed from the callback registration function
635 * @see audio_out_set_state_changed_cb()
636 * @see audio_out_unset_state_changed_cb()
638 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);
641 * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
643 * @details This function is used for audio output initialization.
647 * @remarks @a output must be released by audio_out_destroy().
648 * It is recommended to call audio_out_set_sound_stream_info() after this API.
649 * Multi-channel playback is not supported.
651 * @param[in] sample_rate The audio sample rate \n
652 * Before 5.0: 8000[Hz] ~ 48000[Hz] \n
653 * Since 5.0: 8000[Hz] ~ 192000[Hz]
654 * @param[in] channel The audio channel type (mono or stereo)
655 * @param[in] type The type of audio sample \n
656 * Before 5.0: 8 or 16-bit \n
657 * Since 5.0: 8, 16 or 24-bit \n
658 * Since 5.5: 8, 16, 24 or 32-bit
659 * @param[out] output An audio output handle is created on success
660 * @return @c 0 on success,
661 * otherwise a negative error value
662 * @retval #AUDIO_IO_ERROR_NONE Successful
663 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
664 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
665 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
666 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
668 * @post The state will be #AUDIO_IO_STATE_IDLE.\n
669 * audio_out_set_sound_stream_info() is recommended to be called after this API.
670 * @see audio_out_destroy()
672 int audio_out_create_new(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_out_h *output);
675 * @brief Releases the audio output handle, along with all its resources.
677 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
679 * @param[in] output The handle to the audio output to destroy
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_OUT_OF_MEMORY Out of memory
685 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
687 * @see audio_out_create_new()
689 int audio_out_destroy(audio_out_h output);
692 * @brief Sets the sound stream information to the audio output.
696 * @remarks The sound stream information includes audio routing and volume type.
697 * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
698 * Voice Recognition and Loopback stream types are not supported in this API.
700 * @param[in] output The handle to the audio output
701 * @param[in] stream_info The handle of stream information
702 * @return @c 0 on success,
703 * otherwise a negative error value
704 * @retval #AUDIO_IO_ERROR_NONE Successful
705 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
706 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
707 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
708 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
710 * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
711 * Call audio_out_create_new() before calling this function.
712 * @post Call audio_out_prepare() after calling this function.
713 * @see sound_manager_create_stream_information()
714 * @see sound_manager_destroy_stream_information()
716 int audio_out_set_sound_stream_info(audio_out_h output, sound_stream_info_h stream_info);
719 * @brief Prepares the audio output for playback, this must be called before audio_out_write().
721 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
723 * @param[in] output The handle to the audio output
724 * @return @c 0 on success,
725 * otherwise a negative error value
726 * @retval #AUDIO_IO_ERROR_NONE Successful
727 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
728 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
730 * @post The state will be #AUDIO_IO_STATE_RUNNING.
731 * @see audio_out_unprepare()
733 int audio_out_prepare(audio_out_h output);
736 * @brief Unprepares the audio output.
738 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
740 * @param[in] output The handle to the audio output
741 * @return @c 0 on success,
742 * otherwise a negative error value
743 * @retval #AUDIO_IO_ERROR_NONE Successful
744 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
745 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
747 * @post The state will be #AUDIO_IO_STATE_IDLE.
748 * @see audio_out_prepare()
750 int audio_out_unprepare(audio_out_h output);
753 * @brief Pauses feeding of audio data to the device.
757 * @param[in] output The handle to the audio output
758 * @return @c 0 on success,
759 * otherwise a negative error value
760 * @retval #AUDIO_IO_ERROR_NONE Successful
761 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
762 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
764 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
765 * @post The state will be #AUDIO_IO_STATE_PAUSED.
766 * @see audio_out_resume()
768 int audio_out_pause(audio_out_h output);
771 * @brief Resumes feeding of audio data to the device.
775 * @param[in] output The handle to the audio output
776 * @return @c 0 on success,
777 * otherwise a negative error value
778 * @retval #AUDIO_IO_ERROR_NONE Successful
779 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
780 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
782 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
783 * @post The state will be #AUDIO_IO_STATE_RUNNING.
784 * @see audio_out_pause()
786 int audio_out_resume(audio_out_h output);
789 * @brief Drains buffered audio data from the output stream.
791 * @details This function waits until drains stream buffer completely. (e.g end of playback)
793 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @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 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
803 * @see audio_out_flush()
805 int audio_out_drain(audio_out_h output);
808 * @brief Flushes and discards buffered audio data from the output stream.
810 * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @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 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
820 * @see audio_out_drain()
822 int audio_out_flush(audio_out_h output);
825 * @brief Starts writing the audio data to the device.
827 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
829 * @param[in] output The handle to the audio output
830 * @param[in,out] buffer The PCM buffer address
831 * @param[in] length The length of the PCM buffer (in bytes)
832 * @return The written data size on success,
833 * otherwise a negative error value
834 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
835 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
836 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
837 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
839 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
841 int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
844 * @brief Gets the size to be allocated for the audio output buffer.
846 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
848 * @param[in] output The handle to the audio output
849 * @param[out] size The suggested buffer size (in bytes, the maximum size is 1 MB)
850 * @return @c 0 on success,
851 * otherwise a negative error value
852 * @retval #AUDIO_IO_ERROR_NONE Successful
853 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
855 * @see audio_out_write()
857 int audio_out_get_buffer_size(audio_out_h output, int *size);
860 * @brief Gets the sample rate of the audio output data stream.
862 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
864 * @param[in] output The handle to the audio output
865 * @param[out] sample_rate The audio sample rate \n
866 * Before 5.0: 8000[Hz] ~ 48000[Hz] \n
867 * Since 5.0: 8000[Hz] ~ 192000[Hz]
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
873 int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
876 * @brief Gets the channel type of the audio output data stream.
878 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
880 * @param[in] output The handle to the audio output
881 * @param[out] channel The audio channel type (mono or stereo)
882 * @return @c 0 on success,
883 * otherwise a negative error value
884 * @retval #AUDIO_IO_ERROR_NONE Successful
885 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
887 int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
890 * @brief Gets the sample audio format of the audio output data stream.
892 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
894 * @param[in] output The handle to the audio output
895 * @param[out] type The type of audio sample \n
896 * Before 5.0: 8 or 16-bit \n
897 * Since 5.0: 8, 16 or 24-bit \n
898 * Since 5.5: 8, 16, 24 or 32-bit
899 * @return @c 0 on success,
900 * otherwise a negative error value
901 * @retval #AUDIO_IO_ERROR_NONE Successful
902 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
904 int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
907 * @brief Gets the sound type supported by the audio output device.
909 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
911 * @param[in] output The handle to the audio output
912 * @param[out] type The sound type
913 * @return @c 0 on success,
914 * otherwise a negative error value
915 * @retval #AUDIO_IO_ERROR_NONE Successful
916 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
918 int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
921 * @brief Sets an asynchronous (event) callback function to handle playing PCM (pulse-code modulation) data.
923 * @details @a callback will be called when you can write a PCM data.
924 * It might cause dead lock if change the state of audio handle in callback.
925 * (ex: audio_out_destroy(), audio_out_prepare(), audio_out_unprepare())
926 * Recommend to use as a VOIP only.
927 * Recommend not to hold callback too long.(it affects latency)
929 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
931 * @remarks @a output must be created using audio_out_create_new().
933 * @param[in] output An audio output handle
934 * @param[in] callback notify stream callback when user can write data (#audio_out_stream_cb)
935 * @param[in] user_data user data to be retrieved when callback is called
936 * @return 0 on success, otherwise a negative error value
937 * @retval #AUDIO_IO_ERROR_NONE Successful
938 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
939 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
940 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
941 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
943 * @see audio_out_unset_stream_cb()
945 int audio_out_set_stream_cb(audio_out_h output, audio_out_stream_cb callback, void* user_data);
948 * @brief Unregisters the callback function.
950 * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
952 * @param[in] output The handle to the audio output
953 * @return 0 on success, otherwise a negative error value
954 * @retval #AUDIO_IO_ERROR_NONE Successful
955 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
956 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
958 * @see audio_out_set_stream_cb()
960 int audio_out_unset_stream_cb(audio_out_h output);
963 * @brief Sets the state changed callback function to the audio output handle.
967 * @remarks @a input must be created using audio_out_create_new().
969 * @param[in] output The audio output handle
970 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_out_state_changed_cb)
971 * @param[in] user_data user data to be retrieved when callback is called
972 * @return @c 0 on success,
973 * otherwise a negative error value
974 * @retval #AUDIO_IO_ERROR_NONE Successful
975 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
977 * @see audio_out_unset_state_changed_cb()
979 int audio_out_set_state_changed_cb(audio_out_h output, audio_out_state_changed_cb callback, void* user_data);
982 * @brief Unregisters the state changed callback function of the audio output handle.
986 * @param[in] output The handle to the audio output
987 * @return @c 0 on success,
988 * otherwise a negative error value
989 * @retval #AUDIO_IO_ERROR_NONE Successful
990 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
992 * @see audio_out_set_state_changed_cb()
994 int audio_out_unset_state_changed_cb(audio_out_h output);
1004 #endif /* __TIZEN_MEDIA_AUDIO_IO_H__ */