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 #ifndef WEBRTC_MODULES_AUDIO_CODING_NETEQ_INCLUDE_AUDIO_DECODER_H_
12 #define WEBRTC_MODULES_AUDIO_CODING_NETEQ_INCLUDE_AUDIO_DECODER_H_
13 
14 #include <stdlib.h>  // NULL
15 
16 #include "webrtc/base/constructormagic.h"
17 #include "webrtc/modules/audio_coding/codecs/cng/webrtc_cng.h"
18 #include "webrtc/typedefs.h"
19 
20 namespace webrtc {
21 
22 // This is the interface class for decoders in NetEQ. Each codec type will have
23 // and implementation of this class.
24 class AudioDecoder {
25  public:
26   enum SpeechType {
27     kSpeech = 1,
28     kComfortNoise = 2
29   };
30 
31   // Used by PacketDuration below. Save the value -1 for errors.
32   enum { kNotImplemented = -2 };
33 
34   AudioDecoder() = default;
35   virtual ~AudioDecoder() = default;
36 
37   // Decodes |encode_len| bytes from |encoded| and writes the result in
38   // |decoded|. The maximum bytes allowed to be written into |decoded| is
39   // |max_decoded_bytes|. Returns the total number of samples across all
40   // channels. If the decoder produced comfort noise, |speech_type|
41   // is set to kComfortNoise, otherwise it is kSpeech. The desired output
42   // sample rate is provided in |sample_rate_hz|, which must be valid for the
43   // codec at hand.
44   int Decode(const uint8_t* encoded,
45              size_t encoded_len,
46              int sample_rate_hz,
47              size_t max_decoded_bytes,
48              int16_t* decoded,
49              SpeechType* speech_type);
50 
51   // Same as Decode(), but interfaces to the decoders redundant decode function.
52   // The default implementation simply calls the regular Decode() method.
53   int DecodeRedundant(const uint8_t* encoded,
54                       size_t encoded_len,
55                       int sample_rate_hz,
56                       size_t max_decoded_bytes,
57                       int16_t* decoded,
58                       SpeechType* speech_type);
59 
60   // Indicates if the decoder implements the DecodePlc method.
61   virtual bool HasDecodePlc() const;
62 
63   // Calls the packet-loss concealment of the decoder to update the state after
64   // one or several lost packets. The caller has to make sure that the
65   // memory allocated in |decoded| should accommodate |num_frames| frames.
66   virtual size_t DecodePlc(size_t num_frames, int16_t* decoded);
67 
68   // Resets the decoder state (empty buffers etc.).
69   virtual void Reset() = 0;
70 
71   // Notifies the decoder of an incoming packet to NetEQ.
72   virtual int IncomingPacket(const uint8_t* payload,
73                              size_t payload_len,
74                              uint16_t rtp_sequence_number,
75                              uint32_t rtp_timestamp,
76                              uint32_t arrival_timestamp);
77 
78   // Returns the last error code from the decoder.
79   virtual int ErrorCode();
80 
81   // Returns the duration in samples-per-channel of the payload in |encoded|
82   // which is |encoded_len| bytes long. Returns kNotImplemented if no duration
83   // estimate is available, or -1 in case of an error.
84   virtual int PacketDuration(const uint8_t* encoded, size_t encoded_len) const;
85 
86   // Returns the duration in samples-per-channel of the redandant payload in
87   // |encoded| which is |encoded_len| bytes long. Returns kNotImplemented if no
88   // duration estimate is available, or -1 in case of an error.
89   virtual int PacketDurationRedundant(const uint8_t* encoded,
90                                       size_t encoded_len) const;
91 
92   // Detects whether a packet has forward error correction. The packet is
93   // comprised of the samples in |encoded| which is |encoded_len| bytes long.
94   // Returns true if the packet has FEC and false otherwise.
95   virtual bool PacketHasFec(const uint8_t* encoded, size_t encoded_len) const;
96 
97   // If this is a CNG decoder, return the underlying CNG_dec_inst*. If this
98   // isn't a CNG decoder, don't call this method.
99   virtual CNG_dec_inst* CngDecoderInstance();
100 
101   virtual size_t Channels() const = 0;
102 
103  protected:
104   static SpeechType ConvertSpeechType(int16_t type);
105 
106   virtual int DecodeInternal(const uint8_t* encoded,
107                              size_t encoded_len,
108                              int sample_rate_hz,
109                              int16_t* decoded,
110                              SpeechType* speech_type) = 0;
111 
112   virtual int DecodeRedundantInternal(const uint8_t* encoded,
113                                       size_t encoded_len,
114                                       int sample_rate_hz,
115                                       int16_t* decoded,
116                                       SpeechType* speech_type);
117 
118  private:
119   RTC_DISALLOW_COPY_AND_ASSIGN(AudioDecoder);
120 };
121 
122 }  // namespace webrtc
123 #endif  // WEBRTC_MODULES_AUDIO_CODING_NETEQ_INCLUDE_AUDIO_DECODER_H_
124