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.
42 typedef struct audio_io_s *audio_in_h;
49 * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
54 * @brief The audio output handle.
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.
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.
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) */
93 AUDIO_CHANNEL_MULTI_9, /**< 9 channels (Since 6.5) */
94 AUDIO_CHANNEL_MULTI_10, /**< 10 channels (Since 6.5) */
95 AUDIO_CHANNEL_MULTI_11, /**< 11 channels (Since 6.5) */
96 AUDIO_CHANNEL_MULTI_12, /**< 12 channels (Since 6.5) */
97 AUDIO_CHANNEL_MULTI_13, /**< 13 channels (Since 6.5) */
98 AUDIO_CHANNEL_MULTI_14, /**< 14 channels (Since 6.5) */
99 AUDIO_CHANNEL_MULTI_15, /**< 15 channels (Since 6.5) */
100 AUDIO_CHANNEL_MULTI_16 /**< 16 channels (Since 6.5) */
104 * @brief Enumeration for audio input and output state.
108 AUDIO_IO_STATE_IDLE, /**< Audio-io handle is created, but not prepared */
109 AUDIO_IO_STATE_RUNNING, /**< Audio-io handle is ready and the stream is running */
110 AUDIO_IO_STATE_PAUSED, /**< Audio-io handle is ready and the stream is paused */
114 * @brief Enumeration for audio input and output error.
118 AUDIO_IO_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */
119 AUDIO_IO_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */
120 AUDIO_IO_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
121 AUDIO_IO_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION, /**< Invalid operation */
122 AUDIO_IO_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Device open error by security */
123 AUDIO_IO_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */
124 AUDIO_IO_ERROR_DEVICE_POLICY_RESTRICTION = TIZEN_ERROR_DEVICE_POLICY_RESTRICTION, /**< Device policy restriction (Since 3.0) */
125 AUDIO_IO_ERROR_DEVICE_NOT_OPENED = TIZEN_ERROR_AUDIO_IO | 0x01, /**< Device open error */
126 AUDIO_IO_ERROR_DEVICE_NOT_CLOSED = TIZEN_ERROR_AUDIO_IO | 0x02, /**< Device close error */
127 AUDIO_IO_ERROR_INVALID_BUFFER = TIZEN_ERROR_AUDIO_IO | 0x03, /**< Invalid buffer pointer */
128 AUDIO_IO_ERROR_SOUND_POLICY = TIZEN_ERROR_AUDIO_IO | 0x04, /**< Sound policy error */
129 AUDIO_IO_ERROR_INVALID_STATE = TIZEN_ERROR_AUDIO_IO | 0x05, /**< Invalid state (Since 3.0) */
130 AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE = TIZEN_ERROR_AUDIO_IO | 0x06, /**< Not supported stream type (Since 3.0) */
138 * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
143 * @brief Called when audio input data is available in asynchronous (event) mode.
147 * @remarks Use audio_in_peek() to get 'audio in' data inside callback, use audio_in_drop() after use of peeked data.
149 * @param[in] handle The handle to the audio input
150 * @param[in] nbytes The amount of available 'audio in' data which can be peeked.
151 * @param[in] user_data The user data passed from the callback registration function
153 * @see audio_in_set_stream_cb()
155 typedef void (*audio_in_stream_cb)(audio_in_h handle, size_t nbytes, void *user_data);
158 * @brief Called when the state of audio input is changed.
162 * @param[in] handle The handle of the audio input
163 * @param[in] previous The previous state of the audio input
164 * @param[in] current The current state of the audio input
165 * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
166 * @param[in] user_data The user data passed from the callback registration function
168 * @see audio_in_set_state_changed_cb()
169 * @see audio_in_unset_state_changed_cb()
171 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);
174 * @brief Creates an audio device instance and returns an input handle to record PCM (pulse-code modulation) data.
176 * @details This function is used for audio input initialization.
180 * @privilege %http://tizen.org/privilege/recorder
182 * @remarks @a input must be released using audio_in_destroy().
183 * 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.
185 * @param[in] sample_rate The audio sample rate \n
186 * Before 5.0: 8000[Hz] ~ 48000[Hz] \n
187 * Since 5.0: 8000[Hz] ~ 192000[Hz]
188 * @param[in] channel The audio channel type \n
189 * Before 5.5: Mono or stereo \n
190 * Since 5.5: Mono, stereo or multi-channels
191 * @param[in] type The type of audio sample \n
192 * Before 5.0: 8 or 16-bit \n
193 * Since 5.0: 8, 16 or 24-bit \n
194 * Since 5.5: 8, 16, 24 or 32-bit
195 * @param[out] input An audio input handle is created on success
196 * @return @c 0 on success,
197 * otherwise a negative error value
198 * @retval #AUDIO_IO_ERROR_NONE Successful
199 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
200 * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
201 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
202 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
203 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
204 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
206 * @post The state will be #AUDIO_IO_STATE_IDLE.\n
207 * audio_in_set_sound_stream_info() is recommended to be called after this API.
208 * @see audio_in_destroy()
210 int audio_in_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_in_h *input);
213 * @brief Releases the audio input handle and all its resources associated with an audio stream.
217 * @param[in] input The handle to the audio input to destroy
218 * @return @c 0 on success,
219 * otherwise a negative error value
220 * @retval #AUDIO_IO_ERROR_NONE Successful
221 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
222 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
223 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
225 * @see audio_in_create()
227 int audio_in_destroy(audio_in_h input);
230 * @brief Sets the sound stream information to the audio input.
234 * @remarks The sound stream information includes audio routing and volume type.
235 * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
236 * System, Alarm, Notification, Emergency, Voice Information, Ringtone VOIP and Ringtone Call stream types are not supported in this API.
238 * @param[in] input The handle to the audio input
239 * @param[in] stream_info The handle of stream information
240 * @return @c 0 on success,
241 * otherwise a negative error value
242 * @retval #AUDIO_IO_ERROR_NONE Successful
243 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
244 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
245 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
246 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
248 * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
249 * Call audio_in_create() before calling this function.
250 * @post Call audio_in_prepare() after calling this function.
251 * @see sound_manager_create_stream_information()
252 * @see sound_manager_destroy_stream_information()
254 int audio_in_set_sound_stream_info(audio_in_h input, sound_stream_info_h stream_info);
257 * @brief Prepares the audio input for reading audio data by starting buffering of audio data from the device.
261 * @param[in] input The handle to the audio input
262 * @return @c 0 on success,
263 * otherwise a negative error value
264 * @retval #AUDIO_IO_ERROR_NONE Successful
265 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
266 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
267 * @retval #AUDIO_IO_ERROR_DEVICE_POLICY_RESTRICTION Device policy restriction
268 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
270 * @post The state will be #AUDIO_IO_STATE_RUNNING.
271 * @see audio_in_unprepare()
273 int audio_in_prepare(audio_in_h input);
276 * @brief Unprepares the audio input.
280 * @param[in] input The handle to the audio input
281 * @return @c 0 on success,
282 * otherwise a negative error value
283 * @retval #AUDIO_IO_ERROR_NONE Successful
284 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
285 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
286 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
288 * @post The state will be #AUDIO_IO_STATE_IDLE.
289 * @see audio_in_prepare()
291 int audio_in_unprepare(audio_in_h input);
294 * @brief Pauses buffering of audio data from the device.
298 * @param[in] input The handle to the audio input
299 * @return @c 0 on success,
300 * otherwise a negative error value
301 * @retval #AUDIO_IO_ERROR_NONE Successful
302 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
303 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
304 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
306 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
307 * @post The state will be #AUDIO_IO_STATE_PAUSED.
308 * @see audio_in_resume()
310 int audio_in_pause(audio_in_h input);
313 * @brief Resumes buffering audio data from the device.
317 * @param[in] input The handle to the audio input
318 * @return @c 0 on success,
319 * otherwise a negative error value
320 * @retval #AUDIO_IO_ERROR_NONE Successful
321 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
322 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
323 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
325 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
326 * @post The state will be #AUDIO_IO_STATE_RUNNING.
327 * @see audio_in_pause()
329 int audio_in_resume(audio_in_h input);
332 * @brief Flushes and discards buffered audio data from the input stream.
336 * @param[in] input The handle to the audio input
337 * @return @c 0 on success,
338 * otherwise a negative error value
339 * @retval #AUDIO_IO_ERROR_NONE Successful
340 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
341 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
342 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
344 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
346 int audio_in_flush(audio_in_h input);
349 * @brief Reads audio data from the audio input buffer.
353 * @param[in] input The handle to the audio input
354 * @param[out] buffer The PCM buffer address
355 * @param[in] length The length of the PCM data buffer (in bytes)
356 * @return The number of read bytes on success,
357 * otherwise a negative error value
358 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
359 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
360 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
361 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
362 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
364 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
366 int audio_in_read(audio_in_h input, void *buffer, unsigned int length);
369 * @brief Gets the size to be allocated for the audio input buffer.
373 * @param[in] input The handle to the audio input
374 * @param[out] size The buffer size (in bytes, the maximum size is 1 MB)
375 * @return @c 0 on success,
376 * otherwise a negative error value
377 * @retval #AUDIO_IO_ERROR_NONE Successful
378 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
379 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
380 * @see audio_in_read()
382 int audio_in_get_buffer_size(audio_in_h input, int *size);
385 * @brief Gets the sample rate of the audio input data stream.
389 * @param[in] input The handle to the audio input
390 * @param[out] sample_rate The audio sample rate \n
391 * Before 5.0: 8000[Hz] ~ 48000[Hz] \n
392 * Since 5.0: 8000[Hz] ~ 192000[Hz]
393 * @return @c 0 on success,
394 * otherwise a negative error value
395 * @retval #AUDIO_IO_ERROR_NONE Successful
396 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
397 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
399 int audio_in_get_sample_rate(audio_in_h input, int *sample_rate);
402 * @brief Gets the channel type of the audio input data stream.
406 * @param[in] input The handle to the audio input
407 * @param[out] channel The audio channel type \n
408 * Before 5.5: Mono or stereo \n
409 * Since 5.5: Mono, stereo or multi-channels
410 * @return @c 0 on success,
411 * otherwise a negative error value
412 * @retval #AUDIO_IO_ERROR_NONE Successful
413 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
414 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
416 int audio_in_get_channel(audio_in_h input, audio_channel_e *channel);
419 * @brief Gets the sample audio format of the audio input data stream.
423 * @param[in] input The handle to the audio input
424 * @param[out] type The type of audio sample \n
425 * Before 5.0: 8 or 16-bit \n
426 * Since 5.0: 8, 16 or 24-bit \n
427 * Since 5.5: 8, 16, 24 or 32-bit
428 * @return @c 0 on success,
429 * otherwise a negative error value
430 * @retval #AUDIO_IO_ERROR_NONE Successful
431 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
432 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
434 int audio_in_get_sample_type(audio_in_h input, audio_sample_type_e *type);
437 * @brief Sets an asynchronous (event) callback function to handle recording PCM (pulse-code modulation) data.
439 * @details @a callback will be called when you can read a PCM data.
440 * It might cause dead lock if change the state of audio handle in callback.
441 * (ex: audio_in_destroy(), audio_in_prepare(), audio_in_unprepare())
442 * Recommend to use as a VOIP only.
443 * Recommend not to hold callback too long.(it affects latency)
447 * @remarks @a input must be created using audio_in_create().
449 * @param[in] input An audio input handle
450 * @param[in] callback notify stream callback when user can read data (#audio_in_stream_cb)
451 * @param[in] user_data user data to be retrieved when callback is called
452 * @return @c 0 on success,
453 * otherwise a negative error value
454 * @retval #AUDIO_IO_ERROR_NONE Successful
455 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
456 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
457 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
458 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
459 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
461 * @see audio_in_unset_stream_cb()
463 int audio_in_set_stream_cb(audio_in_h input, audio_in_stream_cb callback, void* user_data);
466 * @brief Unregisters the callback function.
470 * @param[in] input The handle to the audio input
471 * @return @c 0 on success,
472 * otherwise a negative error value
473 * @retval #AUDIO_IO_ERROR_NONE Successful
474 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
475 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
476 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
478 * @see audio_in_set_stream_cb()
480 int audio_in_unset_stream_cb(audio_in_h input);
483 * @brief Peeks into the 'audio in' buffer.
485 * @details This function works correctly only with read callback. Otherwise it won't operate as intended.
489 * @remarks Works only in asynchronous (event) mode.
490 * 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.
491 * 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.
493 * @param[in] input The handle to the audio input
494 * @param[out] buffer start buffer pointer of peeked 'audio in' data
495 * @param[out] length amount of 'audio in' data to be peeked
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
502 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
504 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
505 * @see audio_in_drop()
507 int audio_in_peek(audio_in_h input, const void **buffer, unsigned int *length);
510 * @brief Drops the 'audio in' buffer that was peeked into.
512 * @details This function works correctly only with read callback. Otherwise it won't operate as intended.
516 * @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.
518 * @param[in] input The handle to the audio input
519 * @return 0 on success, otherwise a negative error value
520 * @retval #AUDIO_IO_ERROR_NONE Successful
521 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
522 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
523 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
524 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
526 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
527 * @see audio_in_peek()
529 int audio_in_drop(audio_in_h input);
532 * @brief Sets the state changed callback function to the audio input handle.
536 * @remarks @a input must be created using audio_in_create().
538 * @param[in] input The audio input handle
539 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_in_state_changed_cb)
540 * @param[in] user_data user data to be retrieved when callback is called
541 * @return @c 0 on success,
542 * otherwise a negative error value
543 * @retval #AUDIO_IO_ERROR_NONE Successful
544 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
545 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
547 * @see audio_in_unset_state_changed_cb()
549 int audio_in_set_state_changed_cb(audio_in_h input, audio_in_state_changed_cb callback, void* user_data);
552 * @brief Unregisters the state changed callback function of the audio input handle.
556 * @param[in] input The handle to the audio input
557 * @return @c 0 on success,
558 * otherwise a negative error value
559 * @retval #AUDIO_IO_ERROR_NONE Successful
560 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
561 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
563 * @see audio_in_set_state_changed_cb()
565 int audio_in_unset_state_changed_cb(audio_in_h input);
568 * @brief Gets the volume of the audio input data stream.
572 * @remarks The default @a volume of the audio input stream is 1.0.
574 * @param[in] input The handle to the audio input
575 * @param[out] volume The current volume value of the audio input stream
576 * @return @c 0 on success,
577 * otherwise a negative error value
578 * @retval #AUDIO_IO_ERROR_NONE Successful
579 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
580 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
582 * @see audio_in_set_volume()
584 int audio_in_get_volume(audio_in_h input, double *volume);
587 * @brief Sets the volume of the audio input data stream.
591 * @remarks The default @a volume of the audio input stream is 1.0.
592 * If the @a volume is less than 1.0, the loudness of recorded data will be decreased.
593 * If the @a volume is greater than 1.0, the loudness of recorded data will be increased,
594 * which can be useful when the loudness of original recorded data is too low in certain environments.
595 * 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.
597 * @param[in] input The handle to the audio input
598 * @param[in] volume The volume value to be set (0.0 <= volume <= 2.0)
599 * @return @c 0 on success,
600 * otherwise a negative error value
601 * @retval #AUDIO_IO_ERROR_NONE Successful
602 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
603 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
605 * @see audio_in_get_volume()
607 int audio_in_set_volume(audio_in_h input, double volume);
614 * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
619 * @brief Called when 'audio out' data can be written in asynchronous (event) mode.
623 * @remarks Use audio_out_write() to write pcm data inside this callback.
624 * @param[in] handle The handle to the audio output
625 * @param[in] nbytes The amount of 'audio in' data which can be written.
626 * @param[in] user_data The user data passed from the callback registration function
628 * @see audio_out_set_stream_cb()
630 typedef void (*audio_out_stream_cb)(audio_out_h handle, size_t nbytes, void *user_data);
633 * @brief Called when the state of audio output is changed.
637 * @param[in] handle The handle of the audio output
638 * @param[in] previous The previous state of the audio output
639 * @param[in] current The current state of the audio output
640 * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
641 * @param[in] user_data The user data passed from the callback registration function
643 * @see audio_out_set_state_changed_cb()
644 * @see audio_out_unset_state_changed_cb()
646 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);
649 * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
651 * @details This function is used for audio output initialization.
655 * @remarks @a output must be released by audio_out_destroy().
656 * It is recommended to call audio_out_set_sound_stream_info() after this API.
657 * Multi-channel playback is not supported.
659 * @param[in] sample_rate The audio sample rate \n
660 * Before 5.0: 8000[Hz] ~ 48000[Hz] \n
661 * Since 5.0: 8000[Hz] ~ 192000[Hz]
662 * @param[in] channel The audio channel type (mono or stereo)
663 * @param[in] type The type of audio sample \n
664 * Before 5.0: 8 or 16-bit \n
665 * Since 5.0: 8, 16 or 24-bit \n
666 * Since 5.5: 8, 16, 24 or 32-bit
667 * @param[out] output An audio output handle is created on success
668 * @return @c 0 on success,
669 * otherwise a negative error value
670 * @retval #AUDIO_IO_ERROR_NONE Successful
671 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
672 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
673 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
674 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
676 * @post The state will be #AUDIO_IO_STATE_IDLE.\n
677 * audio_out_set_sound_stream_info() is recommended to be called after this API.
678 * @see audio_out_destroy()
680 int audio_out_create_new(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_out_h *output);
683 * @brief Releases the audio output handle, along with all its resources.
687 * @param[in] output The handle to the audio output to destroy
688 * @return @c 0 on success,
689 * otherwise a negative error value
690 * @retval #AUDIO_IO_ERROR_NONE Successful
691 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
692 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
693 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
695 * @see audio_out_create_new()
697 int audio_out_destroy(audio_out_h output);
700 * @brief Sets the sound stream information to the audio output.
704 * @remarks The sound stream information includes audio routing and volume type.
705 * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
706 * Voice Recognition and Loopback stream types are not supported in this API.
708 * @param[in] output The handle to the audio output
709 * @param[in] stream_info The handle of stream information
710 * @return @c 0 on success,
711 * otherwise a negative error value
712 * @retval #AUDIO_IO_ERROR_NONE Successful
713 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
714 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
715 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
716 * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
718 * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
719 * Call audio_out_create_new() before calling this function.
720 * @post Call audio_out_prepare() after calling this function.
721 * @see sound_manager_create_stream_information()
722 * @see sound_manager_destroy_stream_information()
724 int audio_out_set_sound_stream_info(audio_out_h output, sound_stream_info_h stream_info);
727 * @brief Prepares the audio output for playback, this must be called before audio_out_write().
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 * @post The state will be #AUDIO_IO_STATE_RUNNING.
739 * @see audio_out_unprepare()
741 int audio_out_prepare(audio_out_h output);
744 * @brief Unprepares the audio output.
748 * @param[in] output The handle to the audio output
749 * @return @c 0 on success,
750 * otherwise a negative error value
751 * @retval #AUDIO_IO_ERROR_NONE Successful
752 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
753 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
755 * @post The state will be #AUDIO_IO_STATE_IDLE.
756 * @see audio_out_prepare()
758 int audio_out_unprepare(audio_out_h output);
761 * @brief Pauses feeding of audio data to the device.
765 * @param[in] output The handle to the audio output
766 * @return @c 0 on success,
767 * otherwise a negative error value
768 * @retval #AUDIO_IO_ERROR_NONE Successful
769 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
770 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
772 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
773 * @post The state will be #AUDIO_IO_STATE_PAUSED.
774 * @see audio_out_resume()
776 int audio_out_pause(audio_out_h output);
779 * @brief Resumes feeding of audio data to the device.
783 * @param[in] output The handle to the audio output
784 * @return @c 0 on success,
785 * otherwise a negative error value
786 * @retval #AUDIO_IO_ERROR_NONE Successful
787 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
788 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
790 * @pre The state should be #AUDIO_IO_STATE_PAUSED.
791 * @post The state will be #AUDIO_IO_STATE_RUNNING.
792 * @see audio_out_pause()
794 int audio_out_resume(audio_out_h output);
797 * @brief Drains buffered audio data from the output stream.
799 * @details This function waits until drains stream buffer completely. (e.g end of playback)
803 * @param[in] output The handle to the audio output
804 * @return @c 0 on success,
805 * otherwise a negative error value
806 * @retval #AUDIO_IO_ERROR_NONE Successful
807 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
808 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
810 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
811 * @see audio_out_flush()
813 int audio_out_drain(audio_out_h output);
816 * @brief Flushes and discards buffered audio data from the output stream.
820 * @param[in] output The handle to the audio output
821 * @return @c 0 on success,
822 * otherwise a negative error value
823 * @retval #AUDIO_IO_ERROR_NONE Successful
824 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
825 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
827 * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
828 * @see audio_out_drain()
830 int audio_out_flush(audio_out_h output);
833 * @brief Starts writing the audio data to the device.
837 * @param[in] output The handle to the audio output
838 * @param[in,out] buffer The PCM buffer address
839 * @param[in] length The length of the PCM buffer (in bytes)
840 * @return The written data size on success,
841 * otherwise a negative error value
842 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
843 * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
844 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
845 * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
847 * @pre The state should be #AUDIO_IO_STATE_RUNNING.
849 int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
852 * @brief Gets the size to be allocated for the audio output buffer.
856 * @param[in] output The handle to the audio output
857 * @param[out] size The suggested buffer size (in bytes, the maximum size is 1 MB)
858 * @return @c 0 on success,
859 * otherwise a negative error value
860 * @retval #AUDIO_IO_ERROR_NONE Successful
861 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
863 * @see audio_out_write()
865 int audio_out_get_buffer_size(audio_out_h output, int *size);
868 * @brief Gets the sample rate of the audio output data stream.
872 * @param[in] output The handle to the audio output
873 * @param[out] sample_rate The audio sample rate \n
874 * Before 5.0: 8000[Hz] ~ 48000[Hz] \n
875 * Since 5.0: 8000[Hz] ~ 192000[Hz]
876 * @return @c 0 on success,
877 * otherwise a negative error value
878 * @retval #AUDIO_IO_ERROR_NONE Successful
879 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
881 int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
884 * @brief Gets the channel type of the audio output data stream.
888 * @param[in] output The handle to the audio output
889 * @param[out] channel The audio channel type (mono or stereo)
890 * @return @c 0 on success,
891 * otherwise a negative error value
892 * @retval #AUDIO_IO_ERROR_NONE Successful
893 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
895 int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
898 * @brief Gets the sample audio format of the audio output data stream.
902 * @param[in] output The handle to the audio output
903 * @param[out] type The type of audio sample \n
904 * Before 5.0: 8 or 16-bit \n
905 * Since 5.0: 8, 16 or 24-bit \n
906 * Since 5.5: 8, 16, 24 or 32-bit
907 * @return @c 0 on success,
908 * otherwise a negative error value
909 * @retval #AUDIO_IO_ERROR_NONE Successful
910 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
912 int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
915 * @brief Gets the sound type supported by the audio output device.
919 * @param[in] output The handle to the audio output
920 * @param[out] type The sound type
921 * @return @c 0 on success,
922 * otherwise a negative error value
923 * @retval #AUDIO_IO_ERROR_NONE Successful
924 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
926 int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
929 * @brief Sets an asynchronous (event) callback function to handle playing PCM (pulse-code modulation) data.
931 * @details @a callback will be called when you can write a PCM data.
932 * It might cause dead lock if change the state of audio handle in callback.
933 * (ex: audio_out_destroy(), audio_out_prepare(), audio_out_unprepare())
934 * Recommend to use as a VOIP only.
935 * Recommend not to hold callback too long.(it affects latency)
939 * @remarks @a output must be created using audio_out_create_new().
941 * @param[in] output An audio output handle
942 * @param[in] callback notify stream callback when user can write data (#audio_out_stream_cb)
943 * @param[in] user_data user data to be retrieved when callback is called
944 * @return 0 on success, otherwise a negative error value
945 * @retval #AUDIO_IO_ERROR_NONE Successful
946 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
947 * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
948 * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
949 * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
951 * @see audio_out_unset_stream_cb()
953 int audio_out_set_stream_cb(audio_out_h output, audio_out_stream_cb callback, void* user_data);
956 * @brief Unregisters the callback function.
960 * @param[in] output The handle to the audio output
961 * @return 0 on success, otherwise a negative error value
962 * @retval #AUDIO_IO_ERROR_NONE Successful
963 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
964 * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
966 * @see audio_out_set_stream_cb()
968 int audio_out_unset_stream_cb(audio_out_h output);
971 * @brief Sets the state changed callback function to the audio output handle.
975 * @remarks @a input must be created using audio_out_create_new().
977 * @param[in] output The audio output handle
978 * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_out_state_changed_cb)
979 * @param[in] user_data user data to be retrieved when callback is called
980 * @return @c 0 on success,
981 * otherwise a negative error value
982 * @retval #AUDIO_IO_ERROR_NONE Successful
983 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
985 * @see audio_out_unset_state_changed_cb()
987 int audio_out_set_state_changed_cb(audio_out_h output, audio_out_state_changed_cb callback, void* user_data);
990 * @brief Unregisters the state changed callback function of the audio output handle.
994 * @param[in] output The handle to the audio output
995 * @return @c 0 on success,
996 * otherwise a negative error value
997 * @retval #AUDIO_IO_ERROR_NONE Successful
998 * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
1000 * @see audio_out_set_state_changed_cb()
1002 int audio_out_unset_state_changed_cb(audio_out_h output);
1012 #endif /* __TIZEN_MEDIA_AUDIO_IO_H__ */