Media

Media objects are objects that are capable to either produce media or takes media.

An important subclass of Media is AudioMedia which represents audio media. There are several type of audio media objects supported in PJSUA2:

  • Capture device’s AudioMedia, to capture audio from the sound device.

  • Playback device’s AudioMedia, to play audio to the sound device.

  • Call’s AudioMedia, to transmit and receive audio to/from remote person.

  • AudioMediaPlayer, to play WAV file(s).

  • AudioMediaRecorder, to record audio to a WAV file.

More media objects may be added in the future.

The Audio Conference Bridge

The conference bridge provides a simple but yet powerful concept to manage audio flow between the audio medias. The principle is very simple, that is you connect audio source to audio destination, and the bridge will make the audio flows from the source to destination, and that’s it. If more than one sources are transmitting to the same destination, then the audio from the sources will be mixed. If one source is transmitting to more than one destinations, the bridge will take care of duplicating the audio from the source to the multiple destinations. The bridge will even take care medias with different clock rates and ptime.

In PJSUA2, all audio media objects are plugged-in to the central conference bridge for easier manipulation. At first, a plugged-in audio media will not be connected to anything, so media will not flow from/to any objects. An audio media source can start/stop the transmission to a destination by using the API AudioMedia.startTransmit() / AudioMedia.stopTransmit().

An audio media object plugged-in to the conference bridge will be given a port ID number that identifies the object in the bridge. Application can use the API AudioMedia.getPortId() to retrieve the port ID. Normally, application should not need to worry about the conference bridge and its port ID (as all will be taken care of by the Media class) unless application want to create its own custom audio media.

Playing a WAV File

To playback the WAV file to the sound device, just start the transmission of the WAV playback object to the sound device’s playback media:

AudioMediaPlayer player;
AudioMedia& play_med = Endpoint::instance().audDevManager().getPlaybackDevMedia();
try {
    player.createPlayer("file.wav");
    player.startTransmit(play_med);
} catch(Error& err) {
}

By default, the WAV file will be played in a loop. To disable the loop, specify PJMEDIA_FILE_NO_LOOP when creating the player:

player.createPlayer("file.wav", PJMEDIA_FILE_NO_LOOP);

Without looping, silence will be played once the playback has reached the end of the WAV file.

Once you’re done with the playback, just stop the transmission to stop the playback:

try {
    player.stopTransmit(play_med);
} catch(Error& err) {
}

Resuming the transmission after the playback is stopped will resume playback from the last play position. Use player.setPos() to set playback position to a desired location.

Recording to WAV File

Or if you want to record the audio from the sound device to the WAV file, simply do this:

AudioMediaRecorder recorder;
AudioMedia& cap_med = Endpoint::instance().audDevManager().getCaptureDevMedia();
try {
    recorder.createRecorder("file.wav");
    cap_med.startTransmit(recorder);
} catch(Error& err) {
}

And the media will flow from the sound device to the WAV record file. As usual, to stop or pause recording, just stop the transmission:

try {
   cap_med.stopTransmit(recorder);
} catch(Error& err) {
}

Note that stopping the transmission to the WAV recorder as above does not close the WAV file, and you can resume recording by connecting a source to the WAV recorder again. You cannot playback the recorded WAV file before you close it. To close the WAV recorder, simply delete it:

delete recorder;

Local Audio Loopback

A useful test to check whether the local sound device (capture and playback device) is working properly is by transmitting the audio from the capture device directly to the playback device (i.e. local loopback). You can do this by:

cap_med.startTransmit(play_med);

Looping Audio

If you want, you can loop the audio of an audio media object to itself (i.e. the audio received from the object will be transmitted to itself). You can loop-back audio from any objects, as long as the object has bidirectional media. That means you can loop the call’s audio media, so that audio received from the remote person will be transmitted back to her/him. But you can’t loop the WAV player or recorder since these objects can only play or record and not both.

Normal Call

A single call can have more than one media (for example, audio and video). Application can retrieve the audio media by using the API Call.getMedia(). Then for a normal call, we would want to establish bidirectional audio with the remote person, which can be done easily by connecting the sound device and the call audio media and vice versa:

CallInfo ci = call.getInfo();
AudioMedia *aud_med = NULL;

// Find out which media index is the audio
for (unsigned i=0; i<ci.media.size(); ++i) {
    if (ci.media[i].type == PJMEDIA_TYPE_AUDIO) {
        aud_med = (AudioMedia *)call.getMedia(i);
        break;
    }
}

if (aud_med) {
    // This will connect the sound device/mic to the call audio media
    cap_med.startTransmit(*aud_med);

    // And this will connect the call audio media to the sound device/speaker
    aud_med->startTransmit(play_med);
}

Second Call

Suppose we want to talk with two remote parties at the same time. Since we already have bidirectional media connection with one party, we just need to add bidirectional connection with the other party using the code below:

AudioMedia *aud_med2 = (AudioMedia *)call2.getMedia(aud_idx);
if (aud_med2) {
    cap_med->startTransmit(*aud_med2);
    aud_med2->startTransmit(play_med);
}

Now we can talk to both parties at the same time, and we will hear audio from either party. But at this stage, the remote parties can’t talk or hear each other (i.e. we’re not in full conference mode yet).

Conference Call

To enable both parties talk to each other, just establish bidirectional media between them:

aud_med->startTransmit(*aud_med2);
aud_med2->startTransmit(*aud_med);

Now the three parties (us and both remote parties) will be able to talk to each other.

Recording the Conference

While doing the conference, it perfectly makes sense to want to record the conference to a WAV file, and all we need to do is to connect the microphone and both calls to the WAV recorder:

cap_med.startTransmit(recorder);
aud_med->startTransmit(recorder);
aud_med2->startTransmit(recorder);

Audio Device Management

Please see Audio Device Framework below.

Class Reference

Media Framework

Classes

class Media

Media.

Subclassed by pj::AudioMedia, pj::VideoMedia

Public Functions

virtual ~Media()

Virtual destructor.

pjmedia_type getType() const

Get type of the media.

Returns

The media type.

class AudioMedia : public pj::Media

Audio Media. This is a lite wrapper class for audio conference bridge port, i.e: this class only maintains one data member, conference slot ID, and the methods are simply proxies for conference bridge operations.

Application can create a derived class and use registerMediaPort2()/ unregisterMediaPort() to register/unregister a media port to/from the conference bridge.

The library will not keep a list of AudioMedia instances, so any AudioMedia (descendant) instances instantiated by application must be maintained and destroyed by the application itself.

Note that any PJSUA2 APIs that return AudioMedia instance(s) such as Endpoint::mediaEnumPorts2() or Call::getAudioMedia() will just return generated copy. All AudioMedia methods should work normally on this generated copy instance.

Subclassed by pj::AudioMediaPlayer, pj::AudioMediaRecorder, pj::ExtraAudioDevice, pj::ToneGenerator

Public Functions

ConfPortInfo getPortInfo () const PJSUA2_THROW(Error)

Get information about the specified conference port.

int getPortId() const

Get port Id.

void startTransmit (const AudioMedia &sink) const PJSUA2_THROW(Error)

Establish unidirectional media flow to sink. This media port will act as a source, and it may transmit to multiple destinations/sink. And if multiple sources are transmitting to the same sink, the media will be mixed together. Source and sink may refer to the same Media, effectively looping the media.

If bidirectional media flow is desired, application needs to call this method twice, with the second one called from the opposite source media.

Parameters

sink – The destination Media.

void startTransmit2 (const AudioMedia &sink, const AudioMediaTransmitParam &param) const PJSUA2_THROW(Error)

Establish unidirectional media flow to sink. This media port will act as a source, and it may transmit to multiple destinations/sink. And if multiple sources are transmitting to the same sink, the media will be mixed together. Source and sink may refer to the same Media, effectively looping the media.

Signal level from this source to the sink can be adjusted by making it louder or quieter via the parameter param. The level adjustment will apply to a specific connection only (i.e. only for signal from this source to the sink), as compared to adjustTxLevel()/adjustRxLevel() which applies to all signals from/to this media port. The signal adjustment will be cumulative, in this following order: signal from this source will be adjusted with the level specified in adjustTxLevel(), then with the level specified via this API, and finally with the level specified to the sink’s adjustRxLevel().

If bidirectional media flow is desired, application needs to call this method twice, with the second one called from the opposite source media.

Parameters
  • sink – The destination Media.

  • param – The parameter.

void stopTransmit (const AudioMedia &sink) const PJSUA2_THROW(Error)

Stop media flow to destination/sink port.

Parameters

sink – The destination media.

void adjustRxLevel (float level) PJSUA2_THROW(Error)

Adjust the signal level to be transmitted from the bridge to this media port by making it louder or quieter.

Parameters

level – Signal level adjustment. Value 1.0 means no level adjustment, while value 0 means to mute the port.

void adjustTxLevel (float level) PJSUA2_THROW(Error)

Adjust the signal level to be received from this media port (to the bridge) by making it louder or quieter.

Parameters

level – Signal level adjustment. Value 1.0 means no level adjustment, while value 0 means to mute the port.

unsigned getRxLevel () const PJSUA2_THROW(Error)

Get the last received signal level.

Returns

Signal level in percent.

unsigned getTxLevel () const PJSUA2_THROW(Error)

Get the last transmitted signal level.

Returns

Signal level in percent.

AudioMedia()

Default Constructor.

Normally application will not create AudioMedia object directly, but it instantiates an AudioMedia derived class. This is set as public because some STL vector implementations require it.

virtual ~AudioMedia()

Virtual Destructor.

Public Static Functions

static ConfPortInfo getPortInfoFromId (int port_id) PJSUA2_THROW(Error)

Get information from specific port id.

static AudioMedia *typecastFromMedia(Media *media)

Warning: deprecated and will be removed in future release.

Typecast from base class Media. This is useful for application written in language that does not support downcasting such as Python.

Parameters

media – The object to be downcasted

Returns

The object as AudioMedia instance

class AudioMediaPlayer : public pj::AudioMedia

Audio Media Player.

Public Functions

AudioMediaPlayer()

Constructor.

void createPlayer (const string &file_name, unsigned options=0) PJSUA2_THROW(Error)

Create a file player, and automatically add this player to the conference bridge.

Parameters
  • file_name – The filename to be played. Currently only WAV files are supported, and the WAV file MUST be formatted as 16bit PCM mono/single channel (any clock rate is supported).

  • options – Optional option flag. Application may specify PJMEDIA_FILE_NO_LOOP to prevent playback loop.

void createPlaylist (const StringVector &file_names, const string &label="", unsigned options=0) PJSUA2_THROW(Error)

Create a file playlist media port, and automatically add the port to the conference bridge.

Parameters
  • file_names – Array of file names to be added to the play list. Note that the files must have the same clock rate, number of channels, and number of bits per sample.

  • label – Optional label to be set for the media port.

  • options – Optional option flag. Application may specify PJMEDIA_FILE_NO_LOOP to prevent looping.

AudioMediaPlayerInfo getInfo () const PJSUA2_THROW(Error)

Get additional info about the player. This operation is only valid for player. For playlist, Error will be thrown.

Returns

the info.

pj_uint32_t getPos () const PJSUA2_THROW(Error)

Get current playback position in samples. This operation is not valid for playlist.

Returns

Current playback position, in samples.

void setPos (pj_uint32_t samples) PJSUA2_THROW(Error)

Set playback position in samples. This operation is not valid for playlist.

Parameters

samples – The desired playback position, in samples.

virtual ~AudioMediaPlayer()

Destructor. This will unregister the player port from the conference bridge.

inline virtual void onEof2()

Register a callback to be called when the file player reading has reached the end of file, or when the file reading has reached the end of file of the last file for a playlist. If the file or playlist is set to play repeatedly, then the callback will be called multiple times.

If application wishes to stop the playback, it can stop the media transmission in the callback, and only after all transmissions have been stopped, could the application safely destroy the player.

Public Static Functions

static AudioMediaPlayer *typecastFromAudioMedia(AudioMedia *media)

Warning: deprecated and will be removed in future release.

Typecast from base class AudioMedia. This is useful for application written in language that does not support downcasting such as Python.

Parameters

media – The object to be downcasted

Returns

The object as AudioMediaPlayer instance

class AudioMediaRecorder : public pj::AudioMedia

Audio Media Recorder.

Public Functions

AudioMediaRecorder()

Constructor.

void createRecorder (const string &file_name, unsigned enc_type=0, long max_size=0, unsigned options=0) PJSUA2_THROW(Error)

Create a file recorder, and automatically connect this recorder to the conference bridge. The recorder currently supports recording WAV file. The type of the recorder to use is determined by the extension of the file (e.g. “.wav”).

Parameters
  • file_name – Output file name. The function will determine the default format to be used based on the file extension. Currently “.wav” is supported on all platforms.

  • enc_type – Optionally specify the type of encoder to be used to compress the media, if the file can support different encodings. This value must be zero for now.

  • max_size – Maximum file size. Specify zero or -1 to remove size limitation. This value must be zero or -1 for now.

  • options – Optional options, which can be used to specify the recording file format. Supported options are PJMEDIA_FILE_WRITE_PCM, PJMEDIA_FILE_WRITE_ALAW, and PJMEDIA_FILE_WRITE_ULAW. Default is zero or PJMEDIA_FILE_WRITE_PCM.

virtual ~AudioMediaRecorder()

Destructor. This will unregister the recorder port from the conference bridge.

Public Static Functions

static AudioMediaRecorder *typecastFromAudioMedia(AudioMedia *media)

Warning: deprecated and will be removed in future release.

Typecast from base class AudioMedia. This is useful for application written in language that does not support downcasting such as Python.

Parameters

media – The object to be downcasted

Returns

The object as AudioMediaRecorder instance

Formats and Info

struct MediaFormat

This structure contains all the information needed to completely describe a media.

Subclassed by pj::MediaFormatAudio, pj::MediaFormatVideo

Public Functions

inline MediaFormat()

Default constructor

Public Members

pj_uint32_t id

The format id that specifies the audio sample or video pixel format. Some well known formats ids are declared in pjmedia_format_id enumeration.

pjmedia_type type

The top-most type of the media, as an information.

struct MediaFormatAudio : public pj::MediaFormat

This structure describe detail information about an audio media.

Public Functions

void fromPj(const pjmedia_format &format)

Construct from pjmedia_format.

pjmedia_format toPj() const

Export to pjmedia_format.

Public Members

unsigned clockRate

Audio clock rate in samples or Hz.

unsigned channelCount

Number of channels.

unsigned frameTimeUsec

Frame interval, in microseconds.

unsigned bitsPerSample

Number of bits per sample.

pj_uint32_t avgBps

Average bitrate

pj_uint32_t maxBps

Maximum bitrate

struct MediaFormatVideo : public pj::MediaFormat

This structure describe detail information about an video media.

Public Functions

void fromPj(const pjmedia_format &format)

Construct from pjmedia_format.

pjmedia_format toPj() const

Export to pjmedia_format.

Public Members

unsigned width

Video width.

unsigned height

Video height.

int fpsNum

Frames per second numerator.

int fpsDenum

Frames per second denumerator.

pj_uint32_t avgBps

Average bitrate.

pj_uint32_t maxBps

Maximum bitrate.

struct ConfPortInfo

This structure descibes information about a particular media port that has been registered into the conference bridge.

Public Functions

void fromPj(const pjsua_conf_port_info &port_info)

Construct from pjsua_conf_port_info.

Public Members

int portId

Conference port number.

string name

Port name.

MediaFormatAudio format

Media audio format information

float txLevelAdj

Tx level adjustment. Value 1.0 means no adjustment, value 0 means the port is muted, value 2.0 means the level is amplified two times.

float rxLevelAdj

Rx level adjustment. Value 1.0 means no adjustment, value 0 means the port is muted, value 2.0 means the level is amplified two times.

IntVector listeners

Array of listeners (in other words, ports where this port is transmitting to).

Audio Device Framework

Device Manager

class AudDevManager

Audio device manager.

Public Functions

int getCaptureDev () const PJSUA2_THROW(Error)

Get currently active capture sound devices. If sound devices has not been created, it is possible that the function returns -1 as device IDs.

Returns

Device ID of the capture device.

AudioMedia & getCaptureDevMedia () PJSUA2_THROW(Error)

Get the AudioMedia of the capture audio device.

Returns

Audio media for the capture device.

int getPlaybackDev () const PJSUA2_THROW(Error)

Get currently active playback sound devices. If sound devices has not been created, it is possible that the function returns -1 as device IDs.

Returns

Device ID of the playback device.

AudioMedia & getPlaybackDevMedia () PJSUA2_THROW(Error)

Get the AudioMedia of the speaker/playback audio device.

Returns

Audio media for the speaker/playback device.

void setCaptureDev (int capture_dev) const PJSUA2_THROW(Error)

Select or change capture sound device. Application may call this function at any time to replace current sound device. Calling this method will not change the state of the sound device (opened/closed). Note that this method will override the mode set by setSndDevMode().

Parameters

capture_dev – Device ID of the capture device.

void setPlaybackDev (int playback_dev) const PJSUA2_THROW(Error)

Select or change playback sound device. Application may call this function at any time to replace current sound device. Calling this method will not change the state of the sound device (opened/closed). Note that this method will override the mode set by setSndDevMode().

Parameters

playback_dev – Device ID of the playback device.

const AudioDevInfoVector & enumDev () PJSUA2_THROW(Error)

Warning: deprecated, use enumDev2 instead. This function is not safe in multithreaded environment.

Enum all audio devices installed in the system. This function is not safe in multithreaded environment.

Returns

The list of audio device info.

AudioDevInfoVector2 enumDev2 () const PJSUA2_THROW(Error)

Enum all audio devices installed in the system.

Returns

The list of audio device info.

void setNullDev () PJSUA2_THROW(Error)

Set pjsua to use null sound device. The null sound device only provides the timing needed by the conference bridge, and will not interract with any hardware.

MediaPort *setNoDev()

Disconnect the main conference bridge from any sound devices, and let application connect the bridge to it’s own sound device/master port.

Returns

The port interface of the conference bridge, so that application can connect this to it’s own sound device or master port.

void setSndDevMode (unsigned mode) const PJSUA2_THROW(Error)

Set sound device mode.

Parameters

mode – The sound device mode, as bitmask combination of pjsua_snd_dev_mode

void setEcOptions (unsigned tail_msec, unsigned options) PJSUA2_THROW(Error)

Change the echo cancellation settings.

The behavior of this function depends on whether the sound device is currently active, and if it is, whether device or software AEC is being used.

If the sound device is currently active, and if the device supports AEC, this function will forward the change request to the device and it will be up to the device on whether support the request. If software AEC is being used (the software EC will be used if the device does not support AEC), this function will change the software EC settings. In all cases, the setting will be saved for future opening of the sound device.

If the sound device is not currently active, this will only change the default AEC settings and the setting will be applied next time the sound device is opened.

Parameters
  • tail_msec – The tail length, in miliseconds. Set to zero to disable AEC.

  • options – Options to be passed to pjmedia_echo_create(). Normally the value should be zero.

unsigned getEcTail () const PJSUA2_THROW(Error)

Get current echo canceller tail length.

Returns

The EC tail length in milliseconds, If AEC is disabled, the value will be zero.

bool sndIsActive() const

Check whether the sound device is currently active. The sound device may be inactive if the application has set the auto close feature to non-zero (the sndAutoCloseTime setting in MediaConfig), or if null sound device or no sound device has been configured via the setNoDev() function.

void refreshDevs () PJSUA2_THROW(Error)

Refresh the list of sound devices installed in the system. This method will only refresh the list of audio device so all active audio streams will be unaffected. After refreshing the device list, application MUST make sure to update all index references to audio devices before calling any method that accepts audio device index as its parameter.

unsigned getDevCount() const

Get the number of sound devices installed in the system.

Returns

The number of sound devices installed in the system.

AudioDevInfo getDevInfo (int id) const PJSUA2_THROW(Error)

Get device information.

Parameters

id – The audio device ID.

Returns

The device information which will be filled in by this method once it returns successfully.

int lookupDev (const string &drv_name, const string &dev_name) const PJSUA2_THROW(Error)

Lookup device index based on the driver and device name.

Parameters
  • drv_name – The driver name.

  • dev_name – The device name.

Returns

The device ID. If the device is not found, Error will be thrown.

string capName(pjmedia_aud_dev_cap cap) const

Get string info for the specified capability.

Parameters

cap – The capability ID.

Returns

Capability name.

void setExtFormat (const MediaFormatAudio &format, bool keep=true) PJSUA2_THROW(Error)

This will configure audio format capability (other than PCM) to the sound device being used. If sound device is currently active, the method will forward the setting to the sound device instance to be applied immediately, if it supports it.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_EXT_FORMAT capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Note that in case the setting is kept for future use, it will be applied to any devices, even when application has changed the sound device to be used.

Parameters
  • format – The audio format.

  • keep – Specify whether the setting is to be kept for future use.

MediaFormatAudio getExtFormat () const PJSUA2_THROW(Error)

Get the audio format capability (other than PCM) of the sound device being used. If sound device is currently active, the method will forward the request to the sound device. If sound device is currently inactive, and if application had previously set the setting and mark the setting as kept, then that setting will be returned. Otherwise, this method will raise error.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_EXT_FORMAT capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Returns

The audio format.

void setInputLatency (unsigned latency_msec, bool keep=true) PJSUA2_THROW(Error)

This will configure audio input latency control or query capability to the sound device being used. If sound device is currently active, the method will forward the setting to the sound device instance to be applied immediately, if it supports it.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_INPUT_LATENCY capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Note that in case the setting is kept for future use, it will be applied to any devices, even when application has changed the sound device to be used.

Parameters
  • latency_msec – The input latency.

  • keep – Specify whether the setting is to be kept for future use.

unsigned getInputLatency () const PJSUA2_THROW(Error)

Get the audio input latency control or query capability of the sound device being used. If sound device is currently active, the method will forward the request to the sound device. If sound device is currently inactive, and if application had previously set the setting and mark the setting as kept, then that setting will be returned. Otherwise, this method will raise error.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_INPUT_LATENCY capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Returns

The audio input latency.

void setOutputLatency (unsigned latency_msec, bool keep=true) PJSUA2_THROW(Error)

This will configure audio output latency control or query capability to the sound device being used. If sound device is currently active, the method will forward the setting to the sound device instance to be applied immediately, if it supports it.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_OUTPUT_LATENCY capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Note that in case the setting is kept for future use, it will be applied to any devices, even when application has changed the sound device to be used.

Parameters
  • latency_msec – The output latency.

  • keep – Specify whether the setting is to be kept for future use.

unsigned getOutputLatency () const PJSUA2_THROW(Error)

Get the audio output latency control or query capability of the sound device being used. If sound device is currently active, the method will forward the request to the sound device. If sound device is currently inactive, and if application had previously set the setting and mark the setting as kept, then that setting will be returned. Otherwise, this method will raise error.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_OUTPUT_LATENCY capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Returns

The audio output latency.

void setInputVolume (unsigned volume, bool keep=true) PJSUA2_THROW(Error)

This will configure audio input volume level capability to the sound device being used. If sound device is currently active, the method will forward the setting to the sound device instance to be applied immediately, if it supports it.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_INPUT_VOLUME_SETTING capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Note that in case the setting is kept for future use, it will be applied to any devices, even when application has changed the sound device to be used.

Parameters
  • volume – The input volume level, in percent.

  • keep – Specify whether the setting is to be kept for future use.

unsigned getInputVolume () const PJSUA2_THROW(Error)

Get the audio input volume level capability of the sound device being used. If sound device is currently active, the method will forward the request to the sound device. If sound device is currently inactive, and if application had previously set the setting and mark the setting as kept, then that setting will be returned. Otherwise, this method will raise error.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_INPUT_VOLUME_SETTING capability in AudioDevInfo.caps flags, otherwise Error will be thrown. *

Returns

The audio input volume level, in percent.

void setOutputVolume (unsigned volume, bool keep=true) PJSUA2_THROW(Error)

This will configure audio output volume level capability to the sound device being used. If sound device is currently active, the method will forward the setting to the sound device instance to be applied immediately, if it supports it.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Note that in case the setting is kept for future use, it will be applied to any devices, even when application has changed the sound device to be used.

Parameters
  • volume – The output volume level, in percent.

  • keep – Specify whether the setting is to be kept for future use.

unsigned getOutputVolume () const PJSUA2_THROW(Error)

Get the audio output volume level capability of the sound device being used. If sound device is currently active, the method will forward the request to the sound device. If sound device is currently inactive, and if application had previously set the setting and mark the setting as kept, then that setting will be returned. Otherwise, this method will raise error.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_OUTPUT_VOLUME_SETTING capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Returns

The audio output volume level, in percent.

unsigned getInputSignal () const PJSUA2_THROW(Error)

Get the audio input signal level capability of the sound device being used. If sound device is currently active, the method will forward the request to the sound device. If sound device is currently inactive, and if application had previously set the setting and mark the setting as kept, then that setting will be returned. Otherwise, this method will raise error.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_INPUT_SIGNAL_METER capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Returns

The audio input signal level, in percent.

unsigned getOutputSignal () const PJSUA2_THROW(Error)

Get the audio output signal level capability of the sound device being used. If sound device is currently active, the method will forward the request to the sound device. If sound device is currently inactive, and if application had previously set the setting and mark the setting as kept, then that setting will be returned. Otherwise, this method will raise error.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_OUTPUT_SIGNAL_METER capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Returns

The audio output signal level, in percent.

void setInputRoute (pjmedia_aud_dev_route route, bool keep=true) PJSUA2_THROW(Error)

This will configure audio input route capability to the sound device being used. If sound device is currently active, the method will forward the setting to the sound device instance to be applied immediately, if it supports it.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_INPUT_ROUTE capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Note that in case the setting is kept for future use, it will be applied to any devices, even when application has changed the sound device to be used.

Parameters
  • route – The audio input route.

  • keep – Specify whether the setting is to be kept for future use.

pjmedia_aud_dev_route getInputRoute () const PJSUA2_THROW(Error)

Get the audio input route capability of the sound device being used. If sound device is currently active, the method will forward the request to the sound device. If sound device is currently inactive, and if application had previously set the setting and mark the setting as kept, then that setting will be returned. Otherwise, this method will raise error.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_INPUT_ROUTE capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Returns

The audio input route.

void setOutputRoute (pjmedia_aud_dev_route route, bool keep=true) PJSUA2_THROW(Error)

This will configure audio output route capability to the sound device being used. If sound device is currently active, the method will forward the setting to the sound device instance to be applied immediately, if it supports it.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_OUTPUT_ROUTE capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Note that in case the setting is kept for future use, it will be applied to any devices, even when application has changed the sound device to be used.

Parameters
  • route – The audio output route.

  • keep – Specify whether the setting is to be kept for future use.

pjmedia_aud_dev_route getOutputRoute () const PJSUA2_THROW(Error)

Get the audio output route capability of the sound device being used. If sound device is currently active, the method will forward the request to the sound device. If sound device is currently inactive, and if application had previously set the setting and mark the setting as kept, then that setting will be returned. Otherwise, this method will raise error.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_OUTPUT_ROUTE capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Returns

The audio output route.

void setVad (bool enable, bool keep=true) PJSUA2_THROW(Error)

This will configure audio voice activity detection capability to the sound device being used. If sound device is currently active, the method will forward the setting to the sound device instance to be applied immediately, if it supports it.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_VAD capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Note that in case the setting is kept for future use, it will be applied to any devices, even when application has changed the sound device to be used.

Parameters
  • enable – Enable/disable voice activity detection feature. Set true to enable.

  • keep – Specify whether the setting is to be kept for future use.

bool getVad () const PJSUA2_THROW(Error)

Get the audio voice activity detection capability of the sound device being used. If sound device is currently active, the method will forward the request to the sound device. If sound device is currently inactive, and if application had previously set the setting and mark the setting as kept, then that setting will be returned. Otherwise, this method will raise error.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_VAD capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Returns

The audio voice activity detection feature.

void setCng (bool enable, bool keep=true) PJSUA2_THROW(Error)

This will configure audio comfort noise generation capability to the sound device being used. If sound device is currently active, the method will forward the setting to the sound device instance to be applied immediately, if it supports it.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_CNG capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Note that in case the setting is kept for future use, it will be applied to any devices, even when application has changed the sound device to be used.

Parameters
  • enable – Enable/disable comfort noise generation feature. Set true to enable.

  • keep – Specify whether the setting is to be kept for future use.

bool getCng () const PJSUA2_THROW(Error)

Get the audio comfort noise generation capability of the sound device being used. If sound device is currently active, the method will forward the request to the sound device. If sound device is currently inactive, and if application had previously set the setting and mark the setting as kept, then that setting will be returned. Otherwise, this method will raise error.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_CNG capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Returns

The audio comfort noise generation feature.

void setPlc (bool enable, bool keep=true) PJSUA2_THROW(Error)

This will configure audio packet loss concealment capability to the sound device being used. If sound device is currently active, the method will forward the setting to the sound device instance to be applied immediately, if it supports it.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_PLC capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Note that in case the setting is kept for future use, it will be applied to any devices, even when application has changed the sound device to be used.

Parameters
  • enable – Enable/disable packet loss concealment feature. Set true to enable.

  • keep – Specify whether the setting is to be kept for future use.

bool getPlc () const PJSUA2_THROW(Error)

Get the audio packet loss concealment capability of the sound device being used. If sound device is currently active, the method will forward the request to the sound device. If sound device is currently inactive, and if application had previously set the setting and mark the setting as kept, then that setting will be returned. Otherwise, this method will raise error.

This method is only valid if the device has PJMEDIA_AUD_DEV_CAP_PLC capability in AudioDevInfo.caps flags, otherwise Error will be thrown.

Returns

The audio packet loss concealment feature.

Device Info

struct AudioDevInfo

Audio device information structure.

Public Functions

void fromPj(const pjmedia_aud_dev_info &dev_info)

Construct from pjmedia_aud_dev_info.

~AudioDevInfo()

Destructor.

Public Members

string name

The device name

unsigned inputCount

Maximum number of input channels supported by this device. If the value is zero, the device does not support input operation (i.e. it is a playback only device).

unsigned outputCount

Maximum number of output channels supported by this device. If the value is zero, the device does not support output operation (i.e. it is an input only device).

unsigned defaultSamplesPerSec

Default sampling rate.

string driver

The underlying driver name

unsigned caps

Device capabilities, as bitmask combination of pjmedia_aud_dev_cap.

unsigned routes

Supported audio device routes, as bitmask combination of pjmedia_aud_dev_route. The value may be zero if the device does not support audio routing.

MediaFormatAudioVector extFmt

Array of supported extended audio formats