1 /* 2 * Copyright (c) 2012 The WebRTC project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 // This sub-API supports the following functionalities: 12 // 13 // - Support of non-default codecs (e.g. iLBC, iSAC, etc.). 14 // - Voice Activity Detection (VAD) on a per channel basis. 15 // - Possibility to specify how to map received payload types to codecs. 16 // 17 // Usage example, omitting error checking: 18 // 19 // using namespace webrtc; 20 // VoiceEngine* voe = VoiceEngine::Create(); 21 // VoEBase* base = VoEBase::GetInterface(voe); 22 // VoECodec* codec = VoECodec::GetInterface(voe); 23 // base->Init(); 24 // int num_of_codecs = codec->NumOfCodecs() 25 // ... 26 // base->Terminate(); 27 // base->Release(); 28 // codec->Release(); 29 // VoiceEngine::Delete(voe); 30 // 31 #ifndef WEBRTC_VOICE_ENGINE_VOE_CODEC_H 32 #define WEBRTC_VOICE_ENGINE_VOE_CODEC_H 33 34 #include "webrtc/common_types.h" 35 36 namespace webrtc { 37 38 class RtcEventLog; 39 class VoiceEngine; 40 41 class WEBRTC_DLLEXPORT VoECodec { 42 public: 43 // Factory for the VoECodec sub-API. Increases an internal 44 // reference counter if successful. Returns NULL if the API is not 45 // supported or if construction fails. 46 static VoECodec* GetInterface(VoiceEngine* voiceEngine); 47 48 // Releases the VoECodec sub-API and decreases an internal 49 // reference counter. Returns the new reference count. This value should 50 // be zero for all sub-API:s before the VoiceEngine object can be safely 51 // deleted. 52 virtual int Release() = 0; 53 54 // Gets the number of supported codecs. 55 virtual int NumOfCodecs() = 0; 56 57 // Get the |codec| information for a specified list |index|. 58 virtual int GetCodec(int index, CodecInst& codec) = 0; 59 60 // Sets the |codec| for the |channel| to be used for sending. 61 virtual int SetSendCodec(int channel, const CodecInst& codec) = 0; 62 63 // Gets the |codec| parameters for the sending codec on a specified 64 // |channel|. 65 virtual int GetSendCodec(int channel, CodecInst& codec) = 0; 66 67 // Sets the bitrate on a specified |channel| to the specified value 68 // (in bits/sec). If the value is not supported by the codec, the codec will 69 // choose an appropriate value. 70 // Returns -1 on failure and 0 on success. 71 virtual int SetBitRate(int channel, int bitrate_bps) = 0; 72 73 // Gets the currently received |codec| for a specific |channel|. 74 virtual int GetRecCodec(int channel, CodecInst& codec) = 0; 75 76 // Sets the dynamic payload type number for a particular |codec| or 77 // disables (ignores) a codec for receiving. For instance, when receiving 78 // an invite from a SIP-based client, this function can be used to change 79 // the dynamic payload type number to match that in the INVITE SDP- 80 // message. The utilized parameters in the |codec| structure are: 81 // plname, plfreq, pltype and channels. 82 virtual int SetRecPayloadType(int channel, const CodecInst& codec) = 0; 83 84 // Gets the actual payload type that is set for receiving a |codec| on a 85 // |channel|. The value it retrieves will either be the default payload 86 // type, or a value earlier set with SetRecPayloadType(). 87 virtual int GetRecPayloadType(int channel, CodecInst& codec) = 0; 88 89 // Sets the payload |type| for the sending of SID-frames with background 90 // noise estimation during silence periods detected by the VAD. 91 virtual int SetSendCNPayloadType( 92 int channel, 93 int type, 94 PayloadFrequencies frequency = kFreq16000Hz) = 0; 95 96 // Sets the codec internal FEC (forward error correction) status for a 97 // specified |channel|. Returns 0 if success, and -1 if failed. 98 // TODO(minyue): Make SetFECStatus() pure virtual when fakewebrtcvoiceengine 99 // in talk is ready. SetFECStatus(int channel,bool enable)100 virtual int SetFECStatus(int channel, bool enable) { return -1; } 101 102 // Gets the codec internal FEC status for a specified |channel|. Returns 0 103 // with the status stored in |enabled| if success, and -1 if encountered 104 // error. 105 // TODO(minyue): Make GetFECStatus() pure virtual when fakewebrtcvoiceengine 106 // in talk is ready. GetFECStatus(int channel,bool & enabled)107 virtual int GetFECStatus(int channel, bool& enabled) { return -1; } 108 109 // Sets the VAD/DTX (silence suppression) status and |mode| for a 110 // specified |channel|. Disabling VAD (through |enable|) will also disable 111 // DTX; it is not necessary to explictly set |disableDTX| in this case. 112 virtual int SetVADStatus(int channel, 113 bool enable, 114 VadModes mode = kVadConventional, 115 bool disableDTX = false) = 0; 116 117 // Gets the VAD/DTX status and |mode| for a specified |channel|. 118 virtual int GetVADStatus(int channel, 119 bool& enabled, 120 VadModes& mode, 121 bool& disabledDTX) = 0; 122 123 // If send codec is Opus on a specified |channel|, sets the maximum playback 124 // rate the receiver will render: |frequency_hz| (in Hz). 125 // TODO(minyue): Make SetOpusMaxPlaybackRate() pure virtual when 126 // fakewebrtcvoiceengine in talk is ready. SetOpusMaxPlaybackRate(int channel,int frequency_hz)127 virtual int SetOpusMaxPlaybackRate(int channel, int frequency_hz) { 128 return -1; 129 } 130 131 // If send codec is Opus on a specified |channel|, set its DTX. Returns 0 if 132 // success, and -1 if failed. 133 virtual int SetOpusDtx(int channel, bool enable_dtx) = 0; 134 135 // Get a pointer to the event logging object associated with this Voice 136 // Engine. This pointer will remain valid until VoiceEngine is destroyed. 137 virtual RtcEventLog* GetEventLog() = 0; 138 139 protected: VoECodec()140 VoECodec() {} ~VoECodec()141 virtual ~VoECodec() {} 142 }; 143 144 } // namespace webrtc 145 146 #endif // WEBRTC_VOICE_ENGINE_VOE_CODEC_H 147