Added a ParsePayload method to AudioDecoder.

webrtc/modules/audio_coding/codecs/audio_decoder.h

 /*
  *  Copyright (c) 2012 The WebRTC project authors. All Rights Reserved.
  *
  *  Use of this source code is governed by a BSD-style license
  *  that can be found in the LICENSE file in the root of the source
  *  tree. An additional intellectual property rights grant can be found
  *  in the file PATENTS.  All contributing project authors may
  *  be found in the AUTHORS file in the root of the source tree.
  */
 
 #ifndef WEBRTC_MODULES_AUDIO_CODING_NETEQ_INCLUDE_AUDIO_DECODER_H_
 #define WEBRTC_MODULES_AUDIO_CODING_NETEQ_INCLUDE_AUDIO_DECODER_H_
 
 #include <stdlib.h>  // NULL
 
+#include "webrtc/base/array_view.h"
+#include "webrtc/base/buffer.h"
 #include "webrtc/base/constructormagic.h"
+#include "webrtc/base/optional.h"
 #include "webrtc/typedefs.h"
 
 namespace webrtc {
 
 // This is the interface class for decoders in NetEQ. Each codec type will have
 // and implementation of this class.
 class AudioDecoder {
  public:
   enum SpeechType {
     kSpeech = 1,
     kComfortNoise = 2
   };
 
   // Used by PacketDuration below. Save the value -1 for errors.
   enum { kNotImplemented = -2 };
 
   AudioDecoder() = default;
   virtual ~AudioDecoder() = default;
 
+  class EncodedAudioFrame {
+   public:
+    struct DecodeResult {
+      size_t num_decoded_samples;
+      SpeechType speech_type;
+    };
+
+    virtual ~EncodedAudioFrame() = default;
+
+    // Returns the duration in samples-per-channel of this audio frame.
+    // If no duration can be ascertained, returns zero.
+    virtual size_t Duration() const = 0;
+
+    // Decodes this frame of audio and writes the result in |decoded|.
+    // Returns rtc::Optional containing the total number of samples across all
+    // channels, as well as whether the decoder produced comfort noise or
+    // speech. Decode must only be called once per frame object.

[kwiberg-webrtc, 2016/09/15 12:00:59]

You don't say under what circumstances the return value will be empty. 

Also, it's probably best to be specific: Decode may be called 0 or 1 times.

Is |decoded| guaranteed to be of the correct size? Or at least as large as
necessary?

[ossu, 2016/09/15 13:07:54]

I'd really prefer it if this method were handed a Buffer<int16> instead, but I
won't do that change in this CL. For now, I'll just mention it's supposed to fit
120 ms of audio in the decoder's sample rate.

[kwiberg-webrtc, 2016/09/16 00:14:07]

IOW, it's supposed to be at least as large as necessary? (Relatedly, I presume
the EncodedAudioFrame knows how much output to produce?)

I agree about using a Buffer, and to not make that change in this CL.

+    virtual rtc::Optional<DecodeResult> Decode(
+        rtc::ArrayView<int16_t> decoded) const = 0;
+  };
+
+  struct ParseResult {
+    ParseResult();
+    ParseResult(uint32_t timestamp,
+                bool primary,
+                std::unique_ptr<EncodedAudioFrame> frame);
+    ParseResult(ParseResult&& b);
+    ~ParseResult();
+
+    ParseResult& operator=(ParseResult&& b);
+
+    // The timestamp of the frame is in samples per channel.
+    uint32_t timestamp;
+    bool primary;
+    std::unique_ptr<EncodedAudioFrame> frame;
+  };
+
+  // Let the decoder parse this payload and prepare zero or more decodable
+  // frames. Each frame must be at most 120 ms long. The decoder is free to swap
+  // or move the data from the |payload| buffer.
+  virtual std::vector<ParseResult> ParsePayload(rtc::Buffer* payload,
+                                                uint32_t timestamp,
+                                                bool is_primary);

[kwiberg-webrtc, 2016/09/15 12:00:59]

Do you intend for this to be a sink for the payload Buffers, or should |payload|
own a usable allocation after the call? The latter should be documented, and the
former is probably best expressed by changing the argument type to
rtc::Buffer&&. :-)

Also, please document that the caller is responsible for keeping the
AudioDecoder alive longer than the returned ParseResult objects.

[ossu, 2016/09/15 13:07:54]

It's a sink. I'll clarify the AudioDecoder's lifetime,

[kwiberg-webrtc, 2016/09/16 00:14:07]

Acknowledged.

+
   // Decodes |encode_len| bytes from |encoded| and writes the result in
   // |decoded|. The maximum bytes allowed to be written into |decoded| is
   // |max_decoded_bytes|. Returns the total number of samples across all
   // channels. If the decoder produced comfort noise, |speech_type|
   // is set to kComfortNoise, otherwise it is kSpeech. The desired output
   // sample rate is provided in |sample_rate_hz|, which must be valid for the
   // codec at hand.
   int Decode(const uint8_t* encoded,
              size_t encoded_len,
              int sample_rate_hz,
@@ skipping 69 matching lines @@
                                       int sample_rate_hz,
                                       int16_t* decoded,
                                       SpeechType* speech_type);
 
  private:
   RTC_DISALLOW_COPY_AND_ASSIGN(AudioDecoder);
 };
 
 }  // namespace webrtc
 #endif  // WEBRTC_MODULES_AUDIO_CODING_NETEQ_INCLUDE_AUDIO_DECODER_H_