Home | History | Annotate | Download | only in include 
      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
    155