summaryrefslogtreecommitdiffstats
path: root/dom/media/mediasink/MediaSink.h
blob: 9de884d42292376e3bc2033c327c7d5935ccdbf3 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
/* -*- Mode: C++; tab-width: 8; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

#ifndef MediaSink_h_
#define MediaSink_h_

#include "mozilla/RefPtr.h"
#include "mozilla/MozPromise.h"
#include "nsISupportsImpl.h"
#include "MediaInfo.h"

namespace mozilla {

class TimeStamp;

namespace media {

/**
 * A consumer of audio/video data which plays audio and video tracks and
 * manages A/V sync between them.
 *
 * A typical sink sends audio/video outputs to the speaker and screen.
 * However, there are also sinks which capture the output of an media element
 * and send the output to a MediaStream.
 *
 * This class is used to move A/V sync management and audio/video rendering
 * out of MDSM so it is possible for subclasses to do external rendering using
 * specific hardware which is required by TV projects and CDM.
 *
 * Note this class is not thread-safe and should be called from the state
 * machine thread only.
 */
class MediaSink {
public:
  NS_INLINE_DECL_THREADSAFE_REFCOUNTING(MediaSink);
  typedef mozilla::TrackInfo::TrackType TrackType;

  struct PlaybackParams {
    PlaybackParams()
      : mVolume(1.0) , mPlaybackRate(1.0) , mPreservesPitch(true) {}
    double mVolume;
    double mPlaybackRate;
    bool mPreservesPitch;
  };

  // Return the playback parameters of this sink.
  // Can be called in any state.
  virtual const PlaybackParams& GetPlaybackParams() const = 0;

  // Set the playback parameters of this sink.
  // Can be called in any state.
  virtual void SetPlaybackParams(const PlaybackParams& aParams) = 0;

  // Return a promise which is resolved when the track finishes
  // or null if no such track.
  // Must be called after playback starts.
  virtual RefPtr<GenericPromise> OnEnded(TrackType aType) = 0;

  // Return the end time of the audio/video data that has been consumed
  // or -1 if no such track.
  // Must be called after playback starts.
  virtual int64_t GetEndTime(TrackType aType) const = 0;

  // Return playback position of the media.
  // Since A/V sync is always maintained by this sink, there is no need to
  // specify whether we want to get audio or video position.
  // aTimeStamp returns the timeStamp corresponding to the returned position
  // which is used by the compositor to derive the render time of video frames.
  // Must be called after playback starts.
  virtual int64_t GetPosition(TimeStamp* aTimeStamp = nullptr) const = 0;

  // Return true if there are data consumed but not played yet.
  // Can be called in any state.
  virtual bool HasUnplayedFrames(TrackType aType) const = 0;

  // Set volume of the audio track.
  // Do nothing if this sink has no audio track.
  // Can be called in any state.
  virtual void SetVolume(double aVolume) {}

  // Set the playback rate.
  // Can be called in any state.
  virtual void SetPlaybackRate(double aPlaybackRate) {}

  // Whether to preserve pitch of the audio track.
  // Do nothing if this sink has no audio track.
  // Can be called in any state.
  virtual void SetPreservesPitch(bool aPreservesPitch) {}

  // Pause/resume the playback. Only work after playback starts.
  virtual void SetPlaying(bool aPlaying) = 0;

  // Single frame rendering operation may need to be done before playback
  // started (1st frame) or right after seek completed or playback stopped.
  // Do nothing if this sink has no video track. Can be called in any state.
  virtual void Redraw(const VideoInfo& aInfo) {};

  // Begin a playback session with the provided start time and media info.
  // Must be called when playback is stopped.
  virtual void Start(int64_t aStartTime, const MediaInfo& aInfo) = 0;

  // Finish a playback session.
  // Must be called after playback starts.
  virtual void Stop() = 0;

  // Return true if playback has started.
  // Can be called in any state.
  virtual bool IsStarted() const = 0;

  // Return true if playback is started and not paused otherwise false.
  // Can be called in any state.
  virtual bool IsPlaying() const = 0;

  // Called on the state machine thread to shut down the sink. All resources
  // allocated by this sink should be released.
  // Must be called after playback stopped.
  virtual void Shutdown() {}

  // Dump debugging information to the logs.
  // Can be called in any phase.
  virtual void DumpDebugInfo() {}

protected:
  virtual ~MediaSink() {}
};

} // namespace media
} // namespace mozilla

#endif //MediaSink_h_