include/audio_io.h

   1 /*
   2 * Copyright (c) 2011 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 <tizen.h>
  21 #include <sound_manager.h>
  22
  23 #ifdef __cplusplus
  24 extern "C"
  25 {
  26 #endif
  27
  28 #define AUDIO_IO_ERROR_CLASS          TIZEN_ERROR_MULTIMEDIA_CLASS | 0x40
  29
  30 /**
  31  * @file audio_io.h
  32  * @brief This file contains the Audio Input and Output API.
  33  */
  34
  35 /**
  36  * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
  37  * @{
  38 */
  39
  40 /**
  41  * @brief Audio input handle type.
  42  */
  43 typedef struct audio_in_s *audio_in_h;
  44
  45 /**
  46  * @}
  47 */
  48
  49 /**
  50  * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
  51  * @{
  52  */
  53
  54 /**
  55  * @brief Audio output handle type.
  56  */
  57 typedef struct audio_out_s *audio_out_h;
  58
  59  /**
  60  * @}
  61  */
  62
  63 /**
  64  * @addtogroup CAPI_MEDIA_AUDIO_IO_MODULE
  65  * @{
  66  */
  67
  68 /**
  69  * @brief Enumerations of audio sample type with bit depth
  70  */
  71 typedef enum
  72 {
  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 Enumerations of audio channel
  79  */
  80 typedef enum {
  81     AUDIO_CHANNEL_MONO = 0x80,    /**< 1 channel, mono */
  82     AUDIO_CHANNEL_STEREO,      /**< 2 channel, stereo */
  83 } audio_channel_e;
  84
  85 /**
  86  * @brief Enumerations of audio input and output error code
  87  */
  88 typedef enum{
  89     AUDIO_IO_ERROR_NONE                = TIZEN_ERROR_NONE,                /**<Successful */
  90     AUDIO_IO_ERROR_OUT_OF_MEMORY       = TIZEN_ERROR_OUT_OF_MEMORY,     /**< Out of memory */
  91     AUDIO_IO_ERROR_INVALID_PARAMETER   = TIZEN_ERROR_INVALID_PARAMETER, /**< Invalid parameter */
  92     AUDIO_IO_ERROR_INVALID_OPERATION   = TIZEN_ERROR_INVALID_OPERATION, /**< Invalid operation */
  93     AUDIO_IO_ERROR_DEVICE_NOT_OPENED   = AUDIO_IO_ERROR_CLASS | 0x01, /**< Device open error */
  94     AUDIO_IO_ERROR_DEVICE_NOT_CLOSED   = AUDIO_IO_ERROR_CLASS | 0x02, /**< Device close error */
  95     AUDIO_IO_ERROR_INVALID_BUFFER      = AUDIO_IO_ERROR_CLASS | 0x03, /**< Invalid buffer pointer */
  96     AUDIO_IO_ERROR_SOUND_POLICY        = AUDIO_IO_ERROR_CLASS | 0x04, /**< Sound policy error */
  97 } audio_io_error_e;
  98
  99 /**
 100  * @brief Enumerations of audio io interrupted type
 101  */
 102 typedef enum
 103 {
 104     AUDIO_IO_INTERRUPTED_COMPLETED = 0,                                 /**< Interrupt completed*/
 105     AUDIO_IO_INTERRUPTED_BY_MEDIA,                              /**< Interrupted by non-resumable media application*/
 106     AUDIO_IO_INTERRUPTED_BY_CALL,                                               /**< Interrupted by incoming call*/
 107     AUDIO_IO_INTERRUPTED_BY_EARJACK_UNPLUG,                     /**< Interrupted by unplugging headphone*/
 108     AUDIO_IO_INTERRUPTED_BY_RESOURCE_CONFLICT,          /**< Interrupted by resource conflict*/
 109     AUDIO_IO_INTERRUPTED_BY_ALARM,                                      /**< Interrupted by alarm*/
 110     AUDIO_IO_INTERRUPTED_BY_EMERGENCY,                                  /**< Interrupted by emergency*/
 111     AUDIO_IO_INTERRUPTED_BY_RESUMABLE_MEDIA,                            /**< Interrupted by resumable media application*/
 112 } audio_io_interrupted_code_e;
 113
 114 /**
 115  * @brief  Called when the audio input or output is interrupted.
 116  * @param[in]   error_code      The interrupted error code
 117  * @param[in]   user_data       The user data passed from the callback registration function
 118  * @see audio_in_set_interrupted_cb()
 119  * @see audio_out_set_interrupted_cb()
 120  * @see audio_in_unset_interrupted_cb()
 121  * @see audio_out_unset_interrupted_cb()
 122  */
 123 typedef void (*audio_io_interrupted_cb)(audio_io_interrupted_code_e code, void *user_data);
 124
 125 /**
 126  * @}
 127 */
 128
 129 /**
 130  * @addtogroup CAPI_MEDIA_AUDIO_IN_MODULE
 131  * @{
 132 */
 133
 134
 135 //
 136 //AUDIO INPUT
 137 //
 138
 139
 140 /**
 141  * @brief    Creates an audio device instance and returns an input handle to record PCM (pulse-code modulation) data
 142  * @details  This function is used for audio input initialization.
 143  *
 144  * @remarks @a input must be release audio_in_destroy() by you.
 145  *
 146  * @param[in]  sample_rate      The audio sample rate in 8000[Hz] ~ 48000[Hz]
 147  * @param[in]  channel  The audio channel type, mono, or stereo
 148  * @param[in]  type     The type of audio sample (8- or 16-bit)
 149  * @param[out] input    An audio input handle will be created, if successful
 150  *
 151  * @return 0 on success, otherwise a negative error value.
 152  * @retval #AUDIO_IO_ERROR_NONE Successful
 153  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 154  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 155  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 156  * @retval #AUDIO_IO_ERROR_SOUND_POLICY    Sound policy error
 157  * @see audio_in_destroy()
 158  */
 159 int audio_in_create(int sample_rate, audio_channel_e channel, audio_sample_type_e type , audio_in_h *input);
 160
 161
 162
 163 /**
 164  * @brief    Releases the audio input handle and all its resources associated with an audio stream
 165  *
 166  * @param[in]   input   The handle to the audio input to destroy
 167  *
 168  * @return 0 on success, otherwise a negative error value.
 169  * @retval #AUDIO_IO_ERROR_NONE Successful
 170  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 171  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
 172  * @see audio_in_create()
 173  */
 174 int audio_in_destroy(audio_in_h input);
 175
 176
 177
 178 /**
 179  * @brief   Prepare reading audio in by starting buffering the audio data from the device
 180  * @param[in]   input   The handle to the audio input
 181  * @return 0 on success, otherwise a negative error value.
 182  * @retval #AUDIO_IO_ERROR_NONE Successful
 183  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 184  * @see audio_in_unprepare()
 185  */
 186 int audio_in_prepare(audio_in_h input);
 187
 188
 189
 190 /**
 191  * @brief    Unprepare reading audio in by stopping buffering the audio data from the device
 192  * @param[in]   input   The handle to the audio input
 193  * @return 0 on success, otherwise a negative error value.
 194  * @retval #AUDIO_IO_ERROR_NONE Successful
 195  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 196  * @see audio_in_prepare()
 197  */
 198 int audio_in_unprepare(audio_in_h input);
 199
 200
 201
 202 /**
 203  * @brief   Reads audio data from the audio input buffer
 204  *
 205  * @param[in]   input   The handle to the audio input
 206  * @param[out]  buffer  The PCM buffer address
 207  * @param[in]   length  The length of PCM data buffer (in bytes)
 208  *
 209  * @return  Number of read bytes on success, otherwise a negative error value.
 210  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 211  * @retval  #AUDIO_IO_ERROR_INVALID_BUFFER  Invalid buffer pointer
 212  * @retval  #AUDIO_IO_ERROR_SOUND_POLICY    Sound policy error
 213  * @retval  #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 214  * @pre audio_in_start_recording()
 215 */
 216 int audio_in_read(audio_in_h input, void *buffer, unsigned int length);
 217
 218
 219
 220 /**
 221  * @brief    Gets the size to be allocated for audio input buffer
 222  * @param[in]   input   The handle to the audio input
 223  * @param[out]  size    The buffer size (in bytes). \n The maximum size is 1 MB.
 224  *
 225  * @return  0 on success, otherwise a negative error value.
 226  * @retval  #AUDIO_IO_ERROR_NONE Successful
 227  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 228  * @see audio_in_read()
 229 */
 230 int audio_in_get_buffer_size(audio_in_h input, int *size);
 231
 232
 233
 234 /**
 235  * @brief    Gets the sample rate of the audio input data stream
 236  *
 237  * @param[in]   input   The handle to the audio input
 238  * @param[out]  sample_rate  The audio sample rate in Hertz (8000 ~ 48000)
 239  *
 240  * @return  0 on success, otherwise a negative error value.
 241  * @retval  #AUDIO_IO_ERROR_NONE Successful
 242  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 243 */
 244 int audio_in_get_sample_rate(audio_in_h input, int *sample_rate);
 245
 246
 247
 248 /**
 249  * @brief    Gets the channel type of audio input data stream
 250  *
 251  * @details  The audio channel type defines whether the audio is mono or stereo.
 252  *
 253  * @param[in]   input   The handle to the audio input
 254  * @param[out]  channel The audio channel type
 255  *
 256  * @return 0 on success, otherwise a negative error value.
 257  * @retval #AUDIO_IO_ERROR_NONE Successful
 258  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 259 */
 260 int audio_in_get_channel(audio_in_h input, audio_channel_e *channel);
 261
 262
 263
 264 /**
 265  * @brief    Gets the sample audio format (8-bit or 16-bit) of audio input data stream
 266  *
 267  * @param[in]  input    The handle to the audio input
 268  * @param[out] type     The audio sample type
 269  *
 270  * @return 0 on success, otherwise a negative error value.
 271  * @retval #AUDIO_IO_ERROR_NONE Successful
 272  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 273 */
 274 int audio_in_get_sample_type(audio_in_h input, audio_sample_type_e *type);
 275
 276
 277 /**
 278  * @brief Registers a callback function to be invoked when the audio input handle is interrupted or interrupt completed.
 279  * @param[in] input    The handle to the audio input
 280  * @param[in] callback  The callback function to register
 281  * @param[in] user_data The user data to be passed to the callback function
 282  * @return 0 on success, 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_INVALID_OPERATION Invalid operation
 286  * @post  audio_io_interrupted_cb() will be invoked
 287  * @see audio_in_unset_interrupted_cb()
 288  * @see audio_io_interrupted_cb()
 289  */
 290 int audio_in_set_interrupted_cb(audio_in_h input, audio_io_interrupted_cb callback, void *user_data);
 291
 292 /**
 293  * @brief Unregisters the callback function.
 294  * @param[in]  output   The handle to the audio output
 295  * @return 0 on success, otherwise a negative error value.
 296  * @retval #AUDIO_IO_ERROR_NONE Successful
 297  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 298  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 299  * @see audio_in_set_interrupted_cb()
 300  */
 301 int audio_in_unset_interrupted_cb(audio_in_h input);
 302
 303
 304
 305 //
 306 //  AUDIO OUTPUT
 307 //
 308
 309 /**
 310  * @}
 311 */
 312
 313 /**
 314  * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
 315  * @{
 316  */
 317
 318 /**
 319  * @brief    Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data
 320  * @details  This function is used for audio output initialization.
 321  * @remarks @a output must be released audio_out_destroy() by you.
 322  *
 323  * @param[in]  sample_rate  The audio sample rate in 8000[Hz] ~ 48000[Hz]
 324  * @param[in]  channel      The audio channel type, mono, or stereo
 325  * @param[in]  type         The type of audio sample (8- or 16-bit)
 326  * @param[in]  sound_type   The type of sound (#sound_type_e)
 327  * @param[out] output       An audio output handle will be created, if successful
 328  *
 329  * @return 0 on success, otherwise a negative error value.
 330  * @retval #AUDIO_IO_ERROR_NONE Successful
 331  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 332  * @retval #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 333  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 334  * @retval #AUDIO_IO_ERROR_SOUND_POLICY    Sound policy error
 335  *
 336  * @see audio_out_destroy()
 337 */
 338 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);
 339
 340
 341
 342 /**
 343  * @brief    Releases the audio output handle, along with all its resources
 344  *
 345  * @param[in]   output The handle to the audio output to destroy
 346  *
 347  * @return  0 on success, otherwise a negative error value.
 348  * @retval  #AUDIO_IO_ERROR_NONE Successful
 349  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 350  * @retval  #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 351  * @retval  #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
 352  *
 353  * @see audio_out_create()
 354 */
 355 int audio_out_destroy(audio_out_h output);
 356
 357 /**
 358  * @brief   Prepare playing audio out, this must be called before audio_out_write()
 359  * @param[in]   input   The handle to the audio output
 360  * @return 0 on success, otherwise a negative error value.
 361  * @retval #AUDIO_IO_ERROR_NONE Successful
 362  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 363  * @see audio_out_unprepare()
 364  */
 365 int audio_out_prepare(audio_out_h output);
 366
 367
 368
 369 /**
 370  * @brief    Unprepare playing audio out.
 371  * @param[in]   input   The handle to the audio output
 372  * @return 0 on success, otherwise a negative error value.
 373  * @retval #AUDIO_IO_ERROR_NONE Successful
 374  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 375  * @see audio_out_prepare()
 376  */
 377 int audio_out_unprepare(audio_out_h output);
 378
 379
 380
 381
 382 /**
 383  * @brief    Starts writing the audio data to the device
 384  *
 385  * @param[in]       output  The handle to the audio output
 386  * @param[in,out]   buffer  The PCM buffer address
 387  * @param[in]       length  The length of PCM buffer (in bytes)
 388  *
 389  * @return  Written data size on success, otherwise a negative error value.
 390  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 391  * @retval  #AUDIO_IO_ERROR_INVALID_BUFFER  Invalid buffer pointer
 392  * @retval  #AUDIO_IO_ERROR_SOUND_POLICY    Sound policy error
 393 */
 394 int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
 395
 396
 397
 398 /**
 399  * @brief    Gets the size to be allocated for audio output buffer
 400  * @param[in]     output  The handle to the audio output
 401  * @param[out]    size    The suggested buffer size (in bytes). \n The maximum size is 1 MB.
 402  *
 403  * @return  0 on success, otherwise a negative error value.
 404  * @retval  #AUDIO_IO_ERROR_NONE Successful
 405  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 406  * @see audio_out_write()
 407  *
 408 */
 409 int audio_out_get_buffer_size(audio_out_h output, int *size);
 410
 411
 412
 413 /**
 414  * @brief    Gets the sample rate of audio output data stream
 415  *
 416  * @param[in]   output       The handle to the audio output
 417  * @param[out]  sample_rate  The audio sample rate in Hertz (8000 ~ 48000)
 418  *
 419  * @return  0 on success, otherwise a negative error value.
 420  * @retval  #AUDIO_IO_ERROR_NONE Successful
 421  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 422 */
 423 int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
 424
 425
 426
 427 /**
 428  * @brief    Gets the channel type of audio output data stream
 429  *
 430  * @details  The audio channel type defines whether the audio is mono or stereo.
 431  *
 432  * @param[in]   output  The handle to the audio output
 433  * @param[out]  channel The audio channel type
 434  *
 435  * @return 0 on success, otherwise a negative error value.
 436  * @retval #AUDIO_IO_ERROR_NONE Successful
 437  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 438 */
 439 int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
 440
 441
 442
 443 /**
 444  * @brief    Gets the sample audio format (8-bit or 16-bit) of audio output data stream
 445  *
 446  * @param[in]   output  The handle to the audio output
 447  * @param[out]  type    The audio sample type
 448  * @return 0 on success, otherwise a negative error value.
 449  * @retval #AUDIO_IO_ERROR_NONE Successful
 450  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 451 */
 452 int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
 453
 454
 455
 456 /**
 457  * @brief    Gets the sound type supported by the audio output device
 458  * @param[in]  output   The handle to the audio output
 459  * @param[out] type     The sound type
 460  *
 461  * @return 0 on success, otherwise a negative error value.
 462  * @retval #AUDIO_IO_ERROR_NONE Successful
 463  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 464 */
 465 int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
 466
 467
 468 /**
 469  * @brief Registers a callback function to be invoked when the audio out handle is interrupted or interrupt completed.
 470  * @param[in] output   The handle to the audio output
 471  * @param[in] callback  The callback function to register
 472  * @param[in] user_data The user data to be passed to the callback function
 473  * @return 0 on success, otherwise a negative error value.
 474  * @retval #AUDIO_IO_ERROR_NONE Successful
 475  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 476  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 477  * @post  audio_io_interrupted_cb() will be invoked
 478  * @see audio_out_unset_interrupted_cb()
 479  * @see audio_io_interrupted_cb()
 480  */
 481 int audio_out_set_interrupted_cb(audio_out_h output, audio_io_interrupted_cb callback, void *user_data);
 482
 483 /**
 484  * @brief Unregisters the callback function.
 485  * @param[in]  output   The handle to the audio output
 486  * @return 0 on success, otherwise a negative error value.
 487  * @retval #AUDIO_IO_ERROR_NONE Successful
 488  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 489  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 490  * @see audio_out_set_interrupted_cb()
 491  */
 492 int audio_out_unset_interrupted_cb(audio_out_h output);
 493
 494
 495
 496 /**
 497  * @}
 498 */
 499
 500 #ifdef __cplusplus
 501 }
 502 #endif
 503
 504 #endif /* __TIZEN_MEDIA_AUDIO_IO_H__ */