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
24namespace media {
25namespace cast {
26
27class 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.
47class 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_
195