X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=include%2Faudio_io.h;h=421b0d52f1a31f727b4f5601053f3390d9feebfa;hb=b991401f92f2064a91ddff4432560d29bfc53aff;hp=397235af446e5209ac1c820c4fabacf798fa5fdf;hpb=7e9f563ebfc3c1b8b575d7c053ca4826b5a116a5;p=platform%2Fcore%2Fapi%2Faudio-io.git diff --git a/include/audio_io.h b/include/audio_io.h index 397235a..421b0d5 100644 --- a/include/audio_io.h +++ b/include/audio_io.h @@ -17,13 +17,12 @@ #ifndef __TIZEN_MEDIA_AUDIO_IO_H__ #define __TIZEN_MEDIA_AUDIO_IO_H__ +#include #include #include -#include #ifdef __cplusplus -extern "C" -{ +extern "C" { #endif /** @@ -70,10 +69,12 @@ typedef struct audio_io_s *audio_out_h; * @brief Enumeration for audio sample type with bit depth. * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ -typedef enum -{ - AUDIO_SAMPLE_TYPE_U8 = 0x70, /**< Unsigned 8-bit audio samples */ - AUDIO_SAMPLE_TYPE_S16_LE, /**< Signed 16-bit audio samples */ +typedef enum { + AUDIO_SAMPLE_TYPE_U8 = 0x70, /**< Unsigned 8-bit audio samples */ + AUDIO_SAMPLE_TYPE_S16_LE, /**< Signed 16-bit audio samples */ + AUDIO_SAMPLE_TYPE_S24_LE, /**< Signed 24-bit audio samples (Since 5.0) */ + AUDIO_SAMPLE_TYPE_S24_32_LE, /**< Signed 24-bit (packed in 32-bit) audio samples (Since 5.0) */ + AUDIO_SAMPLE_TYPE_S32_LE, /**< Signed 32-bit audio samples (Since 5.5) */ } audio_sample_type_e; /** @@ -81,73 +82,47 @@ typedef enum * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ typedef enum { - AUDIO_CHANNEL_MONO = 0x80, /**< 1 channel, mono */ - AUDIO_CHANNEL_STEREO, /**< 2 channel, stereo */ + AUDIO_CHANNEL_MONO = 0x80, /**< 1 channel, mono */ + AUDIO_CHANNEL_STEREO, /**< 2 channels, stereo */ + AUDIO_CHANNEL_MULTI_3, /**< 3 channels (Since 5.5) */ + AUDIO_CHANNEL_MULTI_4, /**< 4 channels (Since 5.5) */ + AUDIO_CHANNEL_MULTI_5, /**< 5 channels (Since 5.5) */ + AUDIO_CHANNEL_MULTI_6, /**< 6 channels (Since 5.5) */ + AUDIO_CHANNEL_MULTI_7, /**< 7 channels (Since 5.5) */ + AUDIO_CHANNEL_MULTI_8, /**< 8 channels (Since 5.5) */ } audio_channel_e; /** * @brief Enumeration for audio input and output state. * @since_tizen 3.0 */ -typedef enum -{ - AUDIO_IO_STATE_IDLE, /**< Audio-io handle is created, but not prepared */ - AUDIO_IO_STATE_RUNNING, /**< Audio-io handle is ready and the stream is running */ - AUDIO_IO_STATE_PAUSED, /**< Audio-io handle is ready and the stream is paused */ +typedef enum { + AUDIO_IO_STATE_IDLE, /**< Audio-io handle is created, but not prepared */ + AUDIO_IO_STATE_RUNNING, /**< Audio-io handle is ready and the stream is running */ + AUDIO_IO_STATE_PAUSED, /**< Audio-io handle is ready and the stream is paused */ } audio_io_state_e; /** * @brief Enumeration for audio input and output error. * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif */ -typedef enum{ - AUDIO_IO_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ - AUDIO_IO_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ - AUDIO_IO_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ - AUDIO_IO_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION, /**< Invalid operation */ - AUDIO_IO_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Device open error by security */ - AUDIO_IO_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */ - AUDIO_IO_ERROR_DEVICE_NOT_OPENED = TIZEN_ERROR_AUDIO_IO | 0x01, /**< Device open error */ - AUDIO_IO_ERROR_DEVICE_NOT_CLOSED = TIZEN_ERROR_AUDIO_IO | 0x02, /**< Device close error */ - AUDIO_IO_ERROR_INVALID_BUFFER = TIZEN_ERROR_AUDIO_IO | 0x03, /**< Invalid buffer pointer */ - AUDIO_IO_ERROR_SOUND_POLICY = TIZEN_ERROR_AUDIO_IO | 0x04, /**< Sound policy error */ - AUDIO_IO_ERROR_INVALID_STATE = TIZEN_ERROR_AUDIO_IO | 0x05, /**< Invalid state (Since 3.0) */ - AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE = TIZEN_ERROR_AUDIO_IO | 0x06, /**< Not supported stream type (Since 3.0) */ +typedef enum { + AUDIO_IO_ERROR_NONE = TIZEN_ERROR_NONE, /**< Successful */ + AUDIO_IO_ERROR_OUT_OF_MEMORY = TIZEN_ERROR_OUT_OF_MEMORY, /**< Out of memory */ + AUDIO_IO_ERROR_INVALID_PARAMETER = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */ + AUDIO_IO_ERROR_INVALID_OPERATION = TIZEN_ERROR_INVALID_OPERATION, /**< Invalid operation */ + AUDIO_IO_ERROR_PERMISSION_DENIED = TIZEN_ERROR_PERMISSION_DENIED, /**< Device open error by security */ + AUDIO_IO_ERROR_NOT_SUPPORTED = TIZEN_ERROR_NOT_SUPPORTED, /**< Not supported */ + AUDIO_IO_ERROR_DEVICE_POLICY_RESTRICTION = TIZEN_ERROR_DEVICE_POLICY_RESTRICTION, /**< Device policy restriction (Since 3.0) */ + AUDIO_IO_ERROR_DEVICE_NOT_OPENED = TIZEN_ERROR_AUDIO_IO | 0x01, /**< Device open error */ + AUDIO_IO_ERROR_DEVICE_NOT_CLOSED = TIZEN_ERROR_AUDIO_IO | 0x02, /**< Device close error */ + AUDIO_IO_ERROR_INVALID_BUFFER = TIZEN_ERROR_AUDIO_IO | 0x03, /**< Invalid buffer pointer */ + AUDIO_IO_ERROR_SOUND_POLICY = TIZEN_ERROR_AUDIO_IO | 0x04, /**< Sound policy error */ + AUDIO_IO_ERROR_INVALID_STATE = TIZEN_ERROR_AUDIO_IO | 0x05, /**< Invalid state (Since 3.0) */ + AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE = TIZEN_ERROR_AUDIO_IO | 0x06, /**< Not supported stream type (Since 3.0) */ } audio_io_error_e; /** - * @deprecated Deprecated since 3.0 - * @brief Enumeration for audio IO interrupted messages. - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - */ -typedef enum -{ - AUDIO_IO_INTERRUPTED_COMPLETED = 0, /**< Interrupt completed */ - AUDIO_IO_INTERRUPTED_BY_MEDIA, /**< Interrupted by a media application */ - AUDIO_IO_INTERRUPTED_BY_CALL, /**< Interrupted by an incoming call */ - AUDIO_IO_INTERRUPTED_BY_EARJACK_UNPLUG, /**< Interrupted by unplugging headphones */ - AUDIO_IO_INTERRUPTED_BY_RESOURCE_CONFLICT, /**< Interrupted by a resource conflict */ - AUDIO_IO_INTERRUPTED_BY_ALARM, /**< Interrupted by an alarm */ - AUDIO_IO_INTERRUPTED_BY_EMERGENCY, /**< Interrupted by an emergency */ - AUDIO_IO_INTERRUPTED_BY_NOTIFICATION, /**< Interrupted by a notification */ -} audio_io_interrupted_code_e; - -/** - * @deprecated Deprecated since 3.0. Use sound_stream_focus_state_changed_cb instead. - * @brief Called when audio input or output is interrupted. - * - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * @param[in] error_code The interrupted error code - * @param[in] user_data The user data passed from the callback registration function - * - * @see audio_in_set_interrupted_cb() - * @see audio_out_set_interrupted_cb() - * @see audio_in_unset_interrupted_cb() - * @see audio_out_unset_interrupted_cb() - */ -typedef void (*audio_io_interrupted_cb)(audio_io_interrupted_code_e code, void *user_data); - -/** * @} */ @@ -156,19 +131,15 @@ typedef void (*audio_io_interrupted_cb)(audio_io_interrupted_code_e code, void * * @{ */ -// -//AUDIO INPUT -// - /** - * @brief Called when audio input data is available in asynchronous(event) mode. + * @brief Called when audio input data is available in asynchronous (event) mode. * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * - * @remarks @a use audio_in_peek() to get audio in data inside callback, use audio_in_drop() after use of peeked data. + * @remarks Use audio_in_peek() to get 'audio in' data inside callback, use audio_in_drop() after use of peeked data. * * @param[in] handle The handle to the audio input - * @param[in] nbytes The amount of available audio in data which can be peeked. + * @param[in] nbytes The amount of available 'audio in' data which can be peeked. * @param[in] user_data The user data passed from the callback registration function * * @see audio_in_set_stream_cb() @@ -201,10 +172,18 @@ typedef void (*audio_in_state_changed_cb)(audio_in_h handle, audio_io_state_e pr * @privilege %http://tizen.org/privilege/recorder * * @remarks @a input must be released using audio_in_destroy(). - * - * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz] - * @param[in] channel The audio channel type (mono or stereo) - * @param[in] type The type of audio sample (8- or 16-bit) + * 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. + * + * @param[in] sample_rate The audio sample rate \n + * Before 5.0: 8000[Hz] ~ 48000[Hz] \n + * Since 5.0: 8000[Hz] ~ 192000[Hz] + * @param[in] channel The audio channel type \n + * Before 5.5: Mono or stereo \n + * Since 5.5: Mono, stereo or multi-channels + * @param[in] type The type of audio sample \n + * Before 5.0: 8 or 16-bit \n + * Since 5.0: 8, 16 or 24-bit \n + * Since 5.5: 8, 16, 24 or 32-bit * @param[out] input An audio input handle is created on success * @return @c 0 on success, * otherwise a negative error value @@ -217,42 +196,12 @@ typedef void (*audio_in_state_changed_cb)(audio_in_h handle, audio_io_state_e pr * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported * * @post The state will be #AUDIO_IO_STATE_IDLE.\n - * audio_in_set_stream_info() is recommended to be called after this API. + * audio_in_set_sound_stream_info() is recommended to be called after this API. * @see audio_in_destroy() */ int audio_in_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_in_h *input); /** - * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead. - * @brief Creates an audio loopback device instance and returns an input handle to record PCM (pulse-code modulation) data. - * - * @details This function is used for audio loopback input initialization. - * - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * @privlevel public - * @privilege %http://tizen.org/privilege/recorder - * - * @remarks @a input must be released using audio_in_destroy(). - * - * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz] - * @param[in] channel The audio channel type, mono, or stereo - * @param[in] type The type of audio sample (8- or 16-bit) - * @param[out] input An audio input handle will be created, if successful - * @return @c 0 on success, - * otherwise a negative error value - * @retval #AUDIO_IO_ERROR_NONE Successful - * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied - * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory - * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened - * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error - * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported - * - * @see audio_in_destroy() - */ -int audio_in_create_loopback(int sample_rate, audio_channel_e channel, audio_sample_type_e type , audio_in_h* input); - -/** * @brief Releases the audio input handle and all its resources associated with an audio stream. * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif @@ -274,7 +223,7 @@ int audio_in_destroy(audio_in_h input); * * @since_tizen 3.0 * - * @remarks @a the sound stream information includes audio routing and volume type. + * @remarks The sound stream information includes audio routing and volume type. * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE * System, Alarm, Notification, Emergency, Voice Information, Ringtone VOIP and Ringtone Call stream types are not supported in this API. * @@ -294,7 +243,7 @@ int audio_in_destroy(audio_in_h input); * @see sound_manager_create_stream_information() * @see sound_manager_destroy_stream_information() */ -int audio_in_set_stream_info(audio_in_h input, sound_stream_info_h stream_info); +int audio_in_set_sound_stream_info(audio_in_h input, sound_stream_info_h stream_info); /** * @brief Prepares the audio input for reading audio data by starting buffering of audio data from the device. @@ -307,6 +256,7 @@ int audio_in_set_stream_info(audio_in_h input, sound_stream_info_h stream_info); * @retval #AUDIO_IO_ERROR_NONE Successful * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported + * @retval #AUDIO_IO_ERROR_DEVICE_POLICY_RESTRICTION Device policy restriction * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state * * @post The state will be #AUDIO_IO_STATE_RUNNING. @@ -373,7 +323,7 @@ int audio_in_resume(audio_in_h input); /** * @brief Flushes and discards buffered audio data from the input stream. * - * @since_tizen 2.4 + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif * * @param[in] input The handle to the audio input * @return @c 0 on success, @@ -429,7 +379,9 @@ int audio_in_get_buffer_size(audio_in_h input, int *size); * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * * @param[in] input The handle to the audio input - * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000) + * @param[out] sample_rate The audio sample rate \n + * Before 5.0: 8000[Hz] ~ 48000[Hz] \n + * Since 5.0: 8000[Hz] ~ 192000[Hz] * @return @c 0 on success, * otherwise a negative error value * @retval #AUDIO_IO_ERROR_NONE Successful @@ -441,12 +393,12 @@ int audio_in_get_sample_rate(audio_in_h input, int *sample_rate); /** * @brief Gets the channel type of the audio input data stream. * - * @details The audio channel type defines whether the audio is mono or stereo. - * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * * @param[in] input The handle to the audio input - * @param[out] channel The audio channel type + * @param[out] channel The audio channel type \n + * Before 5.5: Mono or stereo \n + * Since 5.5: Mono, stereo or multi-channels * @return @c 0 on success, * otherwise a negative error value * @retval #AUDIO_IO_ERROR_NONE Successful @@ -456,12 +408,15 @@ int audio_in_get_sample_rate(audio_in_h input, int *sample_rate); int audio_in_get_channel(audio_in_h input, audio_channel_e *channel); /** - * @brief Gets the sample audio format (8-bit or 16-bit) of the audio input data stream. + * @brief Gets the sample audio format of the audio input data stream. * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * * @param[in] input The handle to the audio input - * @param[out] type The audio sample type + * @param[out] type The type of audio sample \n + * Before 5.0: 8 or 16-bit \n + * Since 5.0: 8, 16 or 24-bit \n + * Since 5.5: 8, 16, 24 or 32-bit * @return @c 0 on success, * otherwise a negative error value * @retval #AUDIO_IO_ERROR_NONE Successful @@ -471,67 +426,11 @@ int audio_in_get_channel(audio_in_h input, audio_channel_e *channel); int audio_in_get_sample_type(audio_in_h input, audio_sample_type_e *type); /** - * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead. - * @brief Registers a callback function to be invoked when the audio input handle is interrupted or the interrupt is completed. - * - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @param[in] input The handle to the audio input - * @param[in] callback The callback function to register - * @param[in] user_data The user data to be passed to the callback function - * @return @c 0 on success, - * otherwise a negative error value - * @retval #AUDIO_IO_ERROR_NONE Successful - * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation - * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported - * @post audio_io_interrupted_cb() will be invoked. - * - * @see audio_in_unset_interrupted_cb() - * @see audio_io_interrupted_cb() - */ -int audio_in_set_interrupted_cb(audio_in_h input, audio_io_interrupted_cb callback, void *user_data); - -/** - * @deprecated Deprecated since 3.0 - * @brief Unregisters the callback function. - * - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @param[in] input The handle to the audio input - * @return @c 0 on success, - * otherwise a negative error value - * @retval #AUDIO_IO_ERROR_NONE Successful - * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation - * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported - * - * @see audio_in_set_interrupted_cb() - */ -int audio_in_unset_interrupted_cb(audio_in_h input); - -/** - * @deprecated Deprecated since 3.0 - * @brief Ignores session for input. - * - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @param[in] input The handle to the audio input - * @return @c 0 on success, - * otherwise a negative error value - * @retval #AUDIO_IO_ERROR_NONE Successful - * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation - * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported - */ -int audio_in_ignore_session(audio_in_h input); - -/** - * @brief Sets an asynchronous(event) callback function to handle recording PCM (pulse-code modulation) data. + * @brief Sets an asynchronous (event) callback function to handle recording PCM (pulse-code modulation) data. * * @details @a callback will be called when you can read a PCM data. * It might cause dead lock if change the state of audio handle in callback. - * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare) + * (ex: audio_in_destroy(), audio_in_prepare(), audio_in_unprepare()) * Recommend to use as a VOIP only. * Recommend not to hold callback too long.(it affects latency) * @@ -551,7 +450,7 @@ int audio_in_ignore_session(audio_in_h input); * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported * - * @see audio_out_set_stream_cb() + * @see audio_in_unset_stream_cb() */ int audio_in_set_stream_cb(audio_in_h input, audio_in_stream_cb callback, void* user_data); @@ -568,22 +467,24 @@ int audio_in_set_stream_cb(audio_in_h input, audio_in_stream_cb callback, void* * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported * - * @see audio_in_set_interrupted_cb() + * @see audio_in_set_stream_cb() */ int audio_in_unset_stream_cb(audio_in_h input); /** - * @brief peek from audio in buffer + * @brief Peeks into the 'audio in' buffer. * - * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended. + * @details This function works correctly only with read callback. Otherwise it won't operate as intended. * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * - * @remarks @a Works only in asynchronous(event) mode. This will just retrieve buffer pointer from audio in buffer. Drop after use. + * @remarks Works only in asynchronous (event) mode. + * 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. + * 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. * * @param[in] input The handle to the audio input - * @param[out] buffer start buffer pointer of peeked audio in data - * @param[in,out] length amount of audio in data to be peeked + * @param[out] buffer start buffer pointer of peeked 'audio in' data + * @param[out] length amount of 'audio in' data to be peeked * @return @c 0 on success, * otherwise a negative error value * @retval #AUDIO_IO_ERROR_NONE Successful @@ -598,13 +499,13 @@ int audio_in_unset_stream_cb(audio_in_h input); int audio_in_peek(audio_in_h input, const void **buffer, unsigned int *length); /** - * @brief drop peeked audio buffer. + * @brief Drops the 'audio in' buffer that was peeked into. * - * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended. + * @details This function works correctly only with read callback. Otherwise it won't operate as intended. * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * - * @remarks @a Works only in asynchronous(event) mode. This will remove audio in data from actual stream buffer. Use this if peeked data is not needed anymore. + * @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. * * @param[in] input The handle to the audio input * @return 0 on success, otherwise a negative error value @@ -656,12 +557,50 @@ int audio_in_set_state_changed_cb(audio_in_h input, audio_in_state_changed_cb ca int audio_in_unset_state_changed_cb(audio_in_h input); /** - * @} + * @brief Gets the volume of the audio input data stream. + * + * @since_tizen 6.0 + * + * @remarks The default @a volume of the audio input stream is 1.0. + * + * @param[in] input The handle to the audio input + * @param[out] volume The current volume value of the audio input stream + * @return @c 0 on success, + * otherwise a negative error value + * @retval #AUDIO_IO_ERROR_NONE Successful + * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported + * + * @see audio_in_set_volume() + */ +int audio_in_get_volume(audio_in_h input, double *volume); + +/** + * @brief Sets the volume of the audio input data stream. + * + * @since_tizen 6.0 + * + * @remarks The default @a volume of the audio input stream is 1.0. + * If the @a volume is less than 1.0, the loudness of recorded data will be decreased. + * If the @a volume is greater than 1.0, the loudness of recorded data will be increased, + * which can be useful when the loudness of original recorded data is too low in certain environments. + * 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. + * + * @param[in] input The handle to the audio input + * @param[in] volume The volume value to be set (0.0 <= volume <= 2.0) + * @return @c 0 on success, + * otherwise a negative error value + * @retval #AUDIO_IO_ERROR_NONE Successful + * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter + * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported + * + * @see audio_in_get_volume() */ +int audio_in_set_volume(audio_in_h input, double volume); -// -// AUDIO OUTPUT -// +/** + * @} + */ /** * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE @@ -669,13 +608,13 @@ int audio_in_unset_state_changed_cb(audio_in_h input); */ /** - * @brief Called when audio out data can be written in asynchronous(event) mode. + * @brief Called when 'audio out' data can be written in asynchronous (event) mode. * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * - * @remarks @a use audio_out_write() to write pcm data inside this callback. + * @remarks Use audio_out_write() to write pcm data inside this callback. * @param[in] handle The handle to the audio output - * @param[in] nbytes The amount of audio in data which can be written. + * @param[in] nbytes The amount of 'audio in' data which can be written. * @param[in] user_data The user data passed from the callback registration function * * @see audio_out_set_stream_cb() @@ -699,33 +638,6 @@ typedef void (*audio_out_stream_cb)(audio_out_h handle, size_t nbytes, void *use 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); /** - * @deprecated Deprecated since 3.0. Use audio_out_create_new() instead. - * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data. - * - * @details This function is used for audio output initialization. - * - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @remarks @a output must be released by audio_out_destroy(). - * - * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz] - * @param[in] channel The audio channel type (mono or stereo) - * @param[in] type The type of audio sample (8-bit or 16-bit) - * @param[in] sound_type The type of sound (#sound_type_e) - * @param[out] output An audio output handle is created on success - * @return @c 0 on success, - * otherwise a negative error value - * @retval #AUDIO_IO_ERROR_NONE Successful - * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory - * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened - * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error - * - * @see audio_out_destroy() - */ -int audio_out_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type, sound_type_e sound_type, audio_out_h *output); - -/** * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data. * * @details This function is used for audio output initialization. @@ -733,11 +645,17 @@ int audio_out_create(int sample_rate, audio_channel_e channel, audio_sample_type * @since_tizen 3.0 * * @remarks @a output must be released by audio_out_destroy(). - * It is recommended to call audio_out_set_stream_info() after this API. + * It is recommended to call audio_out_set_sound_stream_info() after this API. + * Multi-channel playback is not supported. * - * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz] + * @param[in] sample_rate The audio sample rate \n + * Before 5.0: 8000[Hz] ~ 48000[Hz] \n + * Since 5.0: 8000[Hz] ~ 192000[Hz] * @param[in] channel The audio channel type (mono or stereo) - * @param[in] type The type of audio sample (8-bit or 16-bit) + * @param[in] type The type of audio sample \n + * Before 5.0: 8 or 16-bit \n + * Since 5.0: 8, 16 or 24-bit \n + * Since 5.5: 8, 16, 24 or 32-bit * @param[out] output An audio output handle is created on success * @return @c 0 on success, * otherwise a negative error value @@ -748,7 +666,7 @@ int audio_out_create(int sample_rate, audio_channel_e channel, audio_sample_type * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error * * @post The state will be #AUDIO_IO_STATE_IDLE.\n - * audio_out_set_stream_info() is recommended to be called after this API. + * audio_out_set_sound_stream_info() is recommended to be called after this API. * @see audio_out_destroy() */ int audio_out_create_new(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_out_h *output); @@ -766,7 +684,7 @@ int audio_out_create_new(int sample_rate, audio_channel_e channel, audio_sample_ * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed * - * @see audio_out_create() + * @see audio_out_create_new() */ int audio_out_destroy(audio_out_h output); @@ -775,7 +693,7 @@ int audio_out_destroy(audio_out_h output); * * @since_tizen 3.0 * - * @remarks @a the sound stream information includes audio routing and volume type. + * @remarks The sound stream information includes audio routing and volume type. * For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE * Voice Recognition and Loopback stream types are not supported in this API. * @@ -795,7 +713,7 @@ int audio_out_destroy(audio_out_h output); * @see sound_manager_create_stream_information() * @see sound_manager_destroy_stream_information() */ -int audio_out_set_stream_info(audio_out_h output, sound_stream_info_h stream_info); +int audio_out_set_sound_stream_info(audio_out_h output, sound_stream_info_h stream_info); /** * @brief Prepares the audio output for playback, this must be called before audio_out_write(). @@ -872,7 +790,7 @@ int audio_out_resume(audio_out_h output); * * @details This function waits until drains stream buffer completely. (e.g end of playback) * - * @since_tizen 2.4 + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif * * @param[in] output The handle to the audio output * @return @c 0 on success, @@ -889,7 +807,7 @@ int audio_out_drain(audio_out_h output); /** * @brief Flushes and discards buffered audio data from the output stream. * - * @since_tizen 2.4 + * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif * * @param[in] output The handle to the audio output * @return @c 0 on success, @@ -944,7 +862,9 @@ int audio_out_get_buffer_size(audio_out_h output, int *size); * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * * @param[in] output The handle to the audio output - * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000) + * @param[out] sample_rate The audio sample rate \n + * Before 5.0: 8000[Hz] ~ 48000[Hz] \n + * Since 5.0: 8000[Hz] ~ 192000[Hz] * @return @c 0 on success, * otherwise a negative error value * @retval #AUDIO_IO_ERROR_NONE Successful @@ -955,12 +875,10 @@ int audio_out_get_sample_rate(audio_out_h output, int *sample_rate); /** * @brief Gets the channel type of the audio output data stream. * - * @details The audio channel type defines whether the audio is mono or stereo. - * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * * @param[in] output The handle to the audio output - * @param[out] channel The audio channel type + * @param[out] channel The audio channel type (mono or stereo) * @return @c 0 on success, * otherwise a negative error value * @retval #AUDIO_IO_ERROR_NONE Successful @@ -969,12 +887,15 @@ int audio_out_get_sample_rate(audio_out_h output, int *sample_rate); int audio_out_get_channel(audio_out_h output, audio_channel_e *channel); /** - * @brief Gets the sample audio format (8-bit or 16-bit) of the audio output data stream. + * @brief Gets the sample audio format of the audio output data stream. * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * * @param[in] output The handle to the audio output - * @param[out] type The audio sample type + * @param[out] type The type of audio sample \n + * Before 5.0: 8 or 16-bit \n + * Since 5.0: 8, 16 or 24-bit \n + * Since 5.5: 8, 16, 24 or 32-bit * @return @c 0 on success, * otherwise a negative error value * @retval #AUDIO_IO_ERROR_NONE Successful @@ -997,70 +918,17 @@ int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type); int audio_out_get_sound_type(audio_out_h output, sound_type_e *type); /** - * @deprecated Deprecated since 3.0. Use sound_manager_create_stream_information() instead. - * @brief Registers a callback function to be invoked when the audio output handle is interrupted or the interrupt is completed. - * - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @param[in] output The handle to the audio output - * @param[in] callback The callback function to register - * @param[in] user_data The user data to be passed to the callback function - * @return @c 0 on success, - * otherwise a negative error value - * @retval #AUDIO_IO_ERROR_NONE Successful - * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation - * - * @post audio_io_interrupted_cb() will be invoked. - * @see audio_out_unset_interrupted_cb() - * @see audio_io_interrupted_cb() - */ -int audio_out_set_interrupted_cb(audio_out_h output, audio_io_interrupted_cb callback, void *user_data); - -/** - * @deprecated Deprecated since 3.0 - * @brief Unregisters the callback function. - * - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @param[in] output The handle to the audio output - * @return @c 0 on success, - * otherwise a negative error value - * @retval #AUDIO_IO_ERROR_NONE Successful - * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation - * - * @see audio_out_set_interrupted_cb() - */ -int audio_out_unset_interrupted_cb(audio_out_h output); - -/** - * @deprecated Deprecated since 3.0 - * @brief Ignores session for output. - * - * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif - * - * @param[in] output The handle to the audio output - * @return @c 0 on success, - * otherwise a negative error value - * @retval #AUDIO_IO_ERROR_NONE Successful - * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter - * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation - */ -int audio_out_ignore_session(audio_out_h output); - -/** - * @brief Sets an asynchronous(event) callback function to handle playing PCM (pulse-code modulation) data. + * @brief Sets an asynchronous (event) callback function to handle playing PCM (pulse-code modulation) data. * * @details @a callback will be called when you can write a PCM data. * It might cause dead lock if change the state of audio handle in callback. - * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare) + * (ex: audio_out_destroy(), audio_out_prepare(), audio_out_unprepare()) * Recommend to use as a VOIP only. * Recommend not to hold callback too long.(it affects latency) * * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif * - * @remarks @a output must be created using audio_out_create(). + * @remarks @a output must be created using audio_out_create_new(). * * @param[in] output An audio output handle * @param[in] callback notify stream callback when user can write data (#audio_out_stream_cb) @@ -1072,7 +940,7 @@ int audio_out_ignore_session(audio_out_h output); * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error * - * @see audio_in_set_stream_cb() + * @see audio_out_unset_stream_cb() */ int audio_out_set_stream_cb(audio_out_h output, audio_out_stream_cb callback, void* user_data);