src/media/cast/receiver/frame_receiver.h

   1 // Copyright 2014 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_RECEIVER_FRAME_RECEIVER_H_
   6 #define MEDIA_CAST_RECEIVER_FRAME_RECEIVER_H_
   7
   8 #include "base/memory/ref_counted.h"
   9 #include "base/memory/scoped_ptr.h"
  10 #include "base/memory/weak_ptr.h"
  11 #include "base/time/time.h"
  12 #include "media/cast/cast_config.h"
  13 #include "media/cast/cast_receiver.h"
  14 #include "media/cast/common/clock_drift_smoother.h"
  15 #include "media/cast/common/transport_encryption_handler.h"
  16 #include "media/cast/logging/logging_defines.h"
  17 #include "media/cast/net/rtcp/receiver_rtcp_event_subscriber.h"
  18 #include "media/cast/net/rtcp/rtcp.h"
  19 #include "media/cast/net/rtp/framer.h"
  20 #include "media/cast/net/rtp/receiver_stats.h"
  21 #include "media/cast/net/rtp/rtp_parser.h"
  22 #include "media/cast/net/rtp/rtp_receiver_defines.h"
  23
  24 namespace media {
  25 namespace cast {
  26
  27 class CastEnvironment;
  28
  29 // FrameReceiver receives packets out-of-order while clients make requests for
  30 // complete frames in-order.  (A frame consists of one or more packets.)
  31 //
  32 // FrameReceiver also includes logic for computing the playout time for each
  33 // frame, accounting for a constant targeted playout delay.  The purpose of the
  34 // playout delay is to provide a fixed window of time between the capture event
  35 // on the sender and the playout on the receiver.  This is important because
  36 // each step of the pipeline (i.e., encode frame, then transmit/retransmit from
  37 // the sender, then receive and re-order packets on the receiver, then decode
  38 // frame) can vary in duration and is typically very hard to predict.
  39 //
  40 // Each request for a frame includes a callback which FrameReceiver guarantees
  41 // will be called at some point in the future unless the FrameReceiver is
  42 // destroyed.  Clients should generally limit the number of outstanding requests
  43 // (perhaps to just one or two).
  44 //
  45 // This class is not thread safe.  Should only be called from the Main cast
  46 // thread.
  47 class FrameReceiver : public RtpPayloadFeedback,
  48                       public base::SupportsWeakPtr<FrameReceiver> {
  49  public:
  50   FrameReceiver(const scoped_refptr<CastEnvironment>& cast_environment,
  51                 const FrameReceiverConfig& config,
  52                 EventMediaType event_media_type,
  53                 PacedPacketSender* const packet_sender);
  54
  55   virtual ~FrameReceiver();
  56
  57   // Request an encoded frame.
  58   //
  59   // The given |callback| is guaranteed to be run at some point in the future,
  60   // except for those requests still enqueued at destruction time.
  61   void RequestEncodedFrame(const ReceiveEncodedFrameCallback& callback);
  62
  63   // Called to deliver another packet, possibly a duplicate, and possibly
  64   // out-of-order.  Returns true if the parsing of the packet succeeded.
  65   bool ProcessPacket(scoped_ptr<Packet> packet);
  66
  67   // TODO(miu): This is the wrong place for this, but the (de)serialization
  68   // implementation needs to be consolidated first.
  69   static bool ParseSenderSsrc(const uint8* packet, size_t length, uint32* ssrc);
  70
  71  protected:
  72   friend class FrameReceiverTest;  // Invokes ProcessParsedPacket().
  73
  74   void ProcessParsedPacket(const RtpCastHeader& rtp_header,
  75                            const uint8* payload_data,
  76                            size_t payload_size);
  77
  78   // RtpPayloadFeedback implementation.
  79   virtual void CastFeedback(const RtcpCastMessage& cast_message) OVERRIDE;
  80
  81  private:
  82   // Processes ready-to-consume packets from |framer_|, decrypting each packet's
  83   // payload data, and then running the enqueued callbacks in order (one for
  84   // each packet).  This method may post a delayed task to re-invoke itself in
  85   // the future to wait for missing/incomplete frames.
  86   void EmitAvailableEncodedFrames();
  87
  88   // Clears the |is_waiting_for_consecutive_frame_| flag and invokes
  89   // EmitAvailableEncodedFrames().
  90   void EmitAvailableEncodedFramesAfterWaiting();
  91
  92   // Helper that runs |callback|, passing ownership of |encoded_frame| to it.
  93   // This method is used by EmitAvailableEncodedFrames() to return to the event
  94   // loop, but make sure that FrameReceiver is still alive before the callback
  95   // is run.
  96   void EmitOneFrame(const ReceiveEncodedFrameCallback& callback,
  97                     scoped_ptr<EncodedFrame> encoded_frame) const;
  98
  99   // Computes the playout time for a frame with the given |rtp_timestamp|.
 100   // Because lip-sync info is refreshed regularly, calling this method with the
 101   // same argument may return different results.
 102   base::TimeTicks GetPlayoutTime(const EncodedFrame& frame) const;
 103
 104   // Schedule timing for the next cast message.
 105   void ScheduleNextCastMessage();
 106
 107   // Schedule timing for the next RTCP report.
 108   void ScheduleNextRtcpReport();
 109
 110   // Actually send the next cast message.
 111   void SendNextCastMessage();
 112
 113   // Actually send the next RTCP report.
 114   void SendNextRtcpReport();
 115
 116   const scoped_refptr<CastEnvironment> cast_environment_;
 117
 118   // Deserializes a packet into a RtpHeader + payload bytes.
 119   RtpParser packet_parser_;
 120
 121   // Accumulates packet statistics, including packet loss, counts, and jitter.
 122   ReceiverStats stats_;
 123
 124   // Partitions logged events by the type of media passing through.
 125   EventMediaType event_media_type_;
 126
 127   // Subscribes to raw events.
 128   // Processes raw events to be sent over to the cast sender via RTCP.
 129   ReceiverRtcpEventSubscriber event_subscriber_;
 130
 131   // RTP timebase: The number of RTP units advanced per one second.
 132   const int rtp_timebase_;
 133
 134   // The total amount of time between a frame's capture/recording on the sender
 135   // and its playback on the receiver (i.e., shown to a user).  This is fixed as
 136   // a value large enough to give the system sufficient time to encode,
 137   // transmit/retransmit, receive, decode, and render; given its run-time
 138   // environment (sender/receiver hardware performance, network conditions,
 139   // etc.).
 140   base::TimeDelta target_playout_delay_;
 141
 142   // Hack: This is used in logic that determines whether to skip frames.
 143   // TODO(miu): Revisit this.  Logic needs to also account for expected decode
 144   // time.
 145   const base::TimeDelta expected_frame_duration_;
 146
 147   // Set to false initially, then set to true after scheduling the periodic
 148   // sending of reports back to the sender.  Reports are first scheduled just
 149   // after receiving a first packet (since the first packet identifies the
 150   // sender for the remainder of the session).
 151   bool reports_are_scheduled_;
 152
 153   // Assembles packets into frames, providing this receiver with complete,
 154   // decodable EncodedFrames.
 155   Framer framer_;
 156
 157   // Manages sending/receiving of RTCP packets, including sender/receiver
 158   // reports.
 159   Rtcp rtcp_;
 160
 161   // Decrypts encrypted frames.
 162   TransportEncryptionHandler decryptor_;
 163
 164   // Outstanding callbacks to run to deliver on client requests for frames.
 165   std::list<ReceiveEncodedFrameCallback> frame_request_queue_;
 166
 167   // True while there's an outstanding task to re-invoke
 168   // EmitAvailableEncodedFrames().
 169   bool is_waiting_for_consecutive_frame_;
 170
 171   // This mapping allows us to log FRAME_ACK_SENT as a frame event. In addition
 172   // it allows the event to be transmitted via RTCP.
 173   RtpTimestamp frame_id_to_rtp_timestamp_[256];
 174
 175   // Lip-sync values used to compute the playout time of each frame from its RTP
 176   // timestamp.  These are updated each time the first packet of a frame is
 177   // received.
 178   RtpTimestamp lip_sync_rtp_timestamp_;
 179   base::TimeTicks lip_sync_reference_time_;
 180   ClockDriftSmoother lip_sync_drift_;
 181
 182   // Time interval for sending a RTCP report.
 183   const base::TimeDelta rtcp_interval_;
 184
 185   // NOTE: Weak pointers must be invalidated before all other member variables.
 186   base::WeakPtrFactory<FrameReceiver> weak_factory_;
 187
 188   DISALLOW_COPY_AND_ASSIGN(FrameReceiver);
 189 };
 190
 191 }  // namespace cast
 192 }  // namespace media
 193
 194 #endif  // MEDIA_CAST_RECEIVER_FRAME_RECEIVER_H_