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|.
+    // |decoded| will be large enough for 120 ms of audio at the decoder's
+    // sample rate. On success, returns an rtc::Optional containing the total

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

Might it be better to simply state that |decoded| will be large enough?

[ossu, 2016/09/16 11:24:16]

I've incorporated the phrasing changes suggested in the next CL into this one.

+    // number of samples across all channels, as well as whether the decoder
+    // produced comfort noise or speech. On failure, returns an empty
+    // rtc::Optional. Decode must be called at most once per frame object.

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

My sometimes reliable sense of English suggests s/must be/may be/.

[ossu, 2016/09/16 11:24:16]

I believe you're right.

+    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 and should never be shorter
+  // than 10 ms. The caller must ensure that the AudioDecoder object outlives

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

This use of "must" and "should" gives the sense that the 10 ms limit may not be
absolute. Perhaps better to say something like

  Frames must be between 10 and 120 ms long.

Are they also required to be an integer multiple of 10 ms?

[hlundin-webrtc, 2016/09/16 07:40:45]

They need not be an integer multiple of 10.

[kwiberg-webrtc, 2016/09/16 07:51:57]

Are there no restrictions whatsoever, except the upper and lower bounds? In that
case, maybe something like

  Frames may be of any length between 10 and 120 ms.

[hlundin-webrtc, 2016/09/16 08:25:02]

In theory, no other restrictions. In practice I cannot be sure. I think our
tests are only running 10, 20, 25, 30, so NetEq works with those at least.

[ossu, 2016/09/16 11:24:16]

Acknowledged.

+  // any frame objects returned by this call. The decoder is free to swap or
+  // move the data from the |payload| buffer. |timestamp| is the input
+  // timestamp, in samples, corresponding to the start of the payload.
+  virtual std::vector<ParseResult> ParsePayload(rtc::Buffer&& payload,
+                                                uint32_t timestamp,
+                                                bool is_primary);
+
   // 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_