mirrors
/
pjsip-pjproject
mirror of https://github.com/pjsip/pjproject.git
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
pjsip-pjproject/pjsip/include/pjsua2/media.hpp

2805 lines
87 KiB
C++
Raw Permalink Blame History

/*
* Copyright (C) 2013 Teluu Inc. (http://www.teluu.com)
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; either version 2 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
#ifndef __PJSUA2_MEDIA_HPP__
#define __PJSUA2_MEDIA_HPP__
/**
* @file pjsua2/media.hpp
* @brief PJSUA2 media operations
*/
#include <pjsua-lib/pjsua.h>
#include <pjsua2/types.hpp>
/** PJSUA2 API is inside pj namespace */
namespace pj
{
/**
* @defgroup PJSUA2_MED Media
* @ingroup PJSUA2_Ref
* @{
*/
using std::string;
using std::vector;
/**
* This structure contains all the information needed to completely describe
* a media.
*/
struct MediaFormat
{
/**
* The format id that specifies the audio sample or video pixel format.
* Some well known formats ids are declared in pjmedia_format_id
* enumeration.
*
* @see pjmedia_format_id
*/
pj_uint32_t id;
/**
* The top-most type of the media, as an information.
*/
pjmedia_type type;
public:
/**
* Default constructor
*/
MediaFormat() : id(0), type(PJMEDIA_TYPE_NONE)
{}
};
/**
* This structure describe detail information about an audio media.
*/
struct MediaFormatAudio : public MediaFormat
{
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 */
/**
* Construct from pjmedia_format.
*/
void fromPj(const pjmedia_format &format);
/**
* Export to pjmedia_format.
*/
pjmedia_format toPj() const;
public:
/**
* Default constructor
*/
MediaFormatAudio() : clockRate(0), channelCount(0), frameTimeUsec(0),
bitsPerSample(0), avgBps(0), maxBps(0)
{}
/**
* Initialization
*/
void init(pj_uint32_t formatId, unsigned clockRate, unsigned channelCount,
int frameTimeUsec, int bitsPerSample,
pj_uint32_t avgBps=0, pj_uint32_t maxBps=0);
};
/**
* This structure describe detail information about an video media.
*/
struct MediaFormatVideo : public MediaFormat
{
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. */
/**
* Construct from pjmedia_format.
*/
void fromPj(const pjmedia_format &format);
/**
* Export to pjmedia_format.
*/
pjmedia_format toPj() const;
public:
/**
* Default constructor
*/
MediaFormatVideo() : width(0), height(0), fpsNum(0),
fpsDenum(1), avgBps(0), maxBps(0)
{}
/**
* Initialization
*/
void init(pj_uint32_t formatId, unsigned width, unsigned height,
int fpsNum, int fpsDenum=1,
pj_uint32_t avgBps=0, pj_uint32_t maxBps=0);
};
/** Array of MediaFormatAudio */
typedef std::vector<MediaFormatAudio> MediaFormatAudioVector;
/** Array of MediaFormatVideo */
typedef std::vector<MediaFormatVideo> MediaFormatVideoVector;
/**
* This structure descibes information about a particular media port that
* has been registered into the conference bridge.
*/
struct ConfPortInfo
{
/**
* Conference port number.
*/
int portId;
/**
* Port name.
*/
string name;
/**
* Media audio format information
*/
MediaFormatAudio format;
/**
* 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 txLevelAdj;
/**
* 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.
*/
float rxLevelAdj;
/**
* Array of listeners (in other words, ports where this port is
* transmitting to).
*/
IntVector listeners;
public:
/**
* Construct from pjsua_conf_port_info.
*/
void fromPj(const pjsua_conf_port_info &port_info);
};
/**
* Media port, corresponds to pjmedia_port
*/
typedef void *MediaPort;
/**
* Media.
*/
class Media
{
public:
/**
* Virtual destructor.
*/
virtual ~Media();
/**
* Get type of the media.
*
* @return The media type.
*/
pjmedia_type getType() const;
protected:
/**
* Constructor.
*/
Media(pjmedia_type med_type);
private:
/**
* Media type.
*/
pjmedia_type type;
};
/**
* Parameters for AudioMedia::startTransmit2() method.
*/
struct AudioMediaTransmitParam
{
/**
* Signal level adjustment. Value 1.0 means no level adjustment,
* while value 0 means to mute the port.
*
* Default: 1.0
*/
float level;
public:
/**
* Default constructor
*/
AudioMediaTransmitParam();
};
/**
* 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.
*/
class AudioMedia : public Media
{
public:
/**
* Get information about the specified conference port.
*/
ConfPortInfo getPortInfo() const PJSUA2_THROW(Error);
/**
* Get port Id.
*/
int getPortId() const;
/**
* Get information from specific port id.
*/
static ConfPortInfo getPortInfoFromId(int port_id) 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.
*
* @param sink The destination Media.
*/
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.
*
* 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.
*
* @param sink The destination Media.
* @param param The parameter.
*/
void startTransmit2(const AudioMedia &sink,
const AudioMediaTransmitParam &param) const
PJSUA2_THROW(Error);
/**
* Stop media flow to destination/sink port.
*
* @param sink The destination media.
*
*/
void stopTransmit(const AudioMedia &sink) const PJSUA2_THROW(Error);
/**
* Adjust the signal level to be transmitted from the bridge to this
* media port by making it louder or quieter.
*
* @param level Signal level adjustment. Value 1.0 means no
* level adjustment, while value 0 means to mute
* the port.
*/
void adjustRxLevel(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.
*
* @param 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);
/**
* Get the last received signal level.
*
* @return Signal level in percent.
*/
unsigned getRxLevel() const PJSUA2_THROW(Error);
/**
* Get the last transmitted signal level.
*
* @return Signal level in percent.
*/
unsigned getTxLevel() const PJSUA2_THROW(Error);
/**
* 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.
*
* @param media The object to be downcasted
*
* @return The object as AudioMedia instance
*/
static AudioMedia* typecastFromMedia(Media *media);
/**
* 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.
*/
AudioMedia();
/**
* Virtual Destructor.
*/
virtual ~AudioMedia();
protected:
/**
* Conference port Id.
*/
int id;
protected:
/**
* Warning: deprecated and will be removed in future release, use
* registerMediaPort2() instead.
*
* This method needs to be called by descendants of this class to register
* the media port created to the conference bridge and Endpoint's
* media list.
*
* param port The media port to be registered to the conference bridge.
*
*/
void registerMediaPort(MediaPort port) PJSUA2_THROW(Error);
/**
* This method needs to be called by descendants of this class to register
* the media port created to the conference bridge and Endpoint's
* media list.
*
* param port The media port to be registered to the conference bridge.
* param pool The memory pool.
*
*/
void registerMediaPort2(MediaPort port, pj_pool_t *pool)
PJSUA2_THROW(Error);
/**
* This method needs to be called by descendants of this class to remove
* the media port from the conference bridge and Endpoint's media list.
* Descendant should only call this method if it has registered the media
* with the previous call to registerMediaPort().
*/
void unregisterMediaPort() PJSUA2_THROW(Error);
private:
/* Memory pool for deprecated registerMediaPort() */
pj_caching_pool mediaCachingPool;
pj_pool_t *mediaPool;
};
/**
* Warning: deprecated, use AudioMediaVector2 instead.
*
* Array of Audio Media.
*/
typedef std::vector<AudioMedia*> AudioMediaVector;
/** Array of Audio Media */
typedef std::vector<AudioMedia> AudioMediaVector2;
/**
* This structure describes a media frame.
*/
struct MediaFrame
{
pjmedia_frame_type type; /**< Frame type. */
ByteVector buf; /**< Frame buffer content. */
unsigned size; /**< Frame size in bytes. */
public:
/**
* Default constructor
*/
MediaFrame()
: type(PJMEDIA_FRAME_TYPE_NONE),
size(0)
{}
};
/**
* Audio Media Port.
*/
class AudioMediaPort : public AudioMedia
{
public:
/**
* Constructor.
*/
AudioMediaPort();
/**
* Destructor. This will unregister the audio media port from the
* conference bridge.
*/
virtual ~AudioMediaPort();
/**
* Create an audio media port and register it to the conference bridge.
*
* @param name The port name.
* @param fmt The audio format.
*/
void createPort(const string &name, MediaFormatAudio &fmt)
PJSUA2_THROW(Error);
/*
* Callbacks
*/
/**
* This callback is called to request a frame from this port. On input,
* frame.size indicates the capacity of the frame buffer and frame.buf
* will initially be an empty vector. Application can then set the frame
* type and fill the vector.
*
* @param frame The frame.
*/
virtual void onFrameRequested(MediaFrame &frame)
{ PJ_UNUSED_ARG(frame); }
/**
* This callback is called when this port receives a frame. The frame
* content will be provided in frame.buf vector, and the frame size
* can be found in either frame.size or the vector's size (both
* have the same value).
*
* @param frame The frame.
*/
virtual void onFrameReceived(MediaFrame &frame)
{ PJ_UNUSED_ARG(frame); }
private:
pj_pool_t *pool;
pjmedia_port port;
};
/**
* This structure contains additional info about AudioMediaPlayer.
*/
struct AudioMediaPlayerInfo
{
/**
* Format ID of the payload.
*/
pjmedia_format_id formatId;
/**
* The number of bits per sample of the file payload. For example,
* the value is 16 for PCM WAV and 8 for Alaw/Ulas WAV files.
*/
unsigned payloadBitsPerSample;
/**
* The WAV payload size in bytes.
*/
pj_uint32_t sizeBytes;
/**
* The WAV payload size in samples.
*/
pj_uint32_t sizeSamples;
public:
/**
* Default constructor
*/
AudioMediaPlayerInfo()
: formatId(PJMEDIA_FORMAT_L16),
payloadBitsPerSample(0),
sizeBytes(0),
sizeSamples(0)
{}
};
/**
* Audio Media Player.
*/
class AudioMediaPlayer : public AudioMedia
{
public:
/**
* Constructor.
*/
AudioMediaPlayer();
/**
* Create a file player, and automatically add this
* player to the conference bridge.
*
* @param 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).
* @param options Optional option flag. Application may specify
* PJMEDIA_FILE_NO_LOOP to prevent playback loop.
*/
void createPlayer(const string &file_name,
unsigned options=0) PJSUA2_THROW(Error);
/**
* Create a file playlist media port, and automatically add the port
* to the conference bridge.
*
* @param 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.
* @param label Optional label to be set for the media port.
* @param options Optional option flag. Application may specify
* PJMEDIA_FILE_NO_LOOP to prevent looping.
*/
void createPlaylist(const StringVector &file_names,
const string &label="",
unsigned options=0) PJSUA2_THROW(Error);
/**
* Get additional info about the player. This operation is only valid
* for player. For playlist, Error will be thrown.
*
* @return the info.
*/
AudioMediaPlayerInfo getInfo() const PJSUA2_THROW(Error);
/**
* Get current playback position in samples. This operation is not valid
* for playlist.
*
* @return Current playback position, in samples.
*/
pj_uint32_t getPos() const PJSUA2_THROW(Error);
/**
* Set playback position in samples. This operation is not valid for
* playlist.
*
* @param samples The desired playback position, in samples.
*/
void setPos(pj_uint32_t samples) PJSUA2_THROW(Error);
/**
* 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.
*
* @param media The object to be downcasted
*
* @return The object as AudioMediaPlayer instance
*/
static AudioMediaPlayer* typecastFromAudioMedia(AudioMedia *media);
/**
* Destructor. This will unregister the player port from the conference
* bridge.
*/
virtual ~AudioMediaPlayer();
public:
/*
* Callbacks
*/
/* Unfortunately for pjsua2, a hard deprecation is inevitable. */
#if 0 // !DEPRECATED_FOR_TICKET_2251
/**
* 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.
*
* @return If the callback returns false, the playback
* will stop. Note that if application destroys
* the player in the callback, it must return
* false here.
*/
virtual bool onEof()
{ return true; }
#endif
/**
* 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.
*/
virtual void onEof2()
{ }
private:
/**
* Player Id.
*/
int playerId;
/**
* Low level PJMEDIA callback
*/
static void eof_cb(pjmedia_port *port,
void *usr_data);
};
/**
* Audio Media Recorder.
*/
class AudioMediaRecorder : public AudioMedia
{
public:
/**
* Constructor.
*/
AudioMediaRecorder();
/**
* 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").
*
* @param 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.
* @param 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.
* @param max_size Maximum file size. Specify zero or -1 to remove size
* limitation. This value must be zero or -1 for now.
* @param 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.
*/
void createRecorder(const string &file_name,
unsigned enc_type=0,
long max_size=0,
unsigned options=0) PJSUA2_THROW(Error);
/**
* 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.
*
* @param media The object to be downcasted
*
* @return The object as AudioMediaRecorder instance
*/
static AudioMediaRecorder* typecastFromAudioMedia(AudioMedia *media);
/**
* Destructor. This will unregister the recorder port from the conference
* bridge.
*/
virtual ~AudioMediaRecorder();
private:
/**
* Recorder Id.
*/
int recorderId;
};
/**
* Tone descriptor (abstraction for pjmedia_tone_desc)
*/
class ToneDesc : public pjmedia_tone_desc
{
public:
ToneDesc()
{
pj_bzero(this, sizeof(*this));
}
~ToneDesc() {}
};
/**
* Array of tone descriptor.
*/
typedef std::vector<ToneDesc> ToneDescVector;
/**
* Tone digit (abstraction for pjmedia_tone_digit)
*/
class ToneDigit : public pjmedia_tone_digit
{
public:
ToneDigit()
{
pj_bzero(this, sizeof(*this));
}
~ToneDigit() {}
};
/**
* Array of tone digits.
*/
typedef std::vector<ToneDigit> ToneDigitVector;
/**
* A digit in tone digit map
*/
struct ToneDigitMapDigit
{
public:
string digit; /**< the digit */
int freq1; /**< first frequency */
int freq2; /**< second frequency */
};
/**
* Tone digit map
*/
typedef std::vector<ToneDigitMapDigit> ToneDigitMapVector;
/**
* Tone generator.
*/
class ToneGenerator : public AudioMedia
{
public:
/**
* Constructor.
*/
ToneGenerator();
/**
* Destructor. This will unregister the tone generator port from the
* conference bridge.
*/
~ToneGenerator();
/**
* Create tone generator and register the port to the conference bridge.
*/
void createToneGenerator(unsigned clock_rate = 16000,
unsigned channel_count = 1) PJSUA2_THROW(Error);
/**
* Check if the tone generator is still busy producing some tones.
* @return Non-zero if busy.
*/
bool isBusy() const;
/**
* Instruct the tone generator to stop current processing.
*/
void stop() PJSUA2_THROW(Error);
/**
* Rewind the playback. This will start the playback to the first
* tone in the playback list.
*/
void rewind() PJSUA2_THROW(Error);
/**
* Instruct the tone generator to play single or dual frequency tones
* with the specified duration. The new tones will be appended to
* currently playing tones, unless stop() is called before calling this
* function. The playback will begin as soon as the tone generator is
* connected to other media.
*
* @param tones Array of tones to be played.
* @param loop Play the tone in a loop.
*/
void play(const ToneDescVector &tones,
bool loop=false) PJSUA2_THROW(Error);
/**
* Instruct the tone generator to play multiple MF digits with each of
* the digits having individual ON/OFF duration. Each of the digit in the
* digit array must have the corresponding descriptor in the digit map.
* The new tones will be appended to currently playing tones, unless
* stop() is called before calling this function. The playback will begin
* as soon as the tone generator is connected to a sink media.
*
* @param digits Array of MF digits.
* @param loop Play the tone in a loop.
*/
void playDigits(const ToneDigitVector &digits,
bool loop=false) PJSUA2_THROW(Error);
/**
* Get the digit-map currently used by this tone generator.
*
* @return The digitmap currently used by the tone generator
*/
ToneDigitMapVector getDigitMap() const PJSUA2_THROW(Error);
/**
* Set digit map to be used by the tone generator.
*
* @param digit_map Digitmap to be used by the tone generator.
*/
void setDigitMap(const ToneDigitMapVector &digit_map) PJSUA2_THROW(Error);
private:
pj_pool_t *pool;
pjmedia_port *tonegen;
pjmedia_tone_digit_map digitMap;
};
/*************************************************************************
* Sound device management
*/
/**
* Audio device information structure.
*/
struct AudioDevInfo
{
/**
* The device ID
*/
pjmedia_aud_dev_index id;
/**
* The device name
*/
string name;
/**
* 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 inputCount;
/**
* 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 outputCount;
/**
* Default sampling rate.
*/
unsigned defaultSamplesPerSec;
/**
* The underlying driver name
*/
string driver;
/**
* Device capabilities, as bitmask combination of pjmedia_aud_dev_cap.
*/
unsigned caps;
/**
* 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.
*/
unsigned routes;
/**
* Array of supported extended audio formats
*/
MediaFormatAudioVector extFmt;
/**
* Construct from pjmedia_aud_dev_info.
*/
void fromPj(const pjmedia_aud_dev_info &dev_info);
/**
* Destructor.
*/
~AudioDevInfo();
};
/**
* Warning: deprecated, use AudioDevInfoVector2 instead.
*
* Array of audio device info.
*/
typedef std::vector<AudioDevInfo*> AudioDevInfoVector;
/** Array of audio device info */
typedef std::vector<AudioDevInfo> AudioDevInfoVector2;
/**
* Audio device manager.
*/
class AudDevManager
{
public:
/**
* Get currently active capture sound devices. If sound devices has not been
* created, it is possible that the function returns -1 as device IDs.
*
* @return Device ID of the capture device.
*/
int getCaptureDev() const PJSUA2_THROW(Error);
/**
* Get the AudioMedia of the capture audio device.
*
* @return Audio media for the capture device.
*/
AudioMedia &getCaptureDevMedia() 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.
*
* @return Device ID of the playback device.
*/
int getPlaybackDev() const PJSUA2_THROW(Error);
/**
* Get the AudioMedia of the speaker/playback audio device.
*
* @return Audio media for the speaker/playback device.
*/
AudioMedia &getPlaybackDevMedia() 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).
*
* @param capture_dev Device ID of the capture device.
*/
void setCaptureDev(int capture_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).
*
* @param playback_dev Device ID of the playback device.
*/
void setPlaybackDev(int playback_dev) const PJSUA2_THROW(Error);
#if !DEPRECATED_FOR_TICKET_2232
/**
* 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.
*
* @return The list of audio device info.
*/
const AudioDevInfoVector &enumDev() PJSUA2_THROW(Error);
#endif
/**
* Enum all audio devices installed in the system.
*
* @return The list of audio device info.
*/
AudioDevInfoVector2 enumDev2() const 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.
*
*/
void setNullDev() PJSUA2_THROW(Error);
/**
* Disconnect the main conference bridge from any sound devices, and let
* application connect the bridge to it's own sound device/master port.
*
* @return The port interface of the conference bridge,
* so that application can connect this to it's
* own sound device or master port.
*/
MediaPort *setNoDev();
/**
* Set sound device mode.
*
* Note that this method will open the sound device, using current
* active IDs set via setCaptureDev() or setPlaybackDev(), if the flag
* PJSUA_SND_DEV_NO_IMMEDIATE_OPEN is not specified.
*
* @param mode The sound device mode, as bitmask combination
* of #pjsua_snd_dev_mode
*
*/
void setSndDevMode(unsigned mode) const 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.
*
* @param tail_msec The tail length, in miliseconds. Set to zero to
* disable AEC.
* @param options Options to be passed to pjmedia_echo_create().
* Normally the value should be zero.
*
*/
void setEcOptions(unsigned tail_msec, unsigned options) PJSUA2_THROW(Error);
/**
* Get current echo canceller tail length.
*
* @return The EC tail length in milliseconds,
* If AEC is disabled, the value will be zero.
*/
unsigned getEcTail() const PJSUA2_THROW(Error);
/**
* 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.
*/
bool sndIsActive() const;
/**
* 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.
*
*/
void refreshDevs() PJSUA2_THROW(Error);
/**
* Get the number of sound devices installed in the system.
*
* @return The number of sound devices installed in the
* system.
*
*/
unsigned getDevCount() const;
/**
* Get device information.
*
* @param id The audio device ID.
*
* @return The device information which will be filled in
* by this method once it returns successfully.
*/
AudioDevInfo getDevInfo(int id) const PJSUA2_THROW(Error);
/**
* Lookup device index based on the driver and device name.
*
* @param drv_name The driver name.
* @param dev_name The device name.
*
* @return The device ID. If the device is not found,
* Error will be thrown.
*/
int lookupDev(const string &drv_name,
const string &dev_name) const PJSUA2_THROW(Error);
/**
* Get string info for the specified capability.
*
* @param cap The capability ID.
*
* @return Capability name.
*/
string capName(pjmedia_aud_dev_cap cap) const;
/**
* 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.
*
* @param format The audio format.
* @param keep Specify whether the setting is to be kept for
* future use.
*
*/
void setExtFormat(const MediaFormatAudio &format, bool keep=true)
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.
*
* @return The audio format.
*
*/
MediaFormatAudio getExtFormat() const 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.
*
* @param latency_msec The input latency.
* @param keep Specify whether the setting is to be kept
* for future use.
*/
void
setInputLatency(unsigned latency_msec, bool keep=true) 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.
*
* @return The audio input latency.
*
*/
unsigned getInputLatency() const 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.
*
* @param latency_msec The output latency.
* @param keep Specify whether the setting is to be kept
* for future use.
*
*/
void
setOutputLatency(unsigned latency_msec, bool keep=true) 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.
*
* @return The audio output latency.
*
*/
unsigned getOutputLatency() const 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.
*
* @param volume The input volume level, in percent.
* @param keep Specify whether the setting is to be kept for
* future use.
*
*/
void setInputVolume(unsigned volume, bool keep=true) 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. *
* @return The audio input volume level, in percent.
*
*/
unsigned getInputVolume() const 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.
*
* @param volume The output volume level, in percent.
* @param keep Specify whether the setting is to be kept
* for future use.
*
*/
void setOutputVolume(unsigned volume, bool keep=true) 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.
*
* @return The audio output volume level, in percent.
*
*/
unsigned getOutputVolume() 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.
*
* @return The audio input signal level, in percent.
*
*/
unsigned getInputSignal() 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.
*
* @return The audio output signal level, in percent.
*
*/
unsigned getOutputSignal() const 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.
*
* @param route The audio input route.
* @param keep Specify whether the setting is to be kept
* for future use.
*
*/
void setInputRoute(pjmedia_aud_dev_route route, bool keep=true)
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.
*
* @return The audio input route.
*
*/
pjmedia_aud_dev_route getInputRoute() const 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.
*
* @param route The audio output route.
* @param keep Specify whether the setting is to be kept
* for future use.
*
*/
void setOutputRoute(pjmedia_aud_dev_route route, bool keep=true)
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.
*
* @return The audio output route.
*
*/
pjmedia_aud_dev_route getOutputRoute() const 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.
*
* @param enable Enable/disable voice activity detection
* feature. Set true to enable.
* @param keep Specify whether the setting is to be kept for
* future use.
*
*/
void setVad(bool enable, bool keep=true) 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.
*
* @return The audio voice activity detection feature.
*
*/
bool getVad() const 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.
*
* @param enable Enable/disable comfort noise generation
* feature. Set true to enable.
* @param keep Specify whether the setting is to be kept for
* future use.
*
*/
void setCng(bool enable, bool keep=true) 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.
*
* @return The audio comfort noise generation feature.
*
*/
bool getCng() const 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.
*
* @param enable Enable/disable packet loss concealment
* feature. Set true to enable.
* @param keep Specify whether the setting is to be kept for
* future use.
*
*/
void setPlc(bool enable, bool keep=true) 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.
*
* @return The audio packet loss concealment feature.
*
*/
bool getPlc() const PJSUA2_THROW(Error);
private:
#if !DEPRECATED_FOR_TICKET_2232
AudioDevInfoVector audioDevList;
#endif
AudioMedia *devMedia;
/**
* Constructor.
*/
AudDevManager();
/**
* Destructor.
*/
~AudDevManager();
void clearAudioDevList();
int getActiveDev(bool is_capture) const PJSUA2_THROW(Error);
friend class Endpoint;
};
/**
* Extra audio device. This class allows application to have multiple
* sound device instances active concurrently.
* Application may also use this class to improve media clock. Normally
* media clock is driven by sound device in master port, but unfortunately
* some sound devices may produce jittery clock. To improve media clock,
* application can install Null Sound Device (i.e: using
* AudDevManager::setNullDev()), which will act as a master port, and
* install the sound device as extra sound device.
*
* Note that extra sound device will not have auto-close upon idle feature.
* Also note that the extra sound device only supports mono channel.
*/
class ExtraAudioDevice : public AudioMedia
{
public:
/**
* Constructor.
*
* @param playdev Playback device ID.
* @param recdev Record device ID.
*/
ExtraAudioDevice(int playdev, int recdev);
/**
* Destructor.
*/
virtual ~ExtraAudioDevice();
/**
* Open the audio device using format (e.g.: clock rate, bit per sample,
* samples per frame) matched to the conference bridge's format, except
* the channel count, which will be set to one (mono channel). This will
* also register the audio device port to conference bridge.
*/
void open();
/**
* Close the audio device and unregister the audio device port from the
* conference bridge.
*/
void close() PJSUA2_THROW(Error);
/**
* Is the extra audio device opened?
*
* @return 'true' if it is opened.
*/
bool isOpened();
protected:
int playDev;
int recDev;
void *ext_snd_dev;
};
/*************************************************************************
* Video media
*/
/**
* Representation of media coordinate.
*/
struct MediaCoordinate
{
int x; /**< X position of the coordinate */
int y; /**< Y position of the coordinate */
};
/**
* Representation of media size.
*/
struct MediaSize
{
unsigned w; /**< The width. */
unsigned h; /**< The height. */
};
/**
* This structure descibes information about a particular media port that
* has been registered into the conference bridge.
*/
struct VidConfPortInfo
{
/**
* Conference port number.
*/
int portId;
/**
* Port name.
*/
string name;
/**
* Media audio format information
*/
MediaFormatVideo format;
/**
* Array of listeners (in other words, ports where this port is
* transmitting to).
*/
IntVector listeners;
/**
* Array of listeners (in other words, ports where this port is
* listening to).
*/
IntVector transmitters;
public:
/**
* Construct from pjsua_conf_port_info.
*/
void fromPj(const pjsua_vid_conf_port_info &port_info);
};
/**
* Parameters for VideoMedia::startTransmit() method.
*/
struct VideoMediaTransmitParam
{
};
/**
* Video Media.
*/
class VideoMedia : public Media
{
public:
/**
* Get information about the specified conference port.
*/
VidConfPortInfo getPortInfo() const PJSUA2_THROW(Error);
/**
* Get port Id.
*/
int getPortId() const;
/**
* Get information from specific port id.
*/
static VidConfPortInfo getPortInfoFromId(int port_id) 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.
*
* @param sink The destination Media.
* @param param The parameter.
*/
void startTransmit(const VideoMedia &sink,
const VideoMediaTransmitParam &param) const
PJSUA2_THROW(Error);
/**
* Stop media flow to destination/sink port.
*
* @param sink The destination media.
*
*/
void stopTransmit(const VideoMedia &sink) const PJSUA2_THROW(Error);
/**
* Update or refresh port states from video port info. Some port may
* change its port info in the middle of a session, for example when
* a video stream decoder learns that incoming video size or frame rate
* has changed, video conference needs to be informed to update its
* internal states.
*
*/
void update() const PJSUA2_THROW(Error);
/**
* Default Constructor.
*
* Normally application will not create VideoMedia object directly,
* but it instantiates a VideoMedia derived class. This is set as public
* because some STL vector implementations require it.
*/
VideoMedia();
/**
* Virtual Destructor
*/
virtual ~VideoMedia();
protected:
/**
* Conference port Id.
*/
int id;
protected:
/**
* This method needs to be called by descendants of this class to register
* the media port created to the conference bridge and Endpoint's
* media list.
*
* param port The media port to be registered to the conference bridge.
* param pool The memory pool.
*/
void registerMediaPort(MediaPort port, pj_pool_t *pool) PJSUA2_THROW(Error);
/**
* This method needs to be called by descendants of this class to remove
* the media port from the conference bridge and Endpoint's media list.
* Descendant should only call this method if it has registered the media
* with the previous call to registerMediaPort().
*/
void unregisterMediaPort();
};
/** Array of Video Media */
typedef std::vector<VideoMedia> VideoMediaVector;
/**
* Window handle.
*/
typedef struct WindowHandle {
void *window; /**< Window */
void *display; /**< Display */
} WindowHandle;
/**
* Video window handle.
*/
struct VideoWindowHandle
{
/**
* The window handle type.
*/
pjmedia_vid_dev_hwnd_type type;
/**
* The window handle.
*/
WindowHandle handle;
};
/**
* This structure describes video window info.
*/
typedef struct VideoWindowInfo
{
/**
* Flag to indicate whether this window is a native window,
* such as created by built-in preview device. If this field is
* true, only the video window handle field of this
* structure is valid.
*/
bool isNative;
/**
* Video window handle.
*/
VideoWindowHandle winHandle;
/**
* Renderer device ID.
*/
int renderDeviceId;
/**
* Window show status. The window is hidden if false.
*/
bool show;
/**
* Window position.
*/
MediaCoordinate pos;
/**
* Window size.
*/
MediaSize size;
} VideoWindowInfo;
/**
* Video window.
*/
class VideoWindow
{
public:
/**
* Constructor
*/
VideoWindow(int win_id);
/**
* Get window info.
*
* @return video window info.
*/
VideoWindowInfo getInfo() const PJSUA2_THROW(Error);
/**
* Get video media or conference bridge port of the renderer of
* this video window.
*
* @return Video media of this renderer window.
*/
VideoMedia getVideoMedia() PJSUA2_THROW(Error);
/**
* Show or hide window. This operation is not valid for native windows
* (VideoWindowInfo.isNative=true), on which native windowing API
* must be used instead.
*
* @param show Set to true to show the window, false to
* hide the window.
*
*/
void Show(bool show) PJSUA2_THROW(Error);
/**
* Set video window position. This operation is not valid for native windows
* (VideoWindowInfo.isNative=true), on which native windowing API
* must be used instead.
*
* @param pos The window position.
*
*/
void setPos(const MediaCoordinate &pos) PJSUA2_THROW(Error);
/**
* Resize window. This operation is not valid for native windows
* (VideoWindowInfo.isNative=true), on which native windowing API
* must be used instead.
*
* @param size The new window size.
*
*/
void setSize(const MediaSize &size) PJSUA2_THROW(Error);
/**
* Rotate the video window. This function will change the video orientation
* and also possibly the video window size (width and height get swapped).
* This operation is not valid for native windows (VideoWindowInfo.isNative
* =true), on which native windowing API must be used instead.
*
* @param angle The rotation angle in degrees, must be
* multiple of 90.
* Specify positive value for clockwise rotation or
* negative value for counter-clockwise rotation.
*/
void rotate(int angle) PJSUA2_THROW(Error);
/**
* Set output window. This operation is valid only when the underlying
* video device supports PJMEDIA_VIDEO_DEV_CAP_OUTPUT_WINDOW capability AND
* allows the output window to be changed on-the-fly, otherwise Error will
* be thrown. Currently it is only supported on Android.
*
* @param win The new output window.
*/
void setWindow(const VideoWindowHandle &win) PJSUA2_THROW(Error);
/**
* Set video window full-screen. This operation is valid only when the
* underlying video device supports PJMEDIA_VID_DEV_CAP_OUTPUT_FULLSCREEN
* capability. Currently it is only supported on SDL backend.
*
* @param enabled Set to true if full screen is desired, false
* otherwise.
*/
void setFullScreen(bool enabled) PJSUA2_THROW(Error);
/**
* Set video window full-screen. This operation is valid only when the
* underlying video device supports PJMEDIA_VID_DEV_CAP_OUTPUT_FULLSCREEN
* capability. Currently it is only supported on SDL backend.
*
* @param mode Fullscreen mode, see
* pjmedia_vid_dev_fullscreen_flag.
*/
void setFullScreen2(pjmedia_vid_dev_fullscreen_flag mode)
PJSUA2_THROW(Error);
private:
pjsua_vid_win_id winId;
};
/**
* This structure contains parameters for VideoPreview::start()
*/
struct VideoPreviewOpParam {
/**
* Device ID for the video renderer to be used for rendering the
* capture stream for preview. This parameter is ignored if native
* preview is being used.
*
* Default: PJMEDIA_VID_DEFAULT_RENDER_DEV
*/
pjmedia_vid_dev_index rendId;
/**
* Show window initially.
*
* Default: PJ_TRUE.
*/
bool show;
/**
* Window flags. The value is a bitmask combination of
* \a pjmedia_vid_dev_wnd_flag.
*
* Default: 0.
*/
unsigned windowFlags;
/**
* Media format video. By default, this parameter is uninitialized
* and will not be used.
*
* To initialize it, use MediaFormatVideo::init().
* If left uninitialized, the capture device will be opened using
* PJMEDIA wrapper default format, e.g:
* - Android : PJMEDIA_FORMAT_I420 using the first supported size and 15fps
* - iOS : PJMEDIA_FORMAT_BGRA using size 352x288 and 15fps
* Note that when the preview is already opened, this setting will be
* ignored.
*/
MediaFormatVideo format;
/**
* Optional output window to be used to display the video preview.
* This parameter will only be used if the video device supports
* PJMEDIA_VID_DEV_CAP_OUTPUT_WINDOW capability and the capability
* is not read-only.
*/
VideoWindowHandle window;
public:
/**
* Default constructor initializes with default values.
*/
VideoPreviewOpParam();
/**
* Convert from pjsip
*/
void fromPj(const pjsua_vid_preview_param &prm);
/**
* Convert to pjsip
*/
pjsua_vid_preview_param toPj() const;
};
/**
* Video Preview
*/
class VideoPreview {
public:
/**
* Constructor
*/
VideoPreview(int dev_id);
/**
* Determine if the specified video input device has built-in native
* preview capability. This is a convenience function that is equal to
* querying device's capability for PJMEDIA_VID_DEV_CAP_INPUT_PREVIEW
* capability.
*
* @return true if it has.
*/
bool hasNative();
/**
* Start video preview window for the specified capture device.
*
* @param param Video preview parameters.
*/
void start(const VideoPreviewOpParam &param) PJSUA2_THROW(Error);
/**
* Stop video preview.
*/
void stop() PJSUA2_THROW(Error);
/**
* Get the preview window handle associated with the capture device,if any.
*/
VideoWindow getVideoWindow();
/**
* Get video media or conference bridge port of the video capture device.
*
* @return Video media of the video capture device.
*/
VideoMedia getVideoMedia() PJSUA2_THROW(Error);
private:
pjmedia_vid_dev_index devId;
pjsua_vid_win_id winId;
void updateDevId();
};
/**
* Video device information structure.
*/
struct VideoDevInfo
{
/**
* The device ID
*/
pjmedia_vid_dev_index id;
/**
* The device name
*/
string name;
/**
* The underlying driver name
*/
string driver;
/**
* The supported direction of the video device, i.e. whether it supports
* capture only, render only, or both.
*/
pjmedia_dir dir;
/**
* Device capabilities, as bitmask combination of #pjmedia_vid_dev_cap
*/
unsigned caps;
/**
* Array of supported video formats. Some fields in each supported video
* format may be set to zero or of "unknown" value, to indicate that the
* value is unknown or should be ignored. When these value are not set
* to zero, it indicates that the exact format combination is being used.
*/
MediaFormatVideoVector fmt;
public:
/**
* Default constructor
*/
VideoDevInfo() : id(-1), dir(PJMEDIA_DIR_NONE), caps(0)
{}
/**
* Construct from pjmedia_vid_dev_info.
*/
void fromPj(const pjmedia_vid_dev_info &dev_info);
/**
* Destructor.
*/
~VideoDevInfo();
};
/**
* Warning: deprecated, use VideoDevInfoVector2 instead.
*
* Array of video device info.
*/
typedef std::vector<VideoDevInfo*> VideoDevInfoVector;
/** Array of video device info */
typedef std::vector<VideoDevInfo> VideoDevInfoVector2;
/**
* Parameter for switching device with PJMEDIA_VID_DEV_CAP_SWITCH capability.
*/
struct VideoSwitchParam
{
/**
* Target device ID to switch to. Once the switching is successful, the
* video stream will use this device and the old device will be closed.
*/
pjmedia_vid_dev_index target_id;
};
/**
* Video device manager.
*/
class VidDevManager {
public:
/**
* Initialize the video device subsystem. This will register all supported
* video device factories to the video device subsystem.
*
* By default, library will initialize video device subsystem automatically
* on library initialization, so application will never need to invoke this
* function. However, when PJSUA_DONT_INIT_VID_DEV_SUBSYS is set to
* non-zero, application should invoke this function before accessing
* video device.
*/
void initSubsys() PJSUA2_THROW(Error);
/**
* Refresh the list of video devices installed in the system. This function
* will only refresh the list of video device so all active video streams
* will be unaffected. After refreshing the device list, application MUST
* make sure to update all index references to video devices (i.e. all
* variables of type pjmedia_vid_dev_index) before calling any function
* that accepts video device index as its parameter.
*/
void refreshDevs() PJSUA2_THROW(Error);
/**
* Get the number of video devices installed in the system.
*
* @return The number of devices.
*/
unsigned getDevCount();
/**
* Retrieve the video device info for the specified device index.
*
* @param dev_id The video device id
*
* @return The list of video device info
*/
VideoDevInfo getDevInfo(int dev_id) const PJSUA2_THROW(Error);
#if !DEPRECATED_FOR_TICKET_2232
/**
* Warning: deprecated, use enumDev2() instead. This function is not
* safe in multithreaded environment.
*
* Enum all video devices installed in the system.
*
* @return The list of video device info
*/
const VideoDevInfoVector &enumDev() PJSUA2_THROW(Error);
#endif
/**
* Enum all video devices installed in the system.
*
* @return The list of video device info
*/
VideoDevInfoVector2 enumDev2() const PJSUA2_THROW(Error);
/**
* Lookup device index based on the driver and device name.
*
* @param drv_name The driver name.
* @param dev_name The device name.
*
* @return The device ID. If the device is not found,
* Error will be thrown.
*/
int lookupDev(const string &drv_name,
const string &dev_name) const PJSUA2_THROW(Error);
/**
* Get string info for the specified capability.
*
* @param cap The capability ID.
*
* @return Capability name.
*/
string capName(pjmedia_vid_dev_cap cap) const;
/**
* This will configure video format capability to the video device.
* If video device is currently active, the method will forward the setting
* to the video device instance to be applied immediately, if it
* supports it.
*
* This method is only valid if the device has
* PJMEDIA_VID_DEV_CAP_FORMAT capability in VideoDevInfo.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 video device to be
* used.
*
* @param dev_id The video device id.
* @param format The video format.
* @param keep Specify whether the setting is to be kept for
* future use.
*/
void setFormat(int dev_id,
const MediaFormatVideo &format,
bool keep) PJSUA2_THROW(Error);
/**
* Get the video format capability to the video device.
* If video device is currently active, the method will forward the request
* to the video device. If video 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_VID_DEV_CAP_FORMAT capability in VideoDevInfo.caps flags,
* otherwise Error will be thrown.
*
* @param dev_id The video device id.
* @return keep The video format.
*/
MediaFormatVideo getFormat(int dev_id) const PJSUA2_THROW(Error);
/**
* This will configure video format capability to the video device.
* If video device is currently active, the method will forward the setting
* to the video device instance to be applied immediately, if it
* supports it.
*
* This method is only valid if the device has
* PJMEDIA_VID_DEV_CAP_INPUT_SCALE capability in VideoDevInfo.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 video device to be
* used.
*
* @param dev_id The video device id.
* @param scale The video scale.
* @param keep Specify whether the setting is to be kept for
* future use.
*/
void setInputScale(int dev_id,
const MediaSize &scale,
bool keep) PJSUA2_THROW(Error);
/**
* Get the video input scale capability to the video device.
* If video device is currently active, the method will forward the request
* to the video device. If video 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_VID_DEV_CAP_FORMAT capability in VideoDevInfo.caps flags,
* otherwise Error will be thrown.
*
* @param dev_id The video device id.
* @return keep The video format.
*/
MediaSize getInputScale(int dev_id) const PJSUA2_THROW(Error);
/**
* This will configure fast switching to another video device.
* If video device is currently active, the method will forward the setting
* to the video device instance to be applied immediately, if it
* supports it.
*
* This method is only valid if the device has
* PJMEDIA_VID_DEV_CAP_OUTPUT_WINDOW_FLAGS capability in VideoDevInfo.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 video device to be
* used.
*
* @param dev_id The video device id.
* @param flags The video window flag.
* @param keep Specify whether the setting is to be kept for
* future use.
*/
void setOutputWindowFlags(int dev_id, int flags, bool keep)
PJSUA2_THROW(Error);
/**
* Get the window output flags capability to the video device.
* If video device is currently active, the method will forward the request
* to the video device. If video 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_VID_DEV_CAP_OUTPUT_WINDOW_FLAGS capability in VideoDevInfo.caps
* flags, otherwise Error will be thrown.
*
* @param dev_id The video device id.
* @return keep The video format.
*/
int getOutputWindowFlags(int dev_id) PJSUA2_THROW(Error);
/**
* This will configure fast switching to another video device.
* If video device is currently active, the method will forward the setting
* to the video device instance to be applied immediately, if it
* supports it.
*
* This method is only valid if the device has
* PJMEDIA_VID_DEV_CAP_SWITCH capability in VideoDevInfo.caps flags,
* otherwise Error will be thrown.
*
* @param dev_id The video device id.
* @param param The video switch param.
*/
void switchDev(int dev_id,
const VideoSwitchParam &param) PJSUA2_THROW(Error);
/**
* Check whether the video capture device is currently active, i.e. if
* a video preview has been started or there is a video call using
* the device.
*
* @param dev_id The video device id
*
* @return True if it's active.
*/
bool isCaptureActive(int dev_id) const;
/**
* This will configure video orientation of the video capture device.
* If the device is currently active (i.e. if there is a video call
* using the device or a video preview has been started), the method
* will forward the setting to the video device instance to be applied
* immediately, if it supports it.
*
* The setting will be saved for future opening of the video device,
* if the "keep" argument is set to true. If the video device is
* currently inactive, and the "keep" argument is false, this method
* will throw Error.
*
* @param dev_id The video device id
* @param orient The video orientation.
* @param keep Specify whether the setting is to be kept for
* future use.
*
*/
void setCaptureOrient(pjmedia_vid_dev_index dev_id,
pjmedia_orient orient,
bool keep=true) PJSUA2_THROW(Error);
private:
#if !DEPRECATED_FOR_TICKET_2232
VideoDevInfoVector videoDevList;
#endif
void clearVideoDevList();
/**
* Constructor.
*/
VidDevManager();
/**
* Destructor.
*/
~VidDevManager();
friend class Endpoint;
};
/*************************************************************************
* Codec management
*/
/**
* This structure describes codec information.
*/
struct CodecInfo
{
/**
* Codec unique identification.
*/
string codecId;
/**
* Codec priority (integer 0-255).
*/
pj_uint8_t priority;
/**
* Codec description.
*/
string desc;
/**
* Construct from pjsua_codec_info.
*/
void fromPj(const pjsua_codec_info &codec_info);
};
/**
* Warning: deprecated, use CodecInfoVector2 instead.
*
* Array of codec info.
*/
typedef std::vector<CodecInfo*> CodecInfoVector;
/** Array of codec info */
typedef std::vector<CodecInfo> CodecInfoVector2;
/**
* Structure of codec specific parameters which contains name=value pairs.
* The codec specific parameters are to be used with SDP according to
* the standards (e.g: RFC 3555) in SDP 'a=fmtp' attribute.
*/
typedef struct CodecFmtp
{
string name; /**< name */
string val; /**< value */
} CodecFmtp;
/** Array of codec fmtp */
typedef std::vector<CodecFmtp> CodecFmtpVector;
/**
* Audio codec parameters info.
*/
struct CodecParamInfo
{
unsigned clockRate; /**< Sampling rate in Hz */
unsigned channelCnt; /**< Channel count. */
unsigned avgBps; /**< Average bandwidth in bits/sec */
unsigned maxBps; /**< Maximum bandwidth in bits/sec */
unsigned maxRxFrameSize; /**< Maximum frame size */
unsigned frameLen; /**< Decoder frame ptime in msec. */
unsigned frameLenDenum; /**< Decoder frame ptime denum, or
zero if ptime is integer. */
unsigned encFrameLen; /**< Encoder ptime, or zero if it's
equal to decoder ptime. */
unsigned encFrameLenDenum; /**< Encoder ptime denum, or zero
if ptime is integer. */
unsigned pcmBitsPerSample; /**< Bits/sample in the PCM side */
unsigned pt; /**< Payload type. */
pjmedia_format_id fmtId; /**< Source format, it's format of
encoder input and decoder
output. */
public:
/**
* Default constructor
*/
CodecParamInfo()
: clockRate(0),
channelCnt(0),
avgBps(0),
maxBps(0),
maxRxFrameSize(0),
frameLen(0),
frameLenDenum(0),
encFrameLen(0),
encFrameLenDenum(0),
pcmBitsPerSample(0),
pt(0),
fmtId(PJMEDIA_FORMAT_L16)
{}
};
/**
* Audio codec parameters setting.
*/
struct CodecParamSetting
{
unsigned frmPerPkt; /**< Number of frames per packet. */
bool vad; /**< Voice Activity Detector. */
bool cng; /**< Comfort Noise Generator. */
bool penh; /**< Perceptual Enhancement */
bool plc; /**< Packet loss concealment */
bool reserved; /**< Reserved, must be zero. */
CodecFmtpVector encFmtp; /**< Encoder's fmtp params. */
CodecFmtpVector decFmtp; /**< Decoder's fmtp params. */
unsigned packetLoss; /**< Encoder's expected pkt loss %. */
unsigned complexity; /**< Encoder complexity, 0-10(max). */
bool cbr; /**< Constant bit rate? */
};
/**
* Detailed codec attributes used in configuring an audio codec and in querying
* the capability of audio codec factories.
*
* Please note that codec parameter also contains SDP specific setting,
* setting::decFmtp and setting::encFmtp, which may need to be set
* appropriately based on the effective setting.
* See each codec documentation for more detail.
*/
struct CodecParam
{
/** info */
struct CodecParamInfo info;
/** setting */
struct CodecParamSetting setting;
void fromPj(const pjmedia_codec_param &param);
pjmedia_codec_param toPj() const;
};
/**
* Opus codec parameters setting;
*/
struct CodecOpusConfig
{
unsigned sample_rate; /**< Sample rate in Hz. */
unsigned channel_cnt; /**< Number of channels. */
unsigned frm_ptime; /**< Frame time in msec. */
unsigned frm_ptime_denum;/**< Frame time denumerator. */
unsigned bit_rate; /**< Encoder bit rate in bps. */
unsigned packet_loss; /**< Encoder's expected packet loss pct. */
unsigned complexity; /**< Encoder complexity, 0-10(10 is highest)*/
bool cbr; /**< Constant bit rate? */
pjmedia_codec_opus_config toPj() const;
void fromPj(const pjmedia_codec_opus_config &config);
};
/**
* Lyra codec setting;
*/
struct CodecLyraConfig
{
/**
* The value represents the decoder bitrate requested by the receiver.
* Endpoints can be configured with different bitrates. For example,
* the local endpoint might be set to a bitrate of 3200, while
* the remote endpoint is set to 6000. In this scenario, the remote
* endpoint will send data at 3200 bitrate, while the local endpoint
* will send data at 6000 bitrate. Valid bitrate: 3200, 6000, 9200.
* By default it is set to PJMEDIA_CODEC_LYRA_DEFAULT_BIT_RATE.
*/
unsigned bitRate;
/**
* Lyra required some additional (model) files, including
* \b lyra_config.binarypb , \b lyragan.tflite , \b quantizer.tflite and
* \b soundstream_encoder.tflite .
* This setting represents the folder containing the above files.
* The specified folder should contain these files. If an invalid folder
* is provided, the codec creation will fail.
*/
string modelPath;
pjmedia_codec_lyra_config toPj() const;
void fromPj(const pjmedia_codec_lyra_config &config);
};
/**
* Detailed codec attributes used in configuring a video codec and in querying
* the capability of video codec factories.
*
* Please note that codec parameter also contains SDP specific setting,
* #decFmtp and #encFmtp, which may need to be set appropriately based on
* the effective setting. See each codec documentation for more detail.
*/
struct VidCodecParam
{
pjmedia_dir dir; /**< Direction */
pjmedia_vid_packing packing; /**< Packetization strategy. */
struct
MediaFormatVideo encFmt; /**< Encoded format */
CodecFmtpVector encFmtp; /**< Encoder fmtp params */
unsigned encMtu; /**< MTU or max payload size setting*/
struct
MediaFormatVideo decFmt; /**< Decoded format */
CodecFmtpVector decFmtp; /**< Decoder fmtp params */
bool ignoreFmtp; /**< Ignore fmtp params. If set to
true, the codec will apply
format settings specified in
encFmt and decFmt only. */
public:
/**
* Default constructor
*/
VidCodecParam() : dir(PJMEDIA_DIR_NONE),
packing(PJMEDIA_VID_PACKING_UNKNOWN),
encMtu(0),
ignoreFmtp(false)
{}
void fromPj(const pjmedia_vid_codec_param &param);
pjmedia_vid_codec_param toPj() const;
};
/*************************************************************************
* Media event
*/
/**
* This structure describes a media format changed event.
*/
struct MediaFmtChangedEvent
{
unsigned newWidth; /**< The new width. */
unsigned newHeight; /**< The new height. */
};
/**
* This structure describes an audio device error event.
*/
struct AudDevErrorEvent
{
pjmedia_dir dir; /**< The direction. */
int id; /**< The audio device ID. */
pj_status_t status; /**< The status code. */
};
/**
* Media event data.
*/
typedef union MediaEventData {
/**
* Media format changed event data.
*/
MediaFmtChangedEvent fmtChanged;
/**
* Audio device error event data.
*/
AudDevErrorEvent audDevError;
/**
* Pointer to storage to user event data, if it's outside
* this struct
*/
GenericData ptr;
} MediaEventData;
/**
* This structure describes a media event. It corresponds to the
* pjmedia_event structure.
*/
struct MediaEvent
{
/**
* The event type.
*/
pjmedia_event_type type;
/**
* Additional data/parameters about the event. The type of data
* will be specific to the event type being reported.
*/
MediaEventData data;
/**
* Pointer to original pjmedia_event. Only valid when the struct
* is converted from PJSIP's pjmedia_event.
*/
void *pjMediaEvent;
public:
/**
* Default constructor
*/
MediaEvent() : type(PJMEDIA_EVENT_NONE), pjMediaEvent(NULL)
{}
/**
* Convert from pjsip
*/
void fromPj(const pjmedia_event &ev);
};
/**
* @} // PJSUA2_MED
*/
} // namespace pj
#endif /* __PJSUA2_MEDIA_HPP__ */
Reference in New Issue View Git Blame Copy Permalink