media/cast/audio_receiver/audio_receiver.h

   1 // Copyright 2013 The Chromium Authors. All rights reserved.
   2 // Use of this source code is governed by a BSD-style license that can be
   3 // found in the LICENSE file.
   4
   5 #ifndef MEDIA_CAST_AUDIO_RECEIVER_AUDIO_RECEIVER_H_
   6 #define MEDIA_CAST_AUDIO_RECEIVER_AUDIO_RECEIVER_H_
   7
   8 #include "base/basictypes.h"
   9 #include "base/callback.h"
  10 #include "base/macros.h"
  11 #include "base/memory/ref_counted.h"
  12 #include "base/memory/scoped_ptr.h"
  13 #include "base/memory/weak_ptr.h"
  14 #include "base/threading/non_thread_safe.h"
  15 #include "base/time/tick_clock.h"
  16 #include "base/time/time.h"
  17 #include "media/cast/cast_config.h"
  18 #include "media/cast/cast_environment.h"
  19 #include "media/cast/cast_receiver.h"
  20 #include "media/cast/framer/framer.h"
  21 #include "media/cast/rtcp/receiver_rtcp_event_subscriber.h"
  22 #include "media/cast/rtcp/rtcp.h"
  23 #include "media/cast/rtp_receiver/rtp_receiver.h"
  24 #include "media/cast/rtp_receiver/rtp_receiver_defines.h"
  25 #include "media/cast/transport/utility/transport_encryption_handler.h"
  26
  27 namespace media {
  28 namespace cast {
  29
  30 class AudioDecoder;
  31
  32 // AudioReceiver receives packets out-of-order while clients make requests for
  33 // complete frames in-order.  (A frame consists of one or more packets.)
  34 //
  35 // AudioReceiver also includes logic for computing the playout time for each
  36 // frame, accounting for a constant targeted playout delay.  The purpose of the
  37 // playout delay is to provide a fixed window of time between the capture event
  38 // on the sender and the playout on the receiver.  This is important because
  39 // each step of the pipeline (i.e., encode frame, then transmit/retransmit from
  40 // the sender, then receive and re-order packets on the receiver, then decode
  41 // frame) can vary in duration and is typically very hard to predict.
  42 // Heuristics will determine when the targeted playout delay is insufficient in
  43 // the current environment; and the receiver can then increase the playout
  44 // delay, notifying the sender, to account for the extra variance.
  45 // TODO(miu): Make the last sentence true.  http://crbug.com/360111
  46 //
  47 // Two types of frames can be requested: 1) A frame of decoded audio data; or 2)
  48 // a frame of still-encoded audio data, to be passed into an external audio
  49 // decoder.  Each request for a frame includes a callback which AudioReceiver
  50 // guarantees will be called at some point in the future unless the
  51 // AudioReceiver is destroyed.  Clients should generally limit the number of
  52 // outstanding requests (perhaps to just one or two).
  53 //
  54 // This class is not thread safe.  Should only be called from the Main cast
  55 // thread.
  56 class AudioReceiver : public RtpReceiver,
  57                       public RtpPayloadFeedback,
  58                       public base::NonThreadSafe,
  59                       public base::SupportsWeakPtr<AudioReceiver> {
  60  public:
  61   AudioReceiver(scoped_refptr<CastEnvironment> cast_environment,
  62                 const AudioReceiverConfig& audio_config,
  63                 transport::PacedPacketSender* const packet_sender);
  64
  65   virtual ~AudioReceiver();
  66
  67   // Request a decoded audio frame.  The audio signal data returned in the
  68   // callback will have the sampling rate and number of channels as requested in
  69   // the configuration that was passed to the ctor.
  70   //
  71   // The given |callback| is guaranteed to be run at some point in the future,
  72   // even if to respond with NULL at shutdown time.
  73   void GetRawAudioFrame(const AudioFrameDecodedCallback& callback);
  74
  75   // Request an encoded audio frame.
  76   //
  77   // The given |callback| is guaranteed to be run at some point in the future,
  78   // even if to respond with NULL at shutdown time.
  79   void GetEncodedAudioFrame(const FrameEncodedCallback& callback);
  80
  81   // Deliver another packet, possibly a duplicate, and possibly out-of-order.
  82   void IncomingPacket(scoped_ptr<Packet> packet);
  83
  84   // Update target audio delay used to compute the playout time. Rtcp
  85   // will also be updated (will be included in all outgoing reports).
  86   void SetTargetDelay(base::TimeDelta target_delay);
  87
  88  protected:
  89   friend class AudioReceiverTest;  // Invokes OnReceivedPayloadData().
  90
  91   virtual void OnReceivedPayloadData(const uint8* payload_data,
  92                                      size_t payload_size,
  93                                      const RtpCastHeader& rtp_header) OVERRIDE;
  94
  95   // RtpPayloadFeedback implementation.
  96   virtual void CastFeedback(const RtcpCastMessage& cast_message) OVERRIDE;
  97
  98  private:
  99   // Processes ready-to-consume packets from |framer_|, decrypting each packet's
 100   // payload data, and then running the enqueued callbacks in order (one for
 101   // each packet).  This method may post a delayed task to re-invoke itself in
 102   // the future to wait for missing/incomplete frames.
 103   void EmitAvailableEncodedFrames();
 104
 105   // Clears the |is_waiting_for_consecutive_frame_| flag and invokes
 106   // EmitAvailableEncodedFrames().
 107   void EmitAvailableEncodedFramesAfterWaiting();
 108
 109   // Feeds an EncodedFrame into |audio_decoder_|.  GetRawAudioFrame() uses this
 110   // as a callback for GetEncodedAudioFrame().
 111   void DecodeEncodedAudioFrame(
 112       const AudioFrameDecodedCallback& callback,
 113       scoped_ptr<transport::EncodedFrame> encoded_frame);
 114
 115   // Return the playout time based on the current time and rtp timestamp.
 116   base::TimeTicks GetPlayoutTime(base::TimeTicks now, uint32 rtp_timestamp);
 117
 118   void InitializeTimers();
 119
 120   // Schedule the next RTCP report.
 121   void ScheduleNextRtcpReport();
 122
 123   // Actually send the next RTCP report.
 124   void SendNextRtcpReport();
 125
 126   // Schedule timing for the next cast message.
 127   void ScheduleNextCastMessage();
 128
 129   // Actually send the next cast message.
 130   void SendNextCastMessage();
 131
 132   // Receives an AudioBus from |audio_decoder_|, logs the event, and passes the
 133   // data on by running the given |callback|.  This method is static to ensure
 134   // it can be called after an AudioReceiver instance is destroyed.
 135   // DecodeEncodedAudioFrame() uses this as a callback for
 136   // AudioDecoder::DecodeFrame().
 137   static void EmitRawAudioFrame(
 138       const scoped_refptr<CastEnvironment>& cast_environment,
 139       const AudioFrameDecodedCallback& callback,
 140       uint32 frame_id,
 141       uint32 rtp_timestamp,
 142       const base::TimeTicks& playout_time,
 143       scoped_ptr<AudioBus> audio_bus,
 144       bool is_continuous);
 145
 146   const scoped_refptr<CastEnvironment> cast_environment_;
 147
 148   // Subscribes to raw events.
 149   // Processes raw audio events to be sent over to the cast sender via RTCP.
 150   ReceiverRtcpEventSubscriber event_subscriber_;
 151
 152   const transport::AudioCodec codec_;
 153   const int frequency_;
 154   base::TimeDelta target_delay_delta_;
 155   Framer framer_;
 156   scoped_ptr<AudioDecoder> audio_decoder_;
 157   Rtcp rtcp_;
 158   base::TimeDelta time_offset_;
 159   base::TimeTicks time_first_incoming_packet_;
 160   uint32 first_incoming_rtp_timestamp_;
 161   transport::TransportEncryptionHandler decryptor_;
 162
 163   // Outstanding callbacks to run to deliver on client requests for frames.
 164   std::list<FrameEncodedCallback> frame_request_queue_;
 165
 166   // True while there's an outstanding task to re-invoke
 167   // EmitAvailableEncodedFrames().
 168   bool is_waiting_for_consecutive_frame_;
 169
 170   // This mapping allows us to log AUDIO_ACK_SENT as a frame event. In addition
 171   // it allows the event to be transmitted via RTCP.
 172   RtpTimestamp frame_id_to_rtp_timestamp_[256];
 173
 174   // NOTE: Weak pointers must be invalidated before all other member variables.
 175   base::WeakPtrFactory<AudioReceiver> weak_factory_;
 176
 177   DISALLOW_COPY_AND_ASSIGN(AudioReceiver);
 178 };
 179
 180 }  // namespace cast
 181 }  // namespace media
 182
 183 #endif  // MEDIA_CAST_AUDIO_RECEIVER_AUDIO_RECEIVER_H_