src/third_party/webrtc/voice_engine/include/voe_codec.h

   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 VoiceEngine;
  39
  40 class WEBRTC_DLLEXPORT VoECodec
  41 {
  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 |codec| as secondary codec for |channel|. Registering a
  68     // secondary send codec enables dual-streaming. In dual-streaming mode,
  69     // payloads of the primary and the secondary codecs are packed in RED
  70     // payloads with |red_payload_type| as payload type. The Secondary codec
  71     // MUST have the same sampling rate as the primary codec, otherwise the
  72     // codec cannot be registered and -1 is returned. This method fails if a
  73     // primary codec is not yet set.
  74     virtual int SetSecondarySendCodec(int channel, const CodecInst& codec,
  75                                       int red_payload_type) = 0;
  76
  77     // Removes the secondary codec from |channel|. This will terminate
  78     // dual-streaming.
  79     virtual int RemoveSecondarySendCodec(int channel) = 0;
  80
  81     // Gets |codec| which is used as secondary codec in |channel|.
  82     virtual int GetSecondarySendCodec(int channel, CodecInst& codec) = 0;
  83
  84     // Gets the currently received |codec| for a specific |channel|.
  85     virtual int GetRecCodec(int channel, CodecInst& codec) = 0;
  86
  87     // Sets the dynamic payload type number for a particular |codec| or
  88     // disables (ignores) a codec for receiving. For instance, when receiving
  89     // an invite from a SIP-based client, this function can be used to change
  90     // the dynamic payload type number to match that in the INVITE SDP-
  91     // message. The utilized parameters in the |codec| structure are:
  92     // plname, plfreq, pltype and channels.
  93     virtual int SetRecPayloadType(int channel, const CodecInst& codec) = 0;
  94
  95     // Gets the actual payload type that is set for receiving a |codec| on a
  96     // |channel|. The value it retrieves will either be the default payload
  97     // type, or a value earlier set with SetRecPayloadType().
  98     virtual int GetRecPayloadType(int channel, CodecInst& codec) = 0;
  99
 100     // Sets the payload |type| for the sending of SID-frames with background
 101     // noise estimation during silence periods detected by the VAD.
 102     virtual int SetSendCNPayloadType(
 103         int channel, int type, PayloadFrequencies frequency = kFreq16000Hz) = 0;
 104
 105     // Sets the codec internal FEC (forward error correction) status for a
 106     // specified |channel|. Returns 0 if success, and -1 if failed.
 107     // TODO(minyue): Make SetFECStatus() pure virtual when fakewebrtcvoiceengine
 108     // in talk is ready.
 109     virtual int SetFECStatus(int channel, bool enable) { return -1; }
 110
 111     // Gets the codec internal FEC status for a specified |channel|. Returns 0
 112     // with the status stored in |enabled| if success, and -1 if encountered
 113     // error.
 114     // TODO(minyue): Make GetFECStatus() pure virtual when fakewebrtcvoiceengine
 115     // in talk is ready.
 116     virtual int GetFECStatus(int channel, bool& enabled) { return -1; }
 117
 118     // Sets the VAD/DTX (silence suppression) status and |mode| for a
 119     // specified |channel|. Disabling VAD (through |enable|) will also disable
 120     // DTX; it is not necessary to explictly set |disableDTX| in this case.
 121     virtual int SetVADStatus(int channel, bool enable,
 122                              VadModes mode = kVadConventional,
 123                              bool disableDTX = false) = 0;
 124
 125     // Gets the VAD/DTX status and |mode| for a specified |channel|.
 126     virtual int GetVADStatus(int channel, bool& enabled, VadModes& mode,
 127                              bool& disabledDTX) = 0;
 128
 129     // If send codec is Opus on a specified |channel|, sets the maximum playback
 130     // rate the receiver will render: |frequency_hz| (in Hz).
 131     // TODO(minyue): Make SetOpusMaxPlaybackRate() pure virtual when
 132     // fakewebrtcvoiceengine in talk is ready.
 133     virtual int SetOpusMaxPlaybackRate(int channel, int frequency_hz) {
 134       return -1;
 135     }
 136
 137     // Don't use. To be removed.
 138     virtual int SetAMREncFormat(int channel, AmrMode mode) { return -1; }
 139     virtual int SetAMRDecFormat(int channel, AmrMode mode) { return -1; }
 140     virtual int SetAMRWbEncFormat(int channel, AmrMode mode) { return -1; }
 141     virtual int SetAMRWbDecFormat(int channel, AmrMode mode) { return -1; }
 142     virtual int SetISACInitTargetRate(int channel, int rateBps,
 143             bool useFixedFrameSize = false) { return -1; }
 144     virtual int SetISACMaxRate(int channel, int rateBps) { return -1; }
 145     virtual int SetISACMaxPayloadSize(int channel, int sizeBytes) { return -1; }
 146
 147 protected:
 148     VoECodec() {}
 149     virtual ~VoECodec() {}
 150 };
 151
 152 }  // namespace webrtc
 153
 154 #endif  //  WEBRTC_VOICE_ENGINE_VOE_CODEC_H