Line data    Source code

       1             : /* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
       2             : /* vim: set ts=8 sts=2 et sw=2 tw=80: */
       3             : /* This Source Code Form is subject to the terms of the Mozilla Public
       4             :  * License, v. 2.0. If a copy of the MPL was not distributed with this
       5             :  * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
       6             : 
       7             : #ifndef MediaSink_h_
       8             : #define MediaSink_h_
       9             : 
      10             : #include "mozilla/RefPtr.h"
      11             : #include "mozilla/MozPromise.h"
      12             : #include "nsISupportsImpl.h"
      13             : #include "MediaInfo.h"
      14             : 
      15             : namespace mozilla {
      16             : 
      17             : class TimeStamp;
      18             : 
      19             : namespace media {
      20             : 
      21             : /**
      22             :  * A consumer of audio/video data which plays audio and video tracks and
      23             :  * manages A/V sync between them.
      24             :  *
      25             :  * A typical sink sends audio/video outputs to the speaker and screen.
      26             :  * However, there are also sinks which capture the output of an media element
      27             :  * and send the output to a MediaStream.
      28             :  *
      29             :  * This class is used to move A/V sync management and audio/video rendering
      30             :  * out of MDSM so it is possible for subclasses to do external rendering using
      31             :  * specific hardware which is required by TV projects and CDM.
      32             :  *
      33             :  * Note this class is not thread-safe and should be called from the state
      34             :  * machine thread only.
      35             :  */
      36           0 : class MediaSink {
      37             : public:
      38           0 :   NS_INLINE_DECL_THREADSAFE_REFCOUNTING(MediaSink);
      39             :   typedef mozilla::TrackInfo::TrackType TrackType;
      40             : 
      41             :   struct PlaybackParams {
      42           0 :     PlaybackParams()
      43           0 :       : mVolume(1.0) , mPlaybackRate(1.0) , mPreservesPitch(true) {}
      44             :     double mVolume;
      45             :     double mPlaybackRate;
      46             :     bool mPreservesPitch;
      47             :   };
      48             : 
      49             :   // Return the playback parameters of this sink.
      50             :   // Can be called in any state.
      51             :   virtual const PlaybackParams& GetPlaybackParams() const = 0;
      52             : 
      53             :   // Set the playback parameters of this sink.
      54             :   // Can be called in any state.
      55             :   virtual void SetPlaybackParams(const PlaybackParams& aParams) = 0;
      56             : 
      57             :   // Return a promise which is resolved when the track finishes
      58             :   // or null if no such track.
      59             :   // Must be called after playback starts.
      60             :   virtual RefPtr<GenericPromise> OnEnded(TrackType aType) = 0;
      61             : 
      62             :   // Return the end time of the audio/video data that has been consumed
      63             :   // or 0 if no such track.
      64             :   // Must be called after playback starts.
      65             :   virtual TimeUnit GetEndTime(TrackType aType) const = 0;
      66             : 
      67             :   // Return playback position of the media.
      68             :   // Since A/V sync is always maintained by this sink, there is no need to
      69             :   // specify whether we want to get audio or video position.
      70             :   // aTimeStamp returns the timeStamp corresponding to the returned position
      71             :   // which is used by the compositor to derive the render time of video frames.
      72             :   // Must be called after playback starts.
      73             :   virtual TimeUnit GetPosition(TimeStamp* aTimeStamp = nullptr) const = 0;
      74             : 
      75             :   // Return true if there are data consumed but not played yet.
      76             :   // Can be called in any state.
      77             :   virtual bool HasUnplayedFrames(TrackType aType) const = 0;
      78             : 
      79             :   // Set volume of the audio track.
      80             :   // Do nothing if this sink has no audio track.
      81             :   // Can be called in any state.
      82           0 :   virtual void SetVolume(double aVolume) {}
      83             : 
      84             :   // Set the playback rate.
      85             :   // Can be called in any state.
      86           0 :   virtual void SetPlaybackRate(double aPlaybackRate) {}
      87             : 
      88             :   // Whether to preserve pitch of the audio track.
      89             :   // Do nothing if this sink has no audio track.
      90             :   // Can be called in any state.
      91           0 :   virtual void SetPreservesPitch(bool aPreservesPitch) {}
      92             : 
      93             :   // Pause/resume the playback. Only work after playback starts.
      94             :   virtual void SetPlaying(bool aPlaying) = 0;
      95             : 
      96             :   // Single frame rendering operation may need to be done before playback
      97             :   // started (1st frame) or right after seek completed or playback stopped.
      98             :   // Do nothing if this sink has no video track. Can be called in any state.
      99           0 :   virtual void Redraw(const VideoInfo& aInfo) {};
     100             : 
     101             :   // Begin a playback session with the provided start time and media info.
     102             :   // Must be called when playback is stopped.
     103             :   virtual void Start(const TimeUnit& aStartTime, const MediaInfo& aInfo) = 0;
     104             : 
     105             :   // Finish a playback session.
     106             :   // Must be called after playback starts.
     107             :   virtual void Stop() = 0;
     108             : 
     109             :   // Return true if playback has started.
     110             :   // Can be called in any state.
     111             :   virtual bool IsStarted() const = 0;
     112             : 
     113             :   // Return true if playback is started and not paused otherwise false.
     114             :   // Can be called in any state.
     115             :   virtual bool IsPlaying() const = 0;
     116             : 
     117             :   // Called on the state machine thread to shut down the sink. All resources
     118             :   // allocated by this sink should be released.
     119             :   // Must be called after playback stopped.
     120           0 :   virtual void Shutdown() {}
     121             : 
     122             :   // Return a string containing debugging information.
     123             :   // Can be called in any phase.
     124           0 :   virtual nsCString GetDebugInfo() { return nsCString(); }
     125             : 
     126             : protected:
     127           0 :   virtual ~MediaSink() {}
     128             : };
     129             : 
     130             : } // namespace media
     131             : } // namespace mozilla
     132             : 
     133             : #endif //MediaSink_h_