1 // Copyright 2021 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 CAST_STREAMING_RECEIVER_BASE_H_ 6 #define CAST_STREAMING_RECEIVER_BASE_H_ 7 8 #include <chrono> 9 10 #include "absl/types/span.h" 11 #include "cast/streaming/encoded_frame.h" 12 #include "cast/streaming/session_config.h" 13 #include "cast/streaming/ssrc.h" 14 #include "platform/api/time.h" 15 16 namespace openscreen { 17 namespace cast { 18 19 // The Cast Streaming Receiver, a peer corresponding to some Cast Streaming 20 // Sender at the other end of a network link. 21 // 22 // Cast Streaming is a transport protocol which divides up the frames for one 23 // media stream (e.g., audio or video) into multiple RTP packets containing an 24 // encrypted payload. The Receiver is the peer responsible for collecting the 25 // RTP packets, decrypting the payload, and re-assembling a frame that can be 26 // passed to a decoder and played out. 27 // 28 // A Sender ↔ Receiver pair is used to transport each media stream. Typically, 29 // there are two pairs in a normal system, one for the audio stream and one for 30 // video stream. A local player is responsible for synchronizing the playout of 31 // the frames of each stream to achieve lip-sync. See the discussion in 32 // encoded_frame.h for how the |reference_time| and |rtp_timestamp| of the 33 // EncodedFrames are used to achieve this. 34 class ReceiverBase { 35 public: 36 class Consumer { 37 public: 38 virtual ~Consumer(); 39 40 // Called whenever one or more frames have become ready for consumption. The 41 // |next_frame_buffer_size| argument is identical to the result of calling 42 // AdvanceToNextFrame(), and so the Consumer only needs to prepare a buffer 43 // and call ConsumeNextFrame(). It may then call AdvanceToNextFrame() to 44 // check whether there are any more frames ready, but this is not mandatory. 45 // See usage example in class-level comments. 46 virtual void OnFramesReady(int next_frame_buffer_size) = 0; 47 }; 48 49 ReceiverBase(); 50 virtual ~ReceiverBase(); 51 52 virtual const SessionConfig& config() const = 0; 53 virtual int rtp_timebase() const = 0; 54 virtual Ssrc ssrc() const = 0; 55 56 // Set the Consumer receiving notifications when new frames are ready for 57 // consumption. Frames received before this method is called will remain in 58 // the queue indefinitely. 59 virtual void SetConsumer(Consumer* consumer) = 0; 60 61 // Sets how much time the consumer will need to decode/buffer/render/etc., and 62 // otherwise fully process a frame for on-time playback. This information is 63 // used by the Receiver to decide whether to skip past frames that have 64 // arrived too late. This method can be called repeatedly to make adjustments 65 // based on changing environmental conditions. 66 // 67 // Default setting: kDefaultPlayerProcessingTime 68 virtual void SetPlayerProcessingTime(Clock::duration needed_time) = 0; 69 70 // Propagates a "picture loss indicator" notification to the Sender, 71 // requesting a key frame so that decode/playout can recover. It is safe to 72 // call this redundantly. The Receiver will clear the picture loss condition 73 // automatically, once a key frame is received (i.e., before 74 // ConsumeNextFrame() is called to access it). 75 virtual void RequestKeyFrame() = 0; 76 77 // Advances to the next frame ready for consumption. This may skip-over 78 // incomplete frames that will not play out on-time; but only if there are 79 // completed frames further down the queue that have no dependency 80 // relationship with them (e.g., key frames). 81 // 82 // This method returns kNoFramesReady if there is not currently a frame ready 83 // for consumption. The caller should wait for a Consumer::OnFramesReady() 84 // notification before trying again. Otherwise, the number of bytes of encoded 85 // data is returned, and the caller should use this to ensure the buffer it 86 // passes to ConsumeNextFrame() is large enough. 87 virtual int AdvanceToNextFrame() = 0; 88 89 // Returns the next frame, both metadata and payload data. The Consumer calls 90 // this method after being notified via OnFramesReady(), and it can also call 91 // this whenever AdvanceToNextFrame() indicates another frame is ready. 92 // |buffer| must point to a sufficiently-sized buffer that will be populated 93 // with the frame's payload data. Upon return |frame->data| will be set to the 94 // portion of the buffer that was populated. 95 virtual EncodedFrame ConsumeNextFrame(absl::Span<uint8_t> buffer) = 0; 96 97 // The default "player processing time" amount. See SetPlayerProcessingTime(). 98 static constexpr std::chrono::milliseconds kDefaultPlayerProcessingTime{5}; 99 100 // Returned by AdvanceToNextFrame() when there are no frames currently ready 101 // for consumption. 102 static constexpr int kNoFramesReady = -1; 103 }; 104 105 } // namespace cast 106 } // namespace openscreen 107 108 #endif // CAST_STREAMING_RECEIVER_BASE_H_ 109