1b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org/* 2b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org * Copyright (c) 2012 The WebRTC project authors. All Rights Reserved. 3b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org * 4b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org * Use of this source code is governed by a BSD-style license 5b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org * that can be found in the LICENSE file in the root of the source 6b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org * tree. An additional intellectual property rights grant can be found 7b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org * in the file PATENTS. All contributing project authors may 8b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org * be found in the AUTHORS file in the root of the source tree. 9b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org */ 10b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 11b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// This sub-API supports the following functionalities: 12b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// 13b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// - Support of non-default codecs (e.g. iLBC, iSAC, etc.). 14b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// - Voice Activity Detection (VAD) on a per channel basis. 15b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// - Possibility to specify how to map received payload types to codecs. 16b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// 17b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// Usage example, omitting error checking: 18b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// 19b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// using namespace webrtc; 20b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// VoiceEngine* voe = VoiceEngine::Create(); 21b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// VoEBase* base = VoEBase::GetInterface(voe); 22b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// VoECodec* codec = VoECodec::GetInterface(voe); 23b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// base->Init(); 24b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// int num_of_codecs = codec->NumOfCodecs() 25b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// ... 26b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// base->Terminate(); 27b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// base->Release(); 28b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// codec->Release(); 29b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// VoiceEngine::Delete(voe); 30b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org// 31b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org#ifndef WEBRTC_VOICE_ENGINE_VOE_CODEC_H 32b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org#define WEBRTC_VOICE_ENGINE_VOE_CODEC_H 33b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 34471ae72f18e7b23a96b245dbd508386fe139449cpbos@webrtc.org#include "webrtc/common_types.h" 35b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 36b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.orgnamespace webrtc { 37b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 38b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.orgclass VoiceEngine; 39b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 40b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.orgclass WEBRTC_DLLEXPORT VoECodec 41b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org{ 42b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.orgpublic: 43b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // Factory for the VoECodec sub-API. Increases an internal 44b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // reference counter if successful. Returns NULL if the API is not 45b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // supported or if construction fails. 46b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org static VoECodec* GetInterface(VoiceEngine* voiceEngine); 47b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 48b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // Releases the VoECodec sub-API and decreases an internal 49b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // reference counter. Returns the new reference count. This value should 50b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // be zero for all sub-API:s before the VoiceEngine object can be safely 51b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // deleted. 52b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org virtual int Release() = 0; 53b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 54b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // Gets the number of supported codecs. 55b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org virtual int NumOfCodecs() = 0; 56b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 57b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // Get the |codec| information for a specified list |index|. 58b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org virtual int GetCodec(int index, CodecInst& codec) = 0; 59b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 60b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // Sets the |codec| for the |channel| to be used for sending. 61b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org virtual int SetSendCodec(int channel, const CodecInst& codec) = 0; 62b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 63b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // Gets the |codec| parameters for the sending codec on a specified 64b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // |channel|. 65b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org virtual int GetSendCodec(int channel, CodecInst& codec) = 0; 66b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 677db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org // Sets the |codec| as secondary codec for |channel|. Registering a 687db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org // secondary send codec enables dual-streaming. In dual-streaming mode, 697db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org // payloads of the primary and the secondary codecs are packed in RED 707db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org // payloads with |red_payload_type| as payload type. The Secondary codec 717db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org // MUST have the same sampling rate as the primary codec, otherwise the 727db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org // codec cannot be registered and -1 is returned. This method fails if a 737db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org // primary codec is not yet set. 747db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org virtual int SetSecondarySendCodec(int channel, const CodecInst& codec, 757db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org int red_payload_type) = 0; 767db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org 777db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org // Removes the secondary codec from |channel|. This will terminate 787db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org // dual-streaming. 797db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org virtual int RemoveSecondarySendCodec(int channel) = 0; 807db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org 817db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org // Gets |codec| which is used as secondary codec in |channel|. 827db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org virtual int GetSecondarySendCodec(int channel, CodecInst& codec) = 0; 837db529046a2f5fc57f964619b9926a53b513c0a4turaj@webrtc.org 84b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // Gets the currently received |codec| for a specific |channel|. 85b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org virtual int GetRecCodec(int channel, CodecInst& codec) = 0; 86b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 87b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // Sets the dynamic payload type number for a particular |codec| or 88b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // disables (ignores) a codec for receiving. For instance, when receiving 89b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // an invite from a SIP-based client, this function can be used to change 90b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // the dynamic payload type number to match that in the INVITE SDP- 91b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // message. The utilized parameters in the |codec| structure are: 92b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // plname, plfreq, pltype and channels. 93b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org virtual int SetRecPayloadType(int channel, const CodecInst& codec) = 0; 94b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 95b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // Gets the actual payload type that is set for receiving a |codec| on a 96b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // |channel|. The value it retrieves will either be the default payload 97b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // type, or a value earlier set with SetRecPayloadType(). 98b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org virtual int GetRecPayloadType(int channel, CodecInst& codec) = 0; 99b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 100b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // Sets the payload |type| for the sending of SID-frames with background 101b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // noise estimation during silence periods detected by the VAD. 102b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org virtual int SetSendCNPayloadType( 103b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org int channel, int type, PayloadFrequencies frequency = kFreq16000Hz) = 0; 104b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 105dd671dea7a51c5db5e15123acac599e89f9be201minyue@webrtc.org // Sets the codec internal FEC (forward error correction) status for a 106dd671dea7a51c5db5e15123acac599e89f9be201minyue@webrtc.org // specified |channel|. Returns 0 if success, and -1 if failed. 107dd671dea7a51c5db5e15123acac599e89f9be201minyue@webrtc.org // TODO(minyue): Make SetFECStatus() pure virtual when fakewebrtcvoiceengine 108dd671dea7a51c5db5e15123acac599e89f9be201minyue@webrtc.org // in talk is ready. 109dd671dea7a51c5db5e15123acac599e89f9be201minyue@webrtc.org virtual int SetFECStatus(int channel, bool enable) { return -1; } 110dd671dea7a51c5db5e15123acac599e89f9be201minyue@webrtc.org 111dd671dea7a51c5db5e15123acac599e89f9be201minyue@webrtc.org // Gets the codec internal FEC status for a specified |channel|. Returns 0 112dd671dea7a51c5db5e15123acac599e89f9be201minyue@webrtc.org // with the status stored in |enabled| if success, and -1 if encountered 113dd671dea7a51c5db5e15123acac599e89f9be201minyue@webrtc.org // error. 114dd671dea7a51c5db5e15123acac599e89f9be201minyue@webrtc.org // TODO(minyue): Make GetFECStatus() pure virtual when fakewebrtcvoiceengine 115dd671dea7a51c5db5e15123acac599e89f9be201minyue@webrtc.org // in talk is ready. 116dd671dea7a51c5db5e15123acac599e89f9be201minyue@webrtc.org virtual int GetFECStatus(int channel, bool& enabled) { return -1; } 117b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 118b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // Sets the VAD/DTX (silence suppression) status and |mode| for a 119b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // specified |channel|. Disabling VAD (through |enable|) will also disable 120b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // DTX; it is not necessary to explictly set |disableDTX| in this case. 121b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org virtual int SetVADStatus(int channel, bool enable, 122b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org VadModes mode = kVadConventional, 123b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org bool disableDTX = false) = 0; 124b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 125b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org // Gets the VAD/DTX status and |mode| for a specified |channel|. 126b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org virtual int GetVADStatus(int channel, bool& enabled, VadModes& mode, 127b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org bool& disabledDTX) = 0; 128b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 129b0aac71bfeb5b06083a9664434d936e091f54d91minyue@webrtc.org // If send codec is Opus on a specified |channel|, sets the maximum playback 130b0aac71bfeb5b06083a9664434d936e091f54d91minyue@webrtc.org // rate the receiver will render: |frequency_hz| (in Hz). 131b0aac71bfeb5b06083a9664434d936e091f54d91minyue@webrtc.org // TODO(minyue): Make SetOpusMaxPlaybackRate() pure virtual when 1321bfd54032a8e60b993fb3b32c15ba9c55184c86bminyue@webrtc.org // fakewebrtcvoiceengine in talk is ready. 133b0aac71bfeb5b06083a9664434d936e091f54d91minyue@webrtc.org virtual int SetOpusMaxPlaybackRate(int channel, int frequency_hz) { 1341bfd54032a8e60b993fb3b32c15ba9c55184c86bminyue@webrtc.org return -1; 1351bfd54032a8e60b993fb3b32c15ba9c55184c86bminyue@webrtc.org } 1361bfd54032a8e60b993fb3b32c15ba9c55184c86bminyue@webrtc.org 13766ccaffbf91ffd265380c16e23eed4bcc2d1b505henrika@webrtc.org // Don't use. To be removed. 13866ccaffbf91ffd265380c16e23eed4bcc2d1b505henrika@webrtc.org virtual int SetAMREncFormat(int channel, AmrMode mode) { return -1; } 13966ccaffbf91ffd265380c16e23eed4bcc2d1b505henrika@webrtc.org virtual int SetAMRDecFormat(int channel, AmrMode mode) { return -1; } 14066ccaffbf91ffd265380c16e23eed4bcc2d1b505henrika@webrtc.org virtual int SetAMRWbEncFormat(int channel, AmrMode mode) { return -1; } 14166ccaffbf91ffd265380c16e23eed4bcc2d1b505henrika@webrtc.org virtual int SetAMRWbDecFormat(int channel, AmrMode mode) { return -1; } 14266ccaffbf91ffd265380c16e23eed4bcc2d1b505henrika@webrtc.org virtual int SetISACInitTargetRate(int channel, int rateBps, 14366ccaffbf91ffd265380c16e23eed4bcc2d1b505henrika@webrtc.org bool useFixedFrameSize = false) { return -1; } 14466ccaffbf91ffd265380c16e23eed4bcc2d1b505henrika@webrtc.org virtual int SetISACMaxRate(int channel, int rateBps) { return -1; } 14566ccaffbf91ffd265380c16e23eed4bcc2d1b505henrika@webrtc.org virtual int SetISACMaxPayloadSize(int channel, int sizeBytes) { return -1; } 146b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 147b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.orgprotected: 148b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org VoECodec() {} 149b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org virtual ~VoECodec() {} 150b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org}; 151b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 1523b89e10f31160da35b408fd00cb8f89d2b08862dpbos@webrtc.org} // namespace webrtc 153b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org 154b015cbede88899f67a53fbbe581b02ce8e32794andrew@webrtc.org#endif // WEBRTC_VOICE_ENGINE_VOE_CODEC_H 155