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
36namespace webrtc {
37
38class VoiceEngine;
39
40class WEBRTC_DLLEXPORT VoECodec
41{
42public:
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
147protected:
148    VoECodec() {}
149    virtual ~VoECodec() {}
150};
151
152}  // namespace webrtc
153
154#endif  //  WEBRTC_VOICE_ENGINE_VOE_CODEC_H
155