105 | | This section describes how to port applications to use the new Audio Device API. |
| 105 | |
| 106 | === Default device convention === |
| 107 | |
| 108 | Old API:: |
| 109 | Value -1 is used throughout to denote default device |
| 110 | |
| 111 | New API:: |
| 112 | Default devices are encoded with the following constants: |
| 113 | - PJMEDIA_AUD_DEFAULT_CAPTURE_DEV (-1) is not used to denote default capture device, and |
| 114 | - PJMEDIA_AUD_DEFAULT_PLAYBACK_DEV (-2) for default playback device. |
| 115 | |
| 116 | Applications using the old convention is expected to work with the new API. |
| 117 | |
| 118 | === Configuring AEC with the sound port === #ec |
| 119 | |
| 120 | Old API:: |
| 121 | The echo cancellation is usually configured after the sound port is created, by using {{{pjmedia_snd_port_set_ec()}}}. |
| 122 | |
| 123 | New API:: |
| 124 | The semantic of {{{pjmedia_snd_port_set_ec()}}} API has been changed to ''to change the settings of the AEC'' rather than ''to enable AEC''. With the new API, the best way to configure AEC is to set the EC parameters in the {{{pjmedia_aud_param}}} when creating the sound device or sound device port, e.g.: |
| 125 | {{{ |
| 126 | pjmedia_aud_param param; |
| 127 | .. |
| 128 | param.flags |= (PJMEDIA_AUD_DEV_CAP_EC | PJMEDIA_AUD_DEV_CAP_EC_TAIL); |
| 129 | param.ec_enabled = PJ_TRUE; |
| 130 | param.ec_tail_ms = ..; |
| 131 | .. |
| 132 | pjmedia_snd_port_create2(pool, ¶m, &snd_port); |
| 133 | }}} |
| 134 | If {{{pjmedia_snd_port_set_ec()}}} is called after the sound port is opened, the behavior is as follows: |
| 135 | - if the device supports (hardware) AEC, as indicated by device capabilities, then the sound port will forward the change request to the device. The device may or may not support the request to change AEC parameters after the device is opened. |
| 136 | - if software AEC is being used (for devices that don't support AEC), this will change the setting of the software AEC. Effectively this resembles the old behavior of the API. |
| 137 | |
| 138 | |
| 139 | |