third_party/libwebrtc/api/audio_codecs/audio_decoder.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 #ifndef API_AUDIO_CODECS_AUDIO_DECODER_H_
  12 #define API_AUDIO_CODECS_AUDIO_DECODER_H_
  13
  14 #include <stddef.h>
  15 #include <stdint.h>
  16
  17 #include <memory>
  18 #include <vector>
  19
  20 #include "absl/types/optional.h"
  21 #include "api/array_view.h"
  22 #include "rtc_base/buffer.h"
  23
  24 namespace webrtc {
  25
  26 class AudioDecoder {
  27  public:
  28   enum SpeechType {
  29     kSpeech = 1,
  30     kComfortNoise = 2,
  31   };
  32
  33   // Used by PacketDuration below. Save the value -1 for errors.
  34   enum { kNotImplemented = -2 };
  35
  36   AudioDecoder() = default;
  37   virtual ~AudioDecoder() = default;
  38
  39   AudioDecoder(const AudioDecoder&) = delete;
  40   AudioDecoder& operator=(const AudioDecoder&) = delete;
  41
  42   class EncodedAudioFrame {
  43    public:
  44     struct DecodeResult {
  45       size_t num_decoded_samples;
  46       SpeechType speech_type;
  47     };
  48
  49     virtual ~EncodedAudioFrame() = default;
  50
  51     // Returns the duration in samples-per-channel of this audio frame.
  52     // If no duration can be ascertained, returns zero.
  53     virtual size_t Duration() const = 0;
  54
  55     // Returns true if this packet contains DTX.
  56     virtual bool IsDtxPacket() const;
  57
  58     // Decodes this frame of audio and writes the result in `decoded`.
  59     // `decoded` must be large enough to store as many samples as indicated by a
  60     // call to Duration() . On success, returns an absl::optional containing the
  61     // total number of samples across all channels, as well as whether the
  62     // decoder produced comfort noise or speech. On failure, returns an empty
  63     // absl::optional. Decode may be called at most once per frame object.
  64     virtual absl::optional<DecodeResult> Decode(
  65         rtc::ArrayView<int16_t> decoded) const = 0;
  66   };
  67
  68   struct ParseResult {
  69     ParseResult();
  70     ParseResult(uint32_t timestamp,
  71                 int priority,
  72                 std::unique_ptr<EncodedAudioFrame> frame);
  73     ParseResult(ParseResult&& b);
  74     ~ParseResult();
  75
  76     ParseResult& operator=(ParseResult&& b);
  77
  78     // The timestamp of the frame is in samples per channel.
  79     uint32_t timestamp;
  80     // The relative priority of the frame compared to other frames of the same
  81     // payload and the same timeframe. A higher value means a lower priority.
  82     // The highest priority is zero - negative values are not allowed.
  83     int priority;
  84     std::unique_ptr<EncodedAudioFrame> frame;
  85   };
  86
  87   // Let the decoder parse this payload and prepare zero or more decodable
  88   // frames. Each frame must be between 10 ms and 120 ms long. The caller must
  89   // ensure that the AudioDecoder object outlives any frame objects returned by
  90   // this call. The decoder is free to swap or move the data from the `payload`
  91   // buffer. `timestamp` is the input timestamp, in samples, corresponding to
  92   // the start of the payload.
  93   virtual std::vector<ParseResult> ParsePayload(rtc::Buffer&& payload,
  94                                                 uint32_t timestamp);
  95
  96   // TODO(bugs.webrtc.org/10098): The Decode and DecodeRedundant methods are
  97   // obsolete; callers should call ParsePayload instead. For now, subclasses
  98   // must still implement DecodeInternal.
  99
 100   // Decodes `encode_len` bytes from `encoded` and writes the result in
 101   // `decoded`. The maximum bytes allowed to be written into `decoded` is
 102   // `max_decoded_bytes`. Returns the total number of samples across all
 103   // channels. If the decoder produced comfort noise, `speech_type`
 104   // is set to kComfortNoise, otherwise it is kSpeech. The desired output
 105   // sample rate is provided in `sample_rate_hz`, which must be valid for the
 106   // codec at hand.
 107   int Decode(const uint8_t* encoded,
 108              size_t encoded_len,
 109              int sample_rate_hz,
 110              size_t max_decoded_bytes,
 111              int16_t* decoded,
 112              SpeechType* speech_type);
 113
 114   // Same as Decode(), but interfaces to the decoders redundant decode function.
 115   // The default implementation simply calls the regular Decode() method.
 116   int DecodeRedundant(const uint8_t* encoded,
 117                       size_t encoded_len,
 118                       int sample_rate_hz,
 119                       size_t max_decoded_bytes,
 120                       int16_t* decoded,
 121                       SpeechType* speech_type);
 122
 123   // Indicates if the decoder implements the DecodePlc method.
 124   virtual bool HasDecodePlc() const;
 125
 126   // Calls the packet-loss concealment of the decoder to update the state after
 127   // one or several lost packets. The caller has to make sure that the
 128   // memory allocated in `decoded` should accommodate `num_frames` frames.
 129   virtual size_t DecodePlc(size_t num_frames, int16_t* decoded);
 130
 131   // Asks the decoder to generate packet-loss concealment and append it to the
 132   // end of `concealment_audio`. The concealment audio should be in
 133   // channel-interleaved format, with as many channels as the last decoded
 134   // packet produced. The implementation must produce at least
 135   // requested_samples_per_channel, or nothing at all. This is a signal to the
 136   // caller to conceal the loss with other means. If the implementation provides
 137   // concealment samples, it is also responsible for "stitching" it together
 138   // with the decoded audio on either side of the concealment.
 139   // Note: The default implementation of GeneratePlc will be deleted soon. All
 140   // implementations must provide their own, which can be a simple as a no-op.
 141   // TODO(bugs.webrtc.org/9676): Remove default implementation.
 142   virtual void GeneratePlc(size_t requested_samples_per_channel,
 143                            rtc::BufferT<int16_t>* concealment_audio);
 144
 145   // Resets the decoder state (empty buffers etc.).
 146   virtual void Reset() = 0;
 147
 148   // Returns the last error code from the decoder.
 149   virtual int ErrorCode();
 150
 151   // Returns the duration in samples-per-channel of the payload in `encoded`
 152   // which is `encoded_len` bytes long. Returns kNotImplemented if no duration
 153   // estimate is available, or -1 in case of an error.
 154   virtual int PacketDuration(const uint8_t* encoded, size_t encoded_len) const;
 155
 156   // Returns the duration in samples-per-channel of the redandant payload in
 157   // `encoded` which is `encoded_len` bytes long. Returns kNotImplemented if no
 158   // duration estimate is available, or -1 in case of an error.
 159   virtual int PacketDurationRedundant(const uint8_t* encoded,
 160                                       size_t encoded_len) const;
 161
 162   // Detects whether a packet has forward error correction. The packet is
 163   // comprised of the samples in `encoded` which is `encoded_len` bytes long.
 164   // Returns true if the packet has FEC and false otherwise.
 165   virtual bool PacketHasFec(const uint8_t* encoded, size_t encoded_len) const;
 166
 167   // Returns the actual sample rate of the decoder's output. This value may not
 168   // change during the lifetime of the decoder.
 169   virtual int SampleRateHz() const = 0;
 170
 171   // The number of channels in the decoder's output. This value may not change
 172   // during the lifetime of the decoder.
 173   virtual size_t Channels() const = 0;
 174
 175   // The maximum number of audio channels supported by WebRTC decoders.
 176   static constexpr int kMaxNumberOfChannels = 24;
 177
 178  protected:
 179   static SpeechType ConvertSpeechType(int16_t type);
 180
 181   virtual int DecodeInternal(const uint8_t* encoded,
 182                              size_t encoded_len,
 183                              int sample_rate_hz,
 184                              int16_t* decoded,
 185                              SpeechType* speech_type) = 0;
 186
 187   virtual int DecodeRedundantInternal(const uint8_t* encoded,
 188                                       size_t encoded_len,
 189                                       int sample_rate_hz,
 190                                       int16_t* decoded,
 191                                       SpeechType* speech_type);
 192 };
 193
 194 }  // namespace webrtc
 195 #endif  // API_AUDIO_CODECS_AUDIO_DECODER_H_