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
20namespace webrtc {
21
22// This is the interface class for decoders in NetEQ. Each codec type will have
23// and implementation of this class.
24class 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