include/audio_io.h

   1 /*
   2  * Copyright (c) 2015 Samsung Electronics Co., Ltd All Rights Reserved
   3  *
   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
   7  *
   8  * http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 #ifndef __TIZEN_MEDIA_AUDIO_IO_H__
  18 #define __TIZEN_MEDIA_AUDIO_IO_H__
  19
  20 #include <sys/types.h>
  21 #include <tizen.h>
  22 #include <sound_manager.h>
  23
  24 #ifdef __cplusplus
  25 extern "C" {
  26 #endif
  27
  28 /**
  29  * @file audio_io.h
  30  * @brief This file contains the Audio Input and Audio Output API.
  31  */
  32
  33 /**
  34  * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
  35  * @{
  36  */
  37
  38 /**
  39  * @brief The audio input handle.
  40  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  41  */
  42 typedef struct audio_io_s *audio_in_h;
  43
  44 /**
  45  * @}
  46  */
  47
  48 /**
  49  * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
  50  * @{
  51  */
  52
  53 /**
  54  * @brief The audio output handle.
  55  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  56  */
  57 typedef struct audio_io_s *audio_out_h;
  58
  59  /**
  60  * @}
  61  */
  62
  63 /**
  64  * @addtogroup CAPI_MEDIA_AUDIO_IO_MODULE
  65  * @{
  66  */
  67
  68 /**
  69  * @brief Enumeration for audio sample type with bit depth.
  70  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  71  */
  72 typedef enum {
  73         AUDIO_SAMPLE_TYPE_U8 = 0x70,    /**< Unsigned 8-bit audio samples */
  74         AUDIO_SAMPLE_TYPE_S16_LE,       /**< Signed 16-bit audio samples */
  75 } audio_sample_type_e;
  76
  77 /**
  78  * @brief Enumeration for audio channel.
  79  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  80  */
  81 typedef enum {
  82         AUDIO_CHANNEL_MONO = 0x80,                  /**< 1 channel, mono */
  83         AUDIO_CHANNEL_STEREO,                       /**< 2 channel, stereo */
  84 } audio_channel_e;
  85
  86 /**
  87  * @brief Enumeration for audio input and output state.
  88  * @since_tizen 3.0
  89  */
  90 typedef enum {
  91         AUDIO_IO_STATE_IDLE,      /**< Audio-io handle is created, but not prepared */
  92         AUDIO_IO_STATE_RUNNING,   /**< Audio-io handle is ready and the stream is running */
  93         AUDIO_IO_STATE_PAUSED,    /**< Audio-io handle is ready and the stream is paused */
  94 } audio_io_state_e;
  95
  96 /**
  97  * @brief Enumeration for audio input and output error.
  98  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
  99  */
 100 typedef enum {
 101         AUDIO_IO_ERROR_NONE                = TIZEN_ERROR_NONE,              /**< Successful */
 102         AUDIO_IO_ERROR_OUT_OF_MEMORY       = TIZEN_ERROR_OUT_OF_MEMORY,     /**< Out of memory */
 103         AUDIO_IO_ERROR_INVALID_PARAMETER   = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
 104         AUDIO_IO_ERROR_INVALID_OPERATION   = TIZEN_ERROR_INVALID_OPERATION, /**< Invalid operation */
 105         AUDIO_IO_ERROR_PERMISSION_DENIED   = TIZEN_ERROR_PERMISSION_DENIED, /**< Device open error by security */
 106         AUDIO_IO_ERROR_NOT_SUPPORTED       = TIZEN_ERROR_NOT_SUPPORTED,     /**< Not supported */
 107         AUDIO_IO_ERROR_DEVICE_POLICY_RESTRICTION = TIZEN_ERROR_DEVICE_POLICY_RESTRICTION, /**< Device policy restriction (Since 3.0) */
 108         AUDIO_IO_ERROR_DEVICE_NOT_OPENED   = TIZEN_ERROR_AUDIO_IO | 0x01,   /**< Device open error */
 109         AUDIO_IO_ERROR_DEVICE_NOT_CLOSED   = TIZEN_ERROR_AUDIO_IO | 0x02,   /**< Device close error */
 110         AUDIO_IO_ERROR_INVALID_BUFFER      = TIZEN_ERROR_AUDIO_IO | 0x03,   /**< Invalid buffer pointer */
 111         AUDIO_IO_ERROR_SOUND_POLICY        = TIZEN_ERROR_AUDIO_IO | 0x04,   /**< Sound policy error */
 112         AUDIO_IO_ERROR_INVALID_STATE       = TIZEN_ERROR_AUDIO_IO | 0x05,   /**< Invalid state (Since 3.0) */
 113         AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE  = TIZEN_ERROR_AUDIO_IO | 0x06,   /**< Not supported stream type (Since 3.0) */
 114 } audio_io_error_e;
 115
 116 /**
 117  * @}
 118  */
 119
 120 /**
 121  * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
 122  * @{
 123  */
 124
 125 /**
 126  * @brief Called when audio input data is available in asynchronous(event) mode.
 127  *
 128  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 129  *
 130  * @remarks @a use audio_in_peek() to get audio in data inside callback, use audio_in_drop() after use of peeked data.
 131  *
 132  * @param[in] handle The handle to the audio input
 133  * @param[in] nbytes The amount of available audio in data which can be peeked.
 134  * @param[in] user_data The user data passed from the callback registration function
 135  *
 136  * @see audio_in_set_stream_cb()
 137  */
 138 typedef void (*audio_in_stream_cb)(audio_in_h handle, size_t nbytes, void *user_data);
 139
 140 /**
 141  * @brief Called when the state of audio input is changed.
 142  *
 143  * @since_tizen 3.0
 144  *
 145  * @param[in] handle The handle of the audio input
 146  * @param[in] previous The previous state of the audio input
 147  * @param[in] current The current state of the audio input
 148  * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
 149  * @param[in] user_data The user data passed from the callback registration function
 150  *
 151  * @see audio_in_set_state_changed_cb()
 152  * @see audio_in_unset_state_changed_cb()
 153  */
 154 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);
 155
 156 /**
 157  * @brief Creates an audio device instance and returns an input handle to record PCM (pulse-code modulation) data.
 158  *
 159  * @details This function is used for audio input initialization.
 160  *
 161  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 162  * @privlevel public
 163  * @privilege %http://tizen.org/privilege/recorder
 164  *
 165  * @remarks @a input must be released using audio_in_destroy().
 166  *
 167  * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
 168  * @param[in] channel The audio channel type (mono or stereo)
 169  * @param[in] type The type of audio sample (8- or 16-bit)
 170  * @param[out] input An audio input handle is created on success
 171  * @return @c 0 on success,
 172  *         otherwise a negative error value
 173  * @retval #AUDIO_IO_ERROR_NONE Successful
 174  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 175  * @retval #AUDIO_IO_ERROR_PERMISSION_DENIED Permission denied
 176  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 177  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 178  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 179  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 180  *
 181  * @post The state will be #AUDIO_IO_STATE_IDLE.\n
 182  *       audio_in_set_sound_stream_info() is recommended to be called after this API.
 183  * @see audio_in_destroy()
 184  */
 185 int audio_in_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_in_h *input);
 186
 187 /**
 188  * @brief Releases the audio input handle and all its resources associated with an audio stream.
 189  *
 190  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 191  *
 192  * @param[in] input The handle to the audio input to destroy
 193  * @return @c 0 on success,
 194  *         otherwise a negative error value
 195  * @retval #AUDIO_IO_ERROR_NONE Successful
 196  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 197  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
 198  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 199  *
 200  * @see audio_in_create()
 201  */
 202 int audio_in_destroy(audio_in_h input);
 203
 204 /**
 205  * @brief Sets the sound stream information to the audio input.
 206  *
 207  * @since_tizen 3.0
 208  *
 209  * @remarks @a the sound stream information includes audio routing and volume type.
 210  *          For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
 211  *          System, Alarm, Notification, Emergency, Voice Information, Ringtone VOIP and Ringtone Call stream types are not supported in this API.
 212  *
 213  * @param[in] input The handle to the audio input
 214  * @param[in] stream_info The handle of stream information
 215  * @return @c 0 on success,
 216  *         otherwise a negative error value
 217  * @retval #AUDIO_IO_ERROR_NONE Successful
 218  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 219  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 220  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 221  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
 222  *
 223  * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
 224  *      Call audio_in_create() before calling this function.
 225  * @post Call audio_in_prepare() after calling this function.
 226  * @see sound_manager_create_stream_information()
 227  * @see sound_manager_destroy_stream_information()
 228  */
 229 int audio_in_set_sound_stream_info(audio_in_h input, sound_stream_info_h stream_info);
 230
 231 /**
 232  * @brief Prepares the audio input for reading audio data by starting buffering of audio data from the device.
 233  *
 234  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 235  *
 236  * @param[in] input The handle to the audio input
 237  * @return @c 0 on success,
 238  *         otherwise a negative error value
 239  * @retval #AUDIO_IO_ERROR_NONE Successful
 240  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 241  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 242  * @retval #AUDIO_IO_ERROR_DEVICE_POLICY_RESTRICTION Device policy restriction
 243  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 244  *
 245  * @post The state will be #AUDIO_IO_STATE_RUNNING.
 246  * @see audio_in_unprepare()
 247  */
 248 int audio_in_prepare(audio_in_h input);
 249
 250 /**
 251  * @brief Unprepares the audio input.
 252  *
 253  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 254  *
 255  * @param[in] input The handle to the audio input
 256  * @return @c 0 on success,
 257  *         otherwise a negative error value
 258  * @retval #AUDIO_IO_ERROR_NONE Successful
 259  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 260  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 261  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 262  *
 263  * @post The state will be #AUDIO_IO_STATE_IDLE.
 264  * @see audio_in_prepare()
 265  */
 266 int audio_in_unprepare(audio_in_h input);
 267
 268 /**
 269  * @brief Pauses buffering of audio data from the device.
 270  *
 271  * @since_tizen 3.0
 272  *
 273  * @param[in] input The handle to the audio input
 274  * @return @c 0 on success,
 275  *         otherwise a negative error value
 276  * @retval #AUDIO_IO_ERROR_NONE Successful
 277  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 278  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 279  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 280  *
 281  * @pre The state should be #AUDIO_IO_STATE_RUNNING.
 282  * @post The state will be #AUDIO_IO_STATE_PAUSED.
 283  * @see audio_in_resume()
 284  */
 285 int audio_in_pause(audio_in_h input);
 286
 287 /**
 288  * @brief Resumes buffering audio data from the device.
 289  *
 290  * @since_tizen 3.0
 291  *
 292  * @param[in] input The handle to the audio input
 293  * @return @c 0 on success,
 294  *         otherwise a negative error value
 295  * @retval #AUDIO_IO_ERROR_NONE Successful
 296  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 297  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 298  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 299  *
 300  * @pre The state should be #AUDIO_IO_STATE_PAUSED.
 301  * @post The state will be #AUDIO_IO_STATE_RUNNING.
 302  * @see audio_in_pause()
 303  */
 304 int audio_in_resume(audio_in_h input);
 305
 306 /**
 307  * @brief Flushes and discards buffered audio data from the input stream.
 308  *
 309  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 310  *
 311  * @param[in] input The handle to the audio input
 312  * @return @c 0 on success,
 313  *         otherwise a negative error value
 314  * @retval #AUDIO_IO_ERROR_NONE Successful
 315  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 316  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 317  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 318  *
 319  * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
 320  */
 321 int audio_in_flush(audio_in_h input);
 322
 323 /**
 324  * @brief Reads audio data from the audio input buffer.
 325  *
 326  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 327  *
 328  * @param[in] input The handle to the audio input
 329  * @param[out] buffer The PCM buffer address
 330  * @param[in] length The length of the PCM data buffer (in bytes)
 331  * @return The number of read bytes on success,
 332  *         otherwise a negative error value
 333  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 334  * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
 335  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 336  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 337  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 338  *
 339  * @pre The state should be #AUDIO_IO_STATE_RUNNING.
 340  */
 341 int audio_in_read(audio_in_h input, void *buffer, unsigned int length);
 342
 343 /**
 344  * @brief Gets the size to be allocated for the audio input buffer.
 345  *
 346  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 347  *
 348  * @param[in] input The handle to the audio input
 349  * @param[out] size The buffer size (in bytes, the maximum size is 1 MB)
 350  * @return @c 0 on success,
 351  *         otherwise a negative error value
 352  * @retval #AUDIO_IO_ERROR_NONE Successful
 353  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 354  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 355  * @see audio_in_read()
 356  */
 357 int audio_in_get_buffer_size(audio_in_h input, int *size);
 358
 359 /**
 360  * @brief Gets the sample rate of the audio input data stream.
 361  *
 362  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 363  *
 364  * @param[in] input The handle to the audio input
 365  * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
 366  * @return @c 0 on success,
 367  *         otherwise a negative error value
 368  * @retval #AUDIO_IO_ERROR_NONE Successful
 369  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 370  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 371  */
 372 int audio_in_get_sample_rate(audio_in_h input, int *sample_rate);
 373
 374 /**
 375  * @brief Gets the channel type of the audio input data stream.
 376  *
 377  * @details The audio channel type defines whether the audio is mono or stereo.
 378  *
 379  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 380  *
 381  * @param[in] input The handle to the audio input
 382  * @param[out] channel The audio channel type
 383  * @return @c 0 on success,
 384  *         otherwise a negative error value
 385  * @retval #AUDIO_IO_ERROR_NONE Successful
 386  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 387  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 388  */
 389 int audio_in_get_channel(audio_in_h input, audio_channel_e *channel);
 390
 391 /**
 392  * @brief Gets the sample audio format (8-bit or 16-bit) of the audio input data stream.
 393  *
 394  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 395  *
 396  * @param[in] input The handle to the audio input
 397  * @param[out] type The audio sample type
 398  * @return @c 0 on success,
 399  *         otherwise a negative error value
 400  * @retval #AUDIO_IO_ERROR_NONE Successful
 401  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 402  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 403  */
 404 int audio_in_get_sample_type(audio_in_h input, audio_sample_type_e *type);
 405
 406 /**
 407  * @brief Sets an asynchronous(event) callback function to handle recording PCM (pulse-code modulation) data.
 408  *
 409  * @details @a callback will be called when you can read a PCM data.
 410  * It might cause dead lock if change the state of audio handle in callback.
 411  * (ex: audio_in_destroy, audio_in_prepare, audio_in_unprepare)
 412  * Recommend to use as a VOIP only.
 413  * Recommend not to hold callback too long.(it affects latency)
 414  *
 415  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 416  *
 417  * @remarks @a input must be created using audio_in_create().
 418  *
 419  * @param[in] input    An audio input handle
 420  * @param[in] callback notify stream callback when user can read data (#audio_in_stream_cb)
 421  * @param[in] user_data user data to be retrieved when callback is called
 422  * @return @c 0 on success,
 423  *         otherwise a negative error value
 424  * @retval #AUDIO_IO_ERROR_NONE Successful
 425  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 426  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 427  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 428  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 429  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 430  *
 431  * @see audio_in_unset_stream_cb()
 432  */
 433 int audio_in_set_stream_cb(audio_in_h input, audio_in_stream_cb callback, void* user_data);
 434
 435 /**
 436  * @brief Unregisters the callback function.
 437  *
 438  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 439  *
 440  * @param[in] input The handle to the audio input
 441  * @return @c 0 on success,
 442  *         otherwise a negative error value
 443  * @retval #AUDIO_IO_ERROR_NONE Successful
 444  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 445  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 446  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 447  *
 448  * @see audio_in_set_stream_cb()
 449  */
 450 int audio_in_unset_stream_cb(audio_in_h input);
 451
 452 /**
 453  * @brief peek from audio in buffer
 454  *
 455  * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
 456  *
 457  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 458  *
 459  * @remarks @a Works only in asynchronous(event) mode. This will just retrieve buffer pointer from audio in buffer. Drop after use.
 460  *
 461  * @param[in] input The handle to the audio input
 462  * @param[out] buffer start buffer pointer of peeked audio in data
 463  * @param[out] length amount of audio in data to be peeked
 464  * @return @c 0 on success,
 465  *         otherwise a negative error value
 466  * @retval #AUDIO_IO_ERROR_NONE Successful
 467  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 468  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 469  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 470  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 471  *
 472  * @pre The state should be #AUDIO_IO_STATE_RUNNING.
 473  * @see audio_in_drop()
 474  */
 475 int audio_in_peek(audio_in_h input, const void **buffer, unsigned int *length);
 476
 477 /**
 478  * @brief drop peeked audio buffer.
 479  *
 480  * @details This function works correctly only with read, write callback. Otherwise it won't operate as intended.
 481  *
 482  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 483  *
 484  * @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.
 485  *
 486  * @param[in] input The handle to the audio input
 487  * @return 0 on success, otherwise a negative error value
 488  * @retval #AUDIO_IO_ERROR_NONE Successful
 489  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 490  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 491  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 492  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 493  *
 494  * @pre The state should be #AUDIO_IO_STATE_RUNNING.
 495  * @see audio_in_peek()
 496  */
 497 int audio_in_drop(audio_in_h input);
 498
 499 /**
 500  * @brief Sets the state changed callback function to the audio input handle.
 501  *
 502  * @since_tizen 3.0
 503  *
 504  * @remarks @a input must be created using audio_in_create().
 505  *
 506  * @param[in] input    The audio input handle
 507  * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_in_state_changed_cb)
 508  * @param[in] user_data user data to be retrieved when callback is called
 509  * @return @c 0 on success,
 510  *         otherwise a negative error value
 511  * @retval #AUDIO_IO_ERROR_NONE Successful
 512  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 513  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 514  *
 515  * @see audio_in_unset_state_changed_cb()
 516  */
 517 int audio_in_set_state_changed_cb(audio_in_h input, audio_in_state_changed_cb callback, void* user_data);
 518
 519 /**
 520  * @brief Unregisters the state changed callback function of the audio input handle.
 521  *
 522  * @since_tizen 3.0
 523  *
 524  * @param[in] input The handle to the audio input
 525  * @return @c 0 on success,
 526  *         otherwise a negative error value
 527  * @retval #AUDIO_IO_ERROR_NONE Successful
 528  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 529  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 530  *
 531  * @see audio_in_set_state_changed_cb()
 532  */
 533 int audio_in_unset_state_changed_cb(audio_in_h input);
 534
 535 /**
 536  * @}
 537  */
 538
 539 /**
 540  * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
 541  * @{
 542  */
 543
 544 /**
 545  * @brief Called when audio out data can be written in asynchronous(event) mode.
 546  *
 547  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 548  *
 549  * @remarks @a use audio_out_write() to write pcm data inside this callback.
 550  * @param[in] handle The handle to the audio output
 551  * @param[in] nbytes The amount of audio in data which can be written.
 552  * @param[in] user_data The user data passed from the callback registration function
 553  *
 554  * @see audio_out_set_stream_cb()
 555  */
 556 typedef void (*audio_out_stream_cb)(audio_out_h handle, size_t nbytes, void *user_data);
 557
 558 /**
 559  * @brief Called when the state of audio output is changed.
 560  *
 561  * @since_tizen 3.0
 562  *
 563  * @param[in] handle The handle of the audio output
 564  * @param[in] previous The previous state of the audio output
 565  * @param[in] current The current state of the audio output
 566  * @param[in] by_policy @c true if the state is changed by policy, otherwise @c false if the state is not changed by policy
 567  * @param[in] user_data The user data passed from the callback registration function
 568  *
 569  * @see audio_out_set_state_changed_cb()
 570  * @see audio_out_unset_state_changed_cb()
 571  */
 572 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);
 573
 574 /**
 575  * @brief Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data.
 576  *
 577  * @details This function is used for audio output initialization.
 578  *
 579  * @since_tizen 3.0
 580  *
 581  * @remarks @a output must be released by audio_out_destroy().
 582  *          It is recommended to call audio_out_set_sound_stream_info() after this API.
 583  *
 584  * @param[in] sample_rate The audio sample rate in 8000[Hz] ~ 48000[Hz]
 585  * @param[in] channel The audio channel type (mono or stereo)
 586  * @param[in] type The type of audio sample (8-bit or 16-bit)
 587  * @param[out] output An audio output handle is created on success
 588  * @return @c 0 on success,
 589  *         otherwise a negative error value
 590  * @retval #AUDIO_IO_ERROR_NONE Successful
 591  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 592  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 593  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 594  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 595  *
 596  * @post The state will be #AUDIO_IO_STATE_IDLE.\n
 597  *       audio_out_set_sound_stream_info() is recommended to be called after this API.
 598  * @see audio_out_destroy()
 599  */
 600 int audio_out_create_new(int sample_rate, audio_channel_e channel, audio_sample_type_e type, audio_out_h *output);
 601
 602 /**
 603  * @brief Releases the audio output handle, along with all its resources.
 604  *
 605  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 606  *
 607  * @param[in] output The handle to the audio output to destroy
 608  * @return @c 0 on success,
 609  *         otherwise a negative error value
 610  * @retval #AUDIO_IO_ERROR_NONE Successful
 611  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 612  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 613  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
 614  *
 615  * @see audio_out_create_new()
 616  */
 617 int audio_out_destroy(audio_out_h output);
 618
 619 /**
 620  * @brief Sets the sound stream information to the audio output.
 621  *
 622  * @since_tizen 3.0
 623  *
 624  * @remarks @a the sound stream information includes audio routing and volume type.
 625  *          For more details, you can refer to @ref CAPI_MEDIA_SOUND_MANAGER_MODULE
 626  *          Voice Recognition and Loopback stream types are not supported in this API.
 627  *
 628  * @param[in] output The handle to the audio output
 629  * @param[in] stream_info The handle of stream information
 630  * @return @c 0 on success,
 631  *         otherwise a negative error value
 632  * @retval #AUDIO_IO_ERROR_NONE Successful
 633  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 634  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED Not supported
 635  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 636  * @retval #AUDIO_IO_ERROR_NOT_SUPPORTED_TYPE Not supported stream type
 637  *
 638  * @pre The state should be #AUDIO_IO_STATE_IDLE.\n
 639  *      Call audio_out_create_new() before calling this function.
 640  * @post Call audio_out_prepare() after calling this function.
 641  * @see sound_manager_create_stream_information()
 642  * @see sound_manager_destroy_stream_information()
 643  */
 644 int audio_out_set_sound_stream_info(audio_out_h output, sound_stream_info_h stream_info);
 645
 646 /**
 647  * @brief Prepares the audio output for playback, this must be called before audio_out_write().
 648  *
 649  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 650  *
 651  * @param[in] output The handle to the audio output
 652  * @return @c 0 on success,
 653  *         otherwise a negative error value
 654  * @retval #AUDIO_IO_ERROR_NONE Successful
 655  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 656  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 657  *
 658  * @post The state will be #AUDIO_IO_STATE_RUNNING.
 659  * @see audio_out_unprepare()
 660  */
 661 int audio_out_prepare(audio_out_h output);
 662
 663 /**
 664  * @brief Unprepares the audio output.
 665  *
 666  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 667  *
 668  * @param[in] output The handle to the audio output
 669  * @return @c 0 on success,
 670  *         otherwise a negative error value
 671  * @retval #AUDIO_IO_ERROR_NONE Successful
 672  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 673  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 674  *
 675  * @post The state will be #AUDIO_IO_STATE_IDLE.
 676  * @see audio_out_prepare()
 677  */
 678 int audio_out_unprepare(audio_out_h output);
 679
 680 /**
 681  * @brief Pauses feeding of audio data to the device.
 682  *
 683  * @since_tizen 3.0
 684  *
 685  * @param[in] output The handle to the audio output
 686  * @return @c 0 on success,
 687  *         otherwise a negative error value
 688  * @retval #AUDIO_IO_ERROR_NONE Successful
 689  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 690  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 691  *
 692  * @pre The state should be #AUDIO_IO_STATE_RUNNING.
 693  * @post The state will be #AUDIO_IO_STATE_PAUSED.
 694  * @see audio_out_resume()
 695  */
 696 int audio_out_pause(audio_out_h output);
 697
 698 /**
 699  * @brief Resumes feeding of audio data to the device.
 700  *
 701  * @since_tizen 3.0
 702  *
 703  * @param[in] output The handle to the audio output
 704  * @return @c 0 on success,
 705  *         otherwise a negative error value
 706  * @retval #AUDIO_IO_ERROR_NONE Successful
 707  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 708  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 709  *
 710  * @pre The state should be #AUDIO_IO_STATE_PAUSED.
 711  * @post The state will be #AUDIO_IO_STATE_RUNNING.
 712  * @see audio_out_pause()
 713  */
 714 int audio_out_resume(audio_out_h output);
 715
 716 /**
 717  * @brief Drains buffered audio data from the output stream.
 718  *
 719  * @details This function waits until drains stream buffer completely. (e.g end of playback)
 720  *
 721  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 722  *
 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
 729  *
 730  * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
 731  * @see audio_out_flush()
 732  */
 733 int audio_out_drain(audio_out_h output);
 734
 735 /**
 736  * @brief Flushes and discards buffered audio data from the output stream.
 737  *
 738  * @since_tizen @if MOBILE 2.4 @elseif WEARABLE 3.0 @endif
 739  *
 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
 746  *
 747  * @pre The state should be #AUDIO_IO_STATE_RUNNING or #AUDIO_IO_STATE_PAUSED.
 748  * @see audio_out_drain()
 749  */
 750 int audio_out_flush(audio_out_h output);
 751
 752 /**
 753  * @brief Starts writing the audio data to the device.
 754  *
 755  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 756  *
 757  * @param[in] output The handle to the audio output
 758  * @param[in,out] buffer The PCM buffer address
 759  * @param[in] length The length of the PCM buffer (in bytes)
 760  * @return The written data size on success,
 761  *         otherwise a negative error value
 762  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 763  * @retval #AUDIO_IO_ERROR_INVALID_BUFFER Invalid buffer pointer
 764  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 765  * @retval #AUDIO_IO_ERROR_INVALID_STATE Invalid state
 766  *
 767  * @pre The state should be #AUDIO_IO_STATE_RUNNING.
 768  */
 769 int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
 770
 771 /**
 772  * @brief Gets the size to be allocated for the audio output buffer.
 773  *
 774  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 775  *
 776  * @param[in] output The handle to the audio output
 777  * @param[out] size The suggested buffer size (in bytes, the maximum size is 1 MB)
 778  * @return  @c 0 on success,
 779  *          otherwise a negative error value
 780  * @retval  #AUDIO_IO_ERROR_NONE Successful
 781  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 782  *
 783  * @see audio_out_write()
 784  */
 785 int audio_out_get_buffer_size(audio_out_h output, int *size);
 786
 787 /**
 788  * @brief Gets the sample rate of the audio output data stream.
 789  *
 790  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 791  *
 792  * @param[in] output The handle to the audio output
 793  * @param[out] sample_rate The audio sample rate in Hertz (8000 ~ 48000)
 794  * @return  @c 0 on success,
 795  *          otherwise a negative error value
 796  * @retval  #AUDIO_IO_ERROR_NONE Successful
 797  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 798  */
 799 int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
 800
 801 /**
 802  * @brief Gets the channel type of the audio output data stream.
 803  *
 804  * @details The audio channel type defines whether the audio is mono or stereo.
 805  *
 806  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 807  *
 808  * @param[in] output The handle to the audio output
 809  * @param[out] channel The audio channel type
 810  * @return @c 0 on success,
 811  *         otherwise a negative error value
 812  * @retval #AUDIO_IO_ERROR_NONE Successful
 813  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 814  */
 815 int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
 816
 817 /**
 818  * @brief Gets the sample audio format (8-bit or 16-bit) of the audio output data stream.
 819  *
 820  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 821  *
 822  * @param[in] output The handle to the audio output
 823  * @param[out] type The audio sample type
 824  * @return @c 0 on success,
 825  *         otherwise a negative error value
 826  * @retval #AUDIO_IO_ERROR_NONE Successful
 827  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 828  */
 829 int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
 830
 831 /**
 832  * @brief Gets the sound type supported by the audio output device.
 833  *
 834  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 835  *
 836  * @param[in] output The handle to the audio output
 837  * @param[out] type The sound type
 838  * @return @c 0 on success,
 839  *         otherwise a negative error value
 840  * @retval #AUDIO_IO_ERROR_NONE Successful
 841  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 842  */
 843 int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
 844
 845 /**
 846  * @brief Sets an asynchronous(event) callback function to handle playing PCM (pulse-code modulation) data.
 847  *
 848  * @details @a callback will be called when you can write a PCM data.
 849  * It might cause dead lock if change the state of audio handle in callback.
 850  * (ex: audio_out_destroy, audio_out_prepare, audio_out_unprepare)
 851  * Recommend to use as a VOIP only.
 852  * Recommend not to hold callback too long.(it affects latency)
 853  *
 854  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 855  *
 856  * @remarks @a output must be created using audio_out_create_new().
 857  *
 858  * @param[in] output   An audio output handle
 859  * @param[in] callback notify stream callback when user can write data (#audio_out_stream_cb)
 860  * @param[in] user_data user data to be retrieved when callback is called
 861  * @return 0 on success, otherwise a negative error value
 862  * @retval #AUDIO_IO_ERROR_NONE Successful
 863  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 864  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 865  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 866  * @retval #AUDIO_IO_ERROR_SOUND_POLICY Sound policy error
 867  *
 868  * @see audio_out_unset_stream_cb()
 869  */
 870 int audio_out_set_stream_cb(audio_out_h output, audio_out_stream_cb callback, void* user_data);
 871
 872 /**
 873  * @brief Unregisters the callback function.
 874  *
 875  * @since_tizen @if MOBILE 2.3 @elseif WEARABLE 2.3.1 @endif
 876  *
 877  * @param[in] output The handle to the audio output
 878  * @return 0 on success, otherwise a negative error value
 879  * @retval #AUDIO_IO_ERROR_NONE Successful
 880  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 881  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 882  *
 883  * @see audio_out_set_stream_cb()
 884  */
 885 int audio_out_unset_stream_cb(audio_out_h output);
 886
 887 /**
 888  * @brief Sets the state changed callback function to the audio output handle.
 889  *
 890  * @since_tizen 3.0
 891  *
 892  * @remarks @a input must be created using audio_out_create_new().
 893  *
 894  * @param[in] output    The audio output handle
 895  * @param[in] callback the state changed callback called when the state of the handle is changed (#audio_out_state_changed_cb)
 896  * @param[in] user_data user data to be retrieved when callback is called
 897  * @return @c 0 on success,
 898  *         otherwise a negative error value
 899  * @retval #AUDIO_IO_ERROR_NONE Successful
 900  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 901  *
 902  * @see audio_out_unset_state_changed_cb()
 903  */
 904 int audio_out_set_state_changed_cb(audio_out_h output, audio_out_state_changed_cb callback, void* user_data);
 905
 906 /**
 907  * @brief Unregisters the state changed callback function of the audio output handle.
 908  *
 909  * @since_tizen 3.0
 910  *
 911  * @param[in] output The handle to the audio output
 912  * @return @c 0 on success,
 913  *         otherwise a negative error value
 914  * @retval #AUDIO_IO_ERROR_NONE Successful
 915  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 916  *
 917  * @see audio_out_set_state_changed_cb()
 918  */
 919 int audio_out_unset_state_changed_cb(audio_out_h output);
 920
 921 /**
 922  * @}
 923  */
 924
 925 #ifdef __cplusplus
 926 }
 927 #endif
 928
 929 #endif /* __TIZEN_MEDIA_AUDIO_IO_H__ */