- Timestamp:
- Dec 28, 2016 3:40:07 AM (8 years ago)
- Location:
- pjproject/branches/projects/uwp
- Files:
-
- 2 edited
Legend:
- Unmodified
- Added
- Removed
-
pjproject/branches/projects/uwp
- Property svn:mergeinfo changed
/pjproject/trunk (added) merged: 5209,5212-5234,5237-5253,5255,5257-5292,5294-5297,5299-5332,5334-5394,5396-5438,5440-5469,5471-5496,5498-5510
- Property svn:mergeinfo changed
-
pjproject/branches/projects/uwp/pjmedia/include/pjmedia-audiodev/audiodev.h
r5201 r5513 23 23 /** 24 24 * @file audiodev.h 25 * @brief Audio deviceAPI.25 * @brief Audio subsystem API. 26 26 */ 27 #include <pjmedia-audiodev/config.h>28 #include <pjmedia-audiodev/errno.h>29 #include <pjmedia/format.h>30 #include <pjmedia/frame.h>31 #include <pjmedia/types.h>32 27 #include <pj/pool.h> 28 #include <pjmedia/audiodev.h> 33 29 34 30 … … 36 32 37 33 /** 38 * @defgroup s2_audio_device_reference Audio DeviceAPI Reference39 * @ingroup audio_ device_api34 * @defgroup s2_audio_device_reference Audio Subsystem API Reference 35 * @ingroup audio_subsystem_api 40 36 * @brief API Reference 41 37 * @{ 42 38 */ 43 39 44 /**45 * Type for device index.46 */47 typedef pj_int32_t pjmedia_aud_dev_index;48 49 /**50 * Device index constants.51 */52 enum53 {54 /**55 * Constant to denote default capture device56 */57 PJMEDIA_AUD_DEFAULT_CAPTURE_DEV = -1,58 59 /**60 * Constant to denote default playback device61 */62 PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV = -2,63 64 /**65 * Constant to denote invalid device index.66 */67 PJMEDIA_AUD_INVALID_DEV = -368 };69 70 71 /**72 * This enumeration identifies various audio device capabilities. These audio73 * capabilities indicates what features are supported by the underlying74 * audio device implementation.75 *76 * Applications get these capabilities in the #pjmedia_aud_dev_info structure.77 *78 * Application can also set the specific features/capabilities when opening79 * the audio stream by setting the \a flags member of #pjmedia_aud_param80 * structure.81 *82 * Once audio stream is running, application can also retrieve or set some83 * specific audio capability, by using #pjmedia_aud_stream_get_cap() and84 * #pjmedia_aud_stream_set_cap() and specifying the desired capability. The85 * value of the capability is specified as pointer, and application needs to86 * supply the pointer with the correct value, according to the documentation87 * of each of the capability.88 */89 typedef enum pjmedia_aud_dev_cap90 {91 /**92 * Support for audio formats other than PCM. The value of this capability93 * is represented by #pjmedia_format structure.94 */95 PJMEDIA_AUD_DEV_CAP_EXT_FORMAT = 1,96 97 /**98 * Support for audio input latency control or query. The value of this99 * capability is an unsigned integer containing milliseconds value of100 * the latency.101 */102 PJMEDIA_AUD_DEV_CAP_INPUT_LATENCY = 2,103 104 /**105 * Support for audio output latency control or query. The value of this106 * capability is an unsigned integer containing milliseconds value of107 * the latency.108 */109 PJMEDIA_AUD_DEV_CAP_OUTPUT_LATENCY = 4,110 111 /**112 * Support for setting/retrieving the audio input device volume level.113 * The value of this capability is an unsigned integer representing114 * the input audio volume setting in percent.115 */116 PJMEDIA_AUD_DEV_CAP_INPUT_VOLUME_SETTING = 8,117 118 /**119 * Support for setting/retrieving the audio output device volume level.120 * The value of this capability is an unsigned integer representing121 * the output audio volume setting in percent.122 */123 PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING = 16,124 125 /**126 * Support for monitoring the current audio input signal volume.127 * The value of this capability is an unsigned integer representing128 * the audio volume in percent.129 */130 PJMEDIA_AUD_DEV_CAP_INPUT_SIGNAL_METER = 32,131 132 /**133 * Support for monitoring the current audio output signal volume.134 * The value of this capability is an unsigned integer representing135 * the audio volume in percent.136 */137 PJMEDIA_AUD_DEV_CAP_OUTPUT_SIGNAL_METER = 64,138 139 /**140 * Support for audio input routing. The value of this capability is an141 * integer containing #pjmedia_aud_dev_route enumeration.142 */143 PJMEDIA_AUD_DEV_CAP_INPUT_ROUTE = 128,144 145 /**146 * Support for audio output routing (e.g. loudspeaker vs earpiece). The147 * value of this capability is an integer containing #pjmedia_aud_dev_route148 * enumeration.149 */150 PJMEDIA_AUD_DEV_CAP_OUTPUT_ROUTE = 256,151 152 /**153 * The audio device has echo cancellation feature. The value of this154 * capability is a pj_bool_t containing boolean PJ_TRUE or PJ_FALSE.155 */156 PJMEDIA_AUD_DEV_CAP_EC = 512,157 158 /**159 * The audio device supports setting echo cancellation fail length. The160 * value of this capability is an unsigned integer representing the161 * echo tail in milliseconds.162 */163 PJMEDIA_AUD_DEV_CAP_EC_TAIL = 1024,164 165 /**166 * The audio device has voice activity detection feature. The value167 * of this capability is a pj_bool_t containing boolean PJ_TRUE or168 * PJ_FALSE.169 */170 PJMEDIA_AUD_DEV_CAP_VAD = 2048,171 172 /**173 * The audio device has comfort noise generation feature. The value174 * of this capability is a pj_bool_t containing boolean PJ_TRUE or175 * PJ_FALSE.176 */177 PJMEDIA_AUD_DEV_CAP_CNG = 4096,178 179 /**180 * The audio device has packet loss concealment feature. The value181 * of this capability is a pj_bool_t containing boolean PJ_TRUE or182 * PJ_FALSE.183 */184 PJMEDIA_AUD_DEV_CAP_PLC = 8192,185 186 /**187 * End of capability188 */189 PJMEDIA_AUD_DEV_CAP_MAX = 16384190 191 } pjmedia_aud_dev_cap;192 193 194 /**195 * This enumeration describes audio routing setting.196 */197 typedef enum pjmedia_aud_dev_route198 {199 /**200 * Default route, it is the default audio route of the audio framework201 * backend, as in opening audio device without specifying any route202 * setting or with specifying neutral route setting.203 */204 PJMEDIA_AUD_DEV_ROUTE_DEFAULT = 0,205 206 /** Route to loudspeaker */207 PJMEDIA_AUD_DEV_ROUTE_LOUDSPEAKER = 1,208 209 /** Route to earpiece */210 PJMEDIA_AUD_DEV_ROUTE_EARPIECE = 2,211 212 /** Route to paired Bluetooth device */213 PJMEDIA_AUD_DEV_ROUTE_BLUETOOTH = 4214 215 } pjmedia_aud_dev_route;216 217 218 /**219 * Device information structure returned by #pjmedia_aud_dev_get_info().220 */221 typedef struct pjmedia_aud_dev_info222 {223 /**224 * The device name225 */226 char name[PJMEDIA_AUD_DEV_INFO_NAME_LEN];227 228 /**229 * Maximum number of input channels supported by this device. If the230 * value is zero, the device does not support input operation (i.e.231 * it is a playback only device).232 */233 unsigned input_count;234 235 /**236 * Maximum number of output channels supported by this device. If the237 * value is zero, the device does not support output operation (i.e.238 * it is an input only device).239 */240 unsigned output_count;241 242 /**243 * Default sampling rate.244 */245 unsigned default_samples_per_sec;246 247 /**248 * The underlying driver name249 */250 char driver[32];251 252 /**253 * Device capabilities, as bitmask combination of #pjmedia_aud_dev_cap.254 */255 unsigned caps;256 257 /**258 * Supported audio device routes, as bitmask combination of259 * #pjmedia_aud_dev_route. The value may be zero if the device260 * does not support audio routing.261 */262 unsigned routes;263 264 /**265 * Number of audio formats supported by this device. The value may be266 * zero if the device does not support non-PCM format.267 */268 unsigned ext_fmt_cnt;269 270 /**271 * Array of supported extended audio formats272 */273 pjmedia_format ext_fmt[8];274 275 276 } pjmedia_aud_dev_info;277 278 279 /**280 * This callback is called by player stream when it needs additional data281 * to be played by the device. Application must fill in the whole of output282 * buffer with audio samples.283 *284 * The frame argument contains the following values:285 * - timestamp Playback timestamp, in samples.286 * - buf Buffer to be filled out by application.287 * - size The size requested in bytes, which will be equal to288 * the size of one whole packet.289 *290 * @param user_data User data associated with the stream.291 * @param frame Audio frame, which buffer is to be filled in by292 * the application.293 *294 * @return Returning non-PJ_SUCCESS will cause the audio stream295 * to stop296 */297 typedef pj_status_t (*pjmedia_aud_play_cb)(void *user_data,298 pjmedia_frame *frame);299 300 /**301 * This callback is called by recorder stream when it has captured the whole302 * packet worth of audio samples.303 *304 * @param user_data User data associated with the stream.305 * @param frame Captured frame.306 *307 * @return Returning non-PJ_SUCCESS will cause the audio stream308 * to stop309 */310 typedef pj_status_t (*pjmedia_aud_rec_cb)(void *user_data,311 pjmedia_frame *frame);312 313 /**314 * This structure specifies the parameters to open the audio stream.315 */316 typedef struct pjmedia_aud_param317 {318 /**319 * The audio direction. This setting is mandatory.320 */321 pjmedia_dir dir;322 323 /**324 * The audio recorder device ID. This setting is mandatory if the audio325 * direction includes input/capture direction.326 */327 pjmedia_aud_dev_index rec_id;328 329 /**330 * The audio playback device ID. This setting is mandatory if the audio331 * direction includes output/playback direction.332 */333 pjmedia_aud_dev_index play_id;334 335 /**336 * Clock rate/sampling rate. This setting is mandatory.337 */338 unsigned clock_rate;339 340 /**341 * Number of channels. This setting is mandatory.342 */343 unsigned channel_count;344 345 /**346 * Number of samples per frame. This setting is mandatory.347 */348 unsigned samples_per_frame;349 350 /**351 * Number of bits per sample. This setting is mandatory.352 */353 unsigned bits_per_sample;354 355 /**356 * This flags specifies which of the optional settings are valid in this357 * structure. The flags is bitmask combination of pjmedia_aud_dev_cap.358 */359 unsigned flags;360 361 /**362 * Set the audio format. This setting is optional, and will only be used363 * if PJMEDIA_AUD_DEV_CAP_EXT_FORMAT is set in the flags.364 */365 pjmedia_format ext_fmt;366 367 /**368 * Input latency, in milliseconds. This setting is optional, and will369 * only be used if PJMEDIA_AUD_DEV_CAP_INPUT_LATENCY is set in the flags.370 */371 unsigned input_latency_ms;372 373 /**374 * Input latency, in milliseconds. This setting is optional, and will375 * only be used if PJMEDIA_AUD_DEV_CAP_OUTPUT_LATENCY is set in the flags.376 */377 unsigned output_latency_ms;378 379 /**380 * Input volume setting, in percent. This setting is optional, and will381 * only be used if PJMEDIA_AUD_DEV_CAP_INPUT_VOLUME_SETTING is set in382 * the flags.383 */384 unsigned input_vol;385 386 /**387 * Output volume setting, in percent. This setting is optional, and will388 * only be used if PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING is set in389 * the flags.390 */391 unsigned output_vol;392 393 /**394 * Set the audio input route. This setting is optional, and will only be395 * used if PJMEDIA_AUD_DEV_CAP_INPUT_ROUTE is set in the flags.396 */397 pjmedia_aud_dev_route input_route;398 399 /**400 * Set the audio output route. This setting is optional, and will only be401 * used if PJMEDIA_AUD_DEV_CAP_OUTPUT_ROUTE is set in the flags.402 */403 pjmedia_aud_dev_route output_route;404 405 /**406 * Enable/disable echo canceller, if the device supports it. This setting407 * is optional, and will only be used if PJMEDIA_AUD_DEV_CAP_EC is set in408 * the flags.409 */410 pj_bool_t ec_enabled;411 412 /**413 * Set echo canceller tail length in milliseconds, if the device supports414 * it. This setting is optional, and will only be used if415 * PJMEDIA_AUD_DEV_CAP_EC_TAIL is set in the flags.416 */417 unsigned ec_tail_ms;418 419 /**420 * Enable/disable PLC. This setting is optional, and will only be used421 * if PJMEDIA_AUD_DEV_CAP_PLC is set in the flags.422 */423 pj_bool_t plc_enabled;424 425 /**426 * Enable/disable CNG. This setting is optional, and will only be used427 * if PJMEDIA_AUD_DEV_CAP_CNG is set in the flags.428 */429 pj_bool_t cng_enabled;430 431 /**432 * Enable/disable VAD. This setting is optional, and will only be used433 * if PJMEDIA_AUD_DEV_CAP_VAD is set in the flags.434 */435 pj_bool_t vad_enabled;436 437 } pjmedia_aud_param;438 439 440 /** Forward declaration for pjmedia_aud_stream */441 typedef struct pjmedia_aud_stream pjmedia_aud_stream;442 443 /** Forward declaration for audio device factory */444 typedef struct pjmedia_aud_dev_factory pjmedia_aud_dev_factory;445 446 /* typedef for factory creation function */447 typedef pjmedia_aud_dev_factory*448 (*pjmedia_aud_dev_factory_create_func_ptr)(pj_pool_factory*);449 450 451 /**452 * Get string info for the specified capability.453 *454 * @param cap The capability ID.455 * @param p_desc Optional pointer which will be filled with longer456 * description about the capability.457 *458 * @return Capability name.459 */460 PJ_DECL(const char*) pjmedia_aud_dev_cap_name(pjmedia_aud_dev_cap cap,461 const char **p_desc);462 463 464 /**465 * Set a capability field value in #pjmedia_aud_param structure. This will466 * also set the flags field for the specified capability in the structure.467 *468 * @param param The structure.469 * @param cap The audio capability which value is to be set.470 * @param pval Pointer to value. Please see the type of value to471 * be supplied in the pjmedia_aud_dev_cap documentation.472 *473 * @return PJ_SUCCESS on successful operation or the appropriate474 * error code.475 */476 PJ_DECL(pj_status_t) pjmedia_aud_param_set_cap(pjmedia_aud_param *param,477 pjmedia_aud_dev_cap cap,478 const void *pval);479 480 481 /**482 * Get a capability field value from #pjmedia_aud_param structure. This483 * function will return PJMEDIA_EAUD_INVCAP error if the flag for that484 * capability is not set in the flags field in the structure.485 *486 * @param param The structure.487 * @param cap The audio capability which value is to be retrieved.488 * @param pval Pointer to value. Please see the type of value to489 * be supplied in the pjmedia_aud_dev_cap documentation.490 *491 * @return PJ_SUCCESS on successful operation or the appropriate492 * error code.493 */494 PJ_DECL(pj_status_t) pjmedia_aud_param_get_cap(const pjmedia_aud_param *param,495 pjmedia_aud_dev_cap cap,496 void *pval);497 40 498 41 /** … … 559 102 560 103 /** 561 * Refresh the list of sound devices installed in the system. This function562 * will only refresh the list of audio device so all active audio streams will563 * be unaffected. After refreshing the device list, application MUST make sure564 * to update all index references to audio devices (i.e. all variables of type565 * pjmedia_aud_dev_index) before calling any function that accepts audio device566 * index as its parameter.567 *568 * @return PJ_SUCCESS on successful operation or the appropriate569 * error code.570 */571 PJ_DECL(pj_status_t) pjmedia_aud_dev_refresh(void);572 573 574 /**575 * Get the number of sound devices installed in the system.576 *577 * @return The number of sound devices installed in the system.578 */579 PJ_DECL(unsigned) pjmedia_aud_dev_count(void);580 581 582 /**583 * Get device information.584 *585 * @param id The audio device ID.586 * @param info The device information which will be filled in by this587 * function once it returns successfully.588 *589 * @return PJ_SUCCESS on successful operation or the appropriate590 * error code.591 */592 PJ_DECL(pj_status_t) pjmedia_aud_dev_get_info(pjmedia_aud_dev_index id,593 pjmedia_aud_dev_info *info);594 595 596 /**597 * Lookup device index based on the driver and device name.598 *599 * @param drv_name The driver name.600 * @param dev_name The device name.601 * @param id Pointer to store the returned device ID.602 *603 * @return PJ_SUCCESS if the device can be found.604 */605 PJ_DECL(pj_status_t) pjmedia_aud_dev_lookup(const char *drv_name,606 const char *dev_name,607 pjmedia_aud_dev_index *id);608 609 610 /**611 * Initialize the audio device parameters with default values for the612 * specified device.613 *614 * @param id The audio device ID.615 * @param param The audio device parameters which will be initialized616 * by this function once it returns successfully.617 *618 * @return PJ_SUCCESS on successful operation or the appropriate619 * error code.620 */621 PJ_DECL(pj_status_t) pjmedia_aud_dev_default_param(pjmedia_aud_dev_index id,622 pjmedia_aud_param *param);623 624 625 /**626 * Open audio stream object using the specified parameters.627 *628 * @param param Sound device parameters to be used for the stream.629 * @param rec_cb Callback to be called on every input frame captured.630 * @param play_cb Callback to be called everytime the sound device needs631 * audio frames to be played back.632 * @param user_data Arbitrary user data, which will be given back in the633 * callbacks.634 * @param p_strm Pointer to receive the audio stream.635 *636 * @return PJ_SUCCESS on successful operation or the appropriate637 * error code.638 */639 PJ_DECL(pj_status_t) pjmedia_aud_stream_create(const pjmedia_aud_param *param,640 pjmedia_aud_rec_cb rec_cb,641 pjmedia_aud_play_cb play_cb,642 void *user_data,643 pjmedia_aud_stream **p_strm);644 645 /**646 * Get the running parameters for the specified audio stream.647 *648 * @param strm The audio stream.649 * @param param Audio stream parameters to be filled in by this650 * function once it returns successfully.651 *652 * @return PJ_SUCCESS on successful operation or the appropriate653 * error code.654 */655 PJ_DECL(pj_status_t) pjmedia_aud_stream_get_param(pjmedia_aud_stream *strm,656 pjmedia_aud_param *param);657 658 /**659 * Get the value of a specific capability of the audio stream.660 *661 * @param strm The audio stream.662 * @param cap The audio capability which value is to be retrieved.663 * @param value Pointer to value to be filled in by this function664 * once it returns successfully. Please see the type665 * of value to be supplied in the pjmedia_aud_dev_cap666 * documentation.667 *668 * @return PJ_SUCCESS on successful operation or the appropriate669 * error code.670 */671 PJ_DECL(pj_status_t) pjmedia_aud_stream_get_cap(pjmedia_aud_stream *strm,672 pjmedia_aud_dev_cap cap,673 void *value);674 675 /**676 * Set the value of a specific capability of the audio stream.677 *678 * @param strm The audio stream.679 * @param cap The audio capability which value is to be set.680 * @param value Pointer to value. Please see the type of value to681 * be supplied in the pjmedia_aud_dev_cap documentation.682 *683 * @return PJ_SUCCESS on successful operation or the appropriate684 * error code.685 */686 PJ_DECL(pj_status_t) pjmedia_aud_stream_set_cap(pjmedia_aud_stream *strm,687 pjmedia_aud_dev_cap cap,688 const void *value);689 690 /**691 * Start the stream.692 *693 * @param strm The audio stream.694 *695 * @return PJ_SUCCESS on successful operation or the appropriate696 * error code.697 */698 PJ_DECL(pj_status_t) pjmedia_aud_stream_start(pjmedia_aud_stream *strm);699 700 /**701 * Stop the stream.702 *703 * @param strm The audio stream.704 *705 * @return PJ_SUCCESS on successful operation or the appropriate706 * error code.707 */708 PJ_DECL(pj_status_t) pjmedia_aud_stream_stop(pjmedia_aud_stream *strm);709 710 /**711 * Destroy the stream.712 *713 * @param strm The audio stream.714 *715 * @return PJ_SUCCESS on successful operation or the appropriate716 * error code.717 */718 PJ_DECL(pj_status_t) pjmedia_aud_stream_destroy(pjmedia_aud_stream *strm);719 720 721 /**722 104 * @} 723 105 */
Note: See TracChangeset
for help on using the changeset viewer.