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]  input   The handle to the audio input
 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  * @brief Ignore session for input
 305  * @param[in]  input   The handle to the audio input
 306  * @return 0 on success, otherwise a negative error value.
 307  * @retval #AUDIO_IO_ERROR_NONE Successful
 308  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 309  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 310  * @see
 311  */
 312 int audio_in_ignore_session(audio_in_h input);
 313
 314 //
 315 //  AUDIO OUTPUT
 316 //
 317
 318 /**
 319  * @}
 320 */
 321
 322 /**
 323  * @addtogroup CAPI_MEDIA_AUDIO_OUT_MODULE
 324  * @{
 325  */
 326
 327 /**
 328  * @brief    Creates an audio device instance and returns an output handle to play PCM (pulse-code modulation) data
 329  * @details  This function is used for audio output initialization.
 330  * @remarks @a output must be released audio_out_destroy() by you.
 331  *
 332  * @param[in]  sample_rate  The audio sample rate in 8000[Hz] ~ 48000[Hz]
 333  * @param[in]  channel      The audio channel type, mono, or stereo
 334  * @param[in]  type         The type of audio sample (8- or 16-bit)
 335  * @param[in]  sound_type   The type of sound (#sound_type_e)
 336  * @param[out] output       An audio output handle will be created, if successful
 337  *
 338  * @return 0 on success, 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_OUT_OF_MEMORY Out of memory
 342  * @retval #AUDIO_IO_ERROR_DEVICE_NOT_OPENED Device not opened
 343  * @retval #AUDIO_IO_ERROR_SOUND_POLICY    Sound policy error
 344  *
 345  * @see audio_out_destroy()
 346 */
 347 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);
 348
 349
 350
 351 /**
 352  * @brief    Releases the audio output handle, along with all its resources
 353  *
 354  * @param[in]   output The handle to the audio output to destroy
 355  *
 356  * @return  0 on success, otherwise a negative error value.
 357  * @retval  #AUDIO_IO_ERROR_NONE Successful
 358  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 359  * @retval  #AUDIO_IO_ERROR_OUT_OF_MEMORY Out of memory
 360  * @retval  #AUDIO_IO_ERROR_DEVICE_NOT_CLOSED Device not closed
 361  *
 362  * @see audio_out_create()
 363 */
 364 int audio_out_destroy(audio_out_h output);
 365
 366 /**
 367  * @brief   Prepare playing audio out, this must be called before audio_out_write()
 368  * @param[in]   output  The handle to the audio output
 369  * @return 0 on success, otherwise a negative error value.
 370  * @retval #AUDIO_IO_ERROR_NONE Successful
 371  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 372  * @see audio_out_unprepare()
 373  */
 374 int audio_out_prepare(audio_out_h output);
 375
 376
 377
 378 /**
 379  * @brief    Unprepare playing audio out.
 380  * @param[in]   output  The handle to the audio output
 381  * @return 0 on success, otherwise a negative error value.
 382  * @retval #AUDIO_IO_ERROR_NONE Successful
 383  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 384  * @see audio_out_prepare()
 385  */
 386 int audio_out_unprepare(audio_out_h output);
 387
 388
 389
 390
 391 /**
 392  * @brief    Starts writing the audio data to the device
 393  *
 394  * @param[in]       output  The handle to the audio output
 395  * @param[in,out]   buffer  The PCM buffer address
 396  * @param[in]       length  The length of PCM buffer (in bytes)
 397  *
 398  * @return  Written data size on success, otherwise a negative error value.
 399  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 400  * @retval  #AUDIO_IO_ERROR_INVALID_BUFFER  Invalid buffer pointer
 401  * @retval  #AUDIO_IO_ERROR_SOUND_POLICY    Sound policy error
 402 */
 403 int audio_out_write(audio_out_h output, void *buffer, unsigned int length);
 404
 405
 406
 407 /**
 408  * @brief    Gets the size to be allocated for audio output buffer
 409  * @param[in]     output  The handle to the audio output
 410  * @param[out]    size    The suggested buffer size (in bytes). \n The maximum size is 1 MB.
 411  *
 412  * @return  0 on success, otherwise a negative error value.
 413  * @retval  #AUDIO_IO_ERROR_NONE Successful
 414  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 415  * @see audio_out_write()
 416  *
 417 */
 418 int audio_out_get_buffer_size(audio_out_h output, int *size);
 419
 420
 421
 422 /**
 423  * @brief    Gets the sample rate of audio output data stream
 424  *
 425  * @param[in]   output       The handle to the audio output
 426  * @param[out]  sample_rate  The audio sample rate in Hertz (8000 ~ 48000)
 427  *
 428  * @return  0 on success, otherwise a negative error value.
 429  * @retval  #AUDIO_IO_ERROR_NONE Successful
 430  * @retval  #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 431 */
 432 int audio_out_get_sample_rate(audio_out_h output, int *sample_rate);
 433
 434
 435
 436 /**
 437  * @brief    Gets the channel type of audio output data stream
 438  *
 439  * @details  The audio channel type defines whether the audio is mono or stereo.
 440  *
 441  * @param[in]   output  The handle to the audio output
 442  * @param[out]  channel The audio channel type
 443  *
 444  * @return 0 on success, otherwise a negative error value.
 445  * @retval #AUDIO_IO_ERROR_NONE Successful
 446  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 447 */
 448 int audio_out_get_channel(audio_out_h output, audio_channel_e *channel);
 449
 450
 451
 452 /**
 453  * @brief    Gets the sample audio format (8-bit or 16-bit) of audio output data stream
 454  *
 455  * @param[in]   output  The handle to the audio output
 456  * @param[out]  type    The audio sample type
 457  * @return 0 on success, otherwise a negative error value.
 458  * @retval #AUDIO_IO_ERROR_NONE Successful
 459  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 460 */
 461 int audio_out_get_sample_type(audio_out_h output, audio_sample_type_e *type);
 462
 463
 464
 465 /**
 466  * @brief    Gets the sound type supported by the audio output device
 467  * @param[in]  output   The handle to the audio output
 468  * @param[out] type     The sound type
 469  *
 470  * @return 0 on success, otherwise a negative error value.
 471  * @retval #AUDIO_IO_ERROR_NONE Successful
 472  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 473 */
 474 int audio_out_get_sound_type(audio_out_h output, sound_type_e *type);
 475
 476
 477 /**
 478  * @brief Registers a callback function to be invoked when the audio out handle is interrupted or interrupt completed.
 479  * @param[in] output   The handle to the audio output
 480  * @param[in] callback  The callback function to register
 481  * @param[in] user_data The user data to be passed to the callback function
 482  * @return 0 on success, otherwise a negative error value.
 483  * @retval #AUDIO_IO_ERROR_NONE Successful
 484  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 485  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 486  * @post  audio_io_interrupted_cb() will be invoked
 487  * @see audio_out_unset_interrupted_cb()
 488  * @see audio_io_interrupted_cb()
 489  */
 490 int audio_out_set_interrupted_cb(audio_out_h output, audio_io_interrupted_cb callback, void *user_data);
 491
 492 /**
 493  * @brief Unregisters the callback function.
 494  * @param[in]  output   The handle to the audio output
 495  * @return 0 on success, otherwise a negative error value.
 496  * @retval #AUDIO_IO_ERROR_NONE Successful
 497  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 498  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 499  * @see audio_out_set_interrupted_cb()
 500  */
 501 int audio_out_unset_interrupted_cb(audio_out_h output);
 502
 503 /**
 504  * @brief Ignore session for output
 505  * @param[in]  output   The handle to the audio output
 506  * @return 0 on success, otherwise a negative error value.
 507  * @retval #AUDIO_IO_ERROR_NONE Successful
 508  * @retval #AUDIO_IO_ERROR_INVALID_PARAMETER Invalid parameter
 509  * @retval #AUDIO_IO_ERROR_INVALID_OPERATION Invalid operation
 510  * @see
 511  */
 512 int audio_out_ignore_session(audio_out_h output);
 513
 514
 515 /**
 516  * @}
 517 */
 518
 519 #ifdef __cplusplus
 520 }
 521 #endif
 522
 523 #endif /* __TIZEN_MEDIA_AUDIO_IO_H__ */