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/. */
7 #if !defined(MediaDataDemuxer_h)
8 # define MediaDataDemuxer_h
10 # include "DecoderDoctorLogger.h"
11 # include "mozilla/MozPromise.h"
12 # include "mozilla/UniquePtr.h"
14 # include "MediaData.h"
15 # include "MediaInfo.h"
16 # include "MediaResult.h"
17 # include "TimeUnits.h"
18 # include "nsISupportsImpl.h"
19 # include "mozilla/RefPtr.h"
20 # include "nsTArray.h"
24 class MediaTrackDemuxer
;
25 class TrackMetadataHolder
;
27 DDLoggedTypeDeclName(MediaDataDemuxer
);
28 DDLoggedTypeName(MediaTrackDemuxer
);
30 // Allows reading the media data: to retrieve the metadata and demux samples.
31 // MediaDataDemuxer isn't designed to be thread safe.
32 // When used by the MediaFormatDecoder, care is taken to ensure that the demuxer
33 // will never be called from more than one thread at once.
34 class MediaDataDemuxer
: public DecoderDoctorLifeLogger
<MediaDataDemuxer
> {
36 NS_INLINE_DECL_THREADSAFE_REFCOUNTING(MediaDataDemuxer
)
38 typedef MozPromise
<MediaResult
, MediaResult
, /* IsExclusive = */ true>
41 // Initializes the demuxer. Other methods cannot be called unless
42 // initialization has completed and succeeded.
43 // Typically a demuxer will wait to parse the metadata before resolving the
44 // promise. The promise must not be resolved until sufficient data is
45 // supplied. For example, an incomplete metadata would cause the promise to be
46 // rejected should no more data be coming, while the demuxer would wait
48 virtual RefPtr
<InitPromise
> Init() = 0;
50 // Returns the number of tracks of aType type available. A value of
51 // 0 indicates that no such type is available.
52 virtual uint32_t GetNumberTracks(TrackInfo::TrackType aType
) const = 0;
54 // Returns the MediaTrackDemuxer associated with aTrackNumber aType track.
55 // aTrackNumber is not to be confused with the Track ID.
56 // aTrackNumber must be constrained between 0 and GetNumberTracks(aType) - 1
57 // The actual Track ID is to be retrieved by calling
58 // MediaTrackDemuxer::TrackInfo.
59 virtual already_AddRefed
<MediaTrackDemuxer
> GetTrackDemuxer(
60 TrackInfo::TrackType aType
, uint32_t aTrackNumber
) = 0;
62 // Returns true if the underlying resource allows seeking.
63 virtual bool IsSeekable() const = 0;
65 // Returns true if the underlying resource can only seek within buffered
67 virtual bool IsSeekableOnlyInBufferedRanges() const { return false; }
69 // Returns the media's crypto information, or nullptr if media isn't
71 virtual UniquePtr
<EncryptionInfo
> GetCrypto() { return nullptr; }
73 // Notifies the demuxer that the underlying resource has received more data
74 // since the demuxer was initialized.
75 // The demuxer can use this mechanism to inform all track demuxers that new
76 // data is available and to refresh its buffered range.
77 virtual void NotifyDataArrived() {}
79 // Notifies the demuxer that the underlying resource has had data removed
80 // since the demuxer was initialized.
81 // The demuxer can use this mechanism to inform all track demuxers to update
82 // its buffered range.
83 // This will be called should the demuxer be used with MediaSource.
84 virtual void NotifyDataRemoved() {}
86 // Indicate to MediaFormatReader if it should compute the start time
87 // of the demuxed data. If true (default) the first sample returned will be
88 // used as reference time base.
89 virtual bool ShouldComputeStartTime() const { return true; }
92 virtual ~MediaDataDemuxer() = default;
95 class MediaTrackDemuxer
: public DecoderDoctorLifeLogger
<MediaTrackDemuxer
> {
97 NS_INLINE_DECL_THREADSAFE_REFCOUNTING(MediaTrackDemuxer
)
101 NS_INLINE_DECL_THREADSAFE_REFCOUNTING(SamplesHolder
)
103 void AppendSample(RefPtr
<MediaRawData
>& aSample
) {
104 MOZ_DIAGNOSTIC_ASSERT(aSample
->HasValidTime());
105 mSamples
.AppendElement(aSample
);
108 const nsTArray
<RefPtr
<MediaRawData
>>& GetSamples() const {
112 // This method is only used to do the move semantic for mSamples, do not
113 // append any element to the samples we returns. We should always append new
114 // sample to mSamples via `AppendSample()`.
115 nsTArray
<RefPtr
<MediaRawData
>>& GetMovableSamples() { return mSamples
; }
118 ~SamplesHolder() = default;
119 nsTArray
<RefPtr
<MediaRawData
>> mSamples
;
122 class SkipFailureHolder
{
124 SkipFailureHolder(const MediaResult
& aFailure
, uint32_t aSkipped
)
125 : mFailure(aFailure
), mSkipped(aSkipped
) {}
126 MediaResult mFailure
;
130 typedef MozPromise
<media::TimeUnit
, MediaResult
, /* IsExclusive = */ true>
132 typedef MozPromise
<RefPtr
<SamplesHolder
>, MediaResult
,
133 /* IsExclusive = */ true>
135 typedef MozPromise
<uint32_t, SkipFailureHolder
, /* IsExclusive = */ true>
136 SkipAccessPointPromise
;
138 // Returns the TrackInfo (a.k.a Track Description) for this track.
139 // The TrackInfo returned will be:
140 // TrackInfo::kVideoTrack -> VideoInfo.
141 // TrackInfo::kAudioTrack -> AudioInfo.
143 virtual UniquePtr
<TrackInfo
> GetInfo() const = 0;
145 // Seeks to aTime. Upon success, SeekPromise will be resolved with the
146 // actual time seeked to. Typically the random access point time
147 virtual RefPtr
<SeekPromise
> Seek(const media::TimeUnit
& aTime
) = 0;
149 // Returns the next aNumSamples sample(s) available.
150 // If only a lesser amount of samples is available, only those will be
152 // A aNumSamples value of -1 indicates to return all remaining samples.
153 // A video sample is typically made of a single video frame while an audio
154 // sample will contains multiple audio frames.
155 virtual RefPtr
<SamplesPromise
> GetSamples(int32_t aNumSamples
= 1) = 0;
157 // Returns true if a call to GetSamples() may block while waiting on the
158 // underlying resource to return the data.
159 // This is used by the MediaFormatReader to determine if buffering heuristics
161 virtual bool GetSamplesMayBlock() const { return true; }
163 // Cancel all pending actions (Seek, GetSamples) and reset current state
164 // All pending promises are to be rejected with CANCEL.
165 // The next call to GetSamples would return the first sample available in the
167 virtual void Reset() = 0;
169 // Returns timestamp of next random access point or an error if the demuxer
170 // can't report this.
171 virtual nsresult
GetNextRandomAccessPoint(media::TimeUnit
* aTime
) {
172 return NS_ERROR_NOT_IMPLEMENTED
;
175 // Returns timestamp of previous random access point or an error if the
176 // demuxer can't report this.
177 virtual nsresult
GetPreviousRandomAccessPoint(media::TimeUnit
* aTime
) {
178 return NS_ERROR_NOT_IMPLEMENTED
;
181 // Skip frames until the next Random Access Point located after
183 // The first frame returned by the next call to GetSamples() will be the
184 // first random access point found after aTimeThreshold.
185 // Upon success, returns the number of frames skipped.
186 virtual RefPtr
<SkipAccessPointPromise
> SkipToNextRandomAccessPoint(
187 const media::TimeUnit
& aTimeThreshold
) = 0;
189 // Gets the resource's offset used for the last Seek() or GetSample().
190 // A negative value indicates that this functionality isn't supported.
191 virtual int64_t GetResourceOffset() const { return -1; }
193 virtual TrackInfo::TrackType
GetType() const { return GetInfo()->GetType(); }
195 virtual media::TimeIntervals
GetBuffered() = 0;
197 // By default, it is assumed that the entire resource can be evicted once
198 // all samples have been demuxed.
199 virtual int64_t GetEvictionOffset(const media::TimeUnit
& aTime
) {
203 // If the MediaTrackDemuxer and MediaDataDemuxer hold cross references.
204 // BreakCycles must be overridden.
205 virtual void BreakCycles() {}
208 virtual ~MediaTrackDemuxer() = default;
211 } // namespace mozilla
213 #endif // MediaDataDemuxer_h