1 // Copyright (c) 2012 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.
5 // SourceBufferStream is a data structure that stores media Buffers in ranges.
6 // Buffers can be appended out of presentation order. Buffers are retrieved by
7 // seeking to the desired start point and calling GetNextBuffer(). Buffers are
8 // returned in sequential presentation order.
10 #ifndef MEDIA_FILTERS_SOURCE_BUFFER_STREAM_H_
11 #define MEDIA_FILTERS_SOURCE_BUFFER_STREAM_H_
19 #include "base/memory/ref_counted.h"
20 #include "media/base/audio_decoder_config.h"
21 #include "media/base/media_export.h"
22 #include "media/base/media_log.h"
23 #include "media/base/ranges.h"
24 #include "media/base/stream_parser_buffer.h"
25 #include "media/base/video_decoder_config.h"
29 class SourceBufferRange;
31 // See file-level comment for complete description.
32 class MEDIA_EXPORT SourceBufferStream {
34 typedef std::deque<scoped_refptr<StreamParserBuffer> > BufferQueue;
36 // Status returned by GetNextBuffer().
37 // kSuccess: Indicates that the next buffer was returned.
38 // kNeedBuffer: Indicates that we need more data before a buffer can be
40 // kConfigChange: Indicates that the next buffer requires a config change.
48 SourceBufferStream(const AudioDecoderConfig& audio_config,
50 SourceBufferStream(const VideoDecoderConfig& video_config,
53 ~SourceBufferStream();
55 // Signals that the next buffers appended are part of a new media segment
56 // starting at |media_segment_start_time|.
57 void OnNewMediaSegment(base::TimeDelta media_segment_start_time);
59 // Add the |buffers| to the SourceBufferStream. Buffers within the queue are
60 // expected to be in order, but multiple calls to Append() may add buffers out
61 // of order or overlapping. Assumes all buffers within |buffers| are in
62 // presentation order and are non-overlapping.
63 // Returns true if Append() was successful, false if |buffers| are not added.
64 // TODO(vrk): Implement garbage collection. (crbug.com/125070)
65 bool Append(const BufferQueue& buffers);
67 // Removes buffers between |start| and |end| according to the steps
68 // in the "Coded Frame Removal Algorithm" in the Media Source
70 // https://dvcs.w3.org/hg/html-media/raw-file/default/media-source/media-source.html#sourcebuffer-coded-frame-removal
72 // |duration| is the current duration of the presentation. It is
73 // required by the computation outlined in the spec.
74 void Remove(base::TimeDelta start, base::TimeDelta end,
75 base::TimeDelta duration);
77 // Changes the SourceBufferStream's state so that it will start returning
78 // buffers starting from the closest keyframe before |timestamp|.
79 void Seek(base::TimeDelta timestamp);
81 // Returns true if the SourceBufferStream has seeked to a time without
82 // buffered data and is waiting for more data to be appended.
83 bool IsSeekPending() const;
85 // Notifies the SourceBufferStream that the media duration has been changed to
86 // |duration| so it should drop any data past that point.
87 void OnSetDuration(base::TimeDelta duration);
89 // Fills |out_buffer| with a new buffer. Buffers are presented in order from
90 // the last call to Seek(), or starting with the first buffer appended if
91 // Seek() has not been called yet.
92 // |out_buffer|'s timestamp may be earlier than the |timestamp| passed to
93 // the last Seek() call.
94 // Returns kSuccess if |out_buffer| is filled with a valid buffer, kNeedBuffer
95 // if there is not enough data buffered to fulfill the request, and
96 // kConfigChange if the next buffer requires a config change.
97 Status GetNextBuffer(scoped_refptr<StreamParserBuffer>* out_buffer);
99 // Returns a list of the buffered time ranges.
100 Ranges<base::TimeDelta> GetBufferedTime() const;
102 // Notifies this object that end of stream has been signalled.
103 void MarkEndOfStream();
105 // Clear the end of stream state set by MarkEndOfStream().
106 void UnmarkEndOfStream();
108 const AudioDecoderConfig& GetCurrentAudioDecoderConfig();
109 const VideoDecoderConfig& GetCurrentVideoDecoderConfig();
111 // Notifies this object that the audio config has changed and buffers in
112 // future Append() calls should be associated with this new config.
113 bool UpdateAudioConfig(const AudioDecoderConfig& config);
115 // Notifies this object that the video config has changed and buffers in
116 // future Append() calls should be associated with this new config.
117 bool UpdateVideoConfig(const VideoDecoderConfig& config);
119 // Returns the largest distance between two adjacent buffers in this stream,
120 // or an estimate if no two adjacent buffers have been appended to the stream
122 base::TimeDelta GetMaxInterbufferDistance() const;
124 void set_memory_limit_for_testing(int memory_limit) {
125 memory_limit_ = memory_limit;
129 friend class SourceBufferStreamTest;
131 typedef std::list<SourceBufferRange*> RangeList;
133 // Frees up space if the SourceBufferStream is taking up too much memory.
134 void GarbageCollectIfNeeded();
136 // Attempts to delete approximately |total_bytes_to_free| amount of data
137 // |ranges_|, starting at the front of |ranges_| and moving linearly forward
138 // through the buffers. Deletes starting from the back if |reverse_direction|
139 // is true. Returns the number of bytes freed.
140 int FreeBuffers(int total_bytes_to_free, bool reverse_direction);
142 // Attempts to delete approximately |total_bytes_to_free| amount of data from
143 // |ranges_|, starting after the last appended buffer before the current
144 // playback position.
145 int FreeBuffersAfterLastAppended(int total_bytes_to_free);
147 // Gets the removal range to secure |byte_to_free| from
148 // [|start_timestamp|, |end_timestamp|).
149 // Returns the size of buffers to secure if future
150 // Remove(|start_timestamp|, |removal_end_timestamp|, duration) is called.
151 // Will not update |removal_end_timestamp| if the returned size is 0.
152 int GetRemovalRange(base::TimeDelta start_timestamp,
153 base::TimeDelta end_timestamp, int byte_to_free,
154 base::TimeDelta* removal_end_timestamp);
156 // Prepares |range_for_next_append_| so |new_buffers| can be appended.
157 // This involves removing buffers between the end of the previous append
158 // and any buffers covered by the time range in |new_buffers|.
159 // |deleted_buffers| is an output parameter containing candidates for
160 // |track_buffer_| if this method ends up removing the current playback
161 // position from the range.
162 void PrepareRangesForNextAppend(const BufferQueue& new_buffers,
163 BufferQueue* deleted_buffers);
165 // Removes buffers, from the |track_buffer_|, that come after |timestamp|.
166 void PruneTrackBuffer(const base::TimeDelta timestamp);
168 // Checks to see if |range_with_new_buffers_itr| can be merged with the range
169 // next to it, and merges them if so.
170 void MergeWithAdjacentRangeIfNecessary(
171 const RangeList::iterator& range_with_new_buffers_itr);
173 // Returns true if |second_timestamp| is the timestamp of the next buffer in
174 // sequence after |first_timestamp|, false otherwise.
175 bool AreAdjacentInSequence(
176 base::TimeDelta first_timestamp, base::TimeDelta second_timestamp) const;
178 // Helper method that returns the timestamp for the next buffer that
179 // |selected_range_| will return from GetNextBuffer() call, or kNoTimestamp()
180 // if in between seeking (i.e. |selected_range_| is null).
181 base::TimeDelta GetNextBufferTimestamp();
183 // Returns the timestamp of the last buffer in the |selected_range_| or
184 // kNoTimestamp() if |selected_range_| is null.
185 base::TimeDelta GetEndBufferTimestamp();
187 // Finds the range that should contain a media segment that begins with
188 // |start_timestamp| and returns the iterator pointing to it. Returns
189 // |ranges_.end()| if there's no such existing range.
190 RangeList::iterator FindExistingRangeFor(base::TimeDelta start_timestamp);
192 // Inserts |new_range| into |ranges_| preserving sorted order. Returns an
193 // iterator in |ranges_| that points to |new_range|.
194 RangeList::iterator AddToRanges(SourceBufferRange* new_range);
196 // Returns an iterator that points to the place in |ranges_| where
197 // |selected_range_| lives.
198 RangeList::iterator GetSelectedRangeItr();
200 // Sets the |selected_range_| to |range| and resets the next buffer position
201 // for the previous |selected_range_|.
202 void SetSelectedRange(SourceBufferRange* range);
204 // Seeks |range| to |seek_timestamp| and then calls SetSelectedRange() with
206 void SeekAndSetSelectedRange(SourceBufferRange* range,
207 base::TimeDelta seek_timestamp);
209 // Resets this stream back to an unseeked state.
210 void ResetSeekState();
212 // Returns true if |seek_timestamp| refers to the beginning of the first range
213 // in |ranges_|, false otherwise or if |ranges_| is empty.
214 bool ShouldSeekToStartOfBuffered(base::TimeDelta seek_timestamp) const;
216 // Returns true if the timestamps of |buffers| are monotonically increasing
217 // since the previous append to the media segment, false otherwise.
218 bool IsMonotonicallyIncreasing(const BufferQueue& buffers) const;
220 // Returns true if |next_timestamp| and |next_is_keyframe| are valid for
221 // the first buffer after the previous append.
222 bool IsNextTimestampValid(base::TimeDelta next_timestamp,
223 bool next_is_keyframe) const;
225 // Returns true if |selected_range_| is the only range in |ranges_| that
226 // HasNextBufferPosition().
227 bool OnlySelectedRangeIsSeeked() const;
229 // Measures the distances between buffer timestamps and tracks the max.
230 void UpdateMaxInterbufferDistance(const BufferQueue& buffers);
232 // Sets the config ID for each buffer to |append_config_index_|.
233 void SetConfigIds(const BufferQueue& buffers);
235 // Called to complete a config change. Updates |current_config_index_| to
236 // match the index of the next buffer. Calling this method causes
237 // GetNextBuffer() to stop returning kConfigChange and start returning
239 void CompleteConfigChange();
241 // Sets |selected_range_| and seeks to the nearest keyframe after
242 // |timestamp| if necessary and possible. This method only attempts to
243 // set |selected_range_| if |seleted_range_| is null and |track_buffer_|
245 void SetSelectedRangeIfNeeded(const base::TimeDelta timestamp);
247 // Find a keyframe timestamp that is >= |start_timestamp| and can be used to
248 // find a new selected range.
249 // Returns kNoTimestamp() if an appropriate keyframe timestamp could not be
251 base::TimeDelta FindNewSelectedRangeSeekTimestamp(
252 const base::TimeDelta start_timestamp);
254 // Searches |ranges_| for the first keyframe timestamp that is >= |timestamp|.
255 // If |ranges_| doesn't contain a GOP that covers |timestamp| or doesn't
256 // have a keyframe after |timestamp| then kNoTimestamp() is returned.
257 base::TimeDelta FindKeyframeAfterTimestamp(const base::TimeDelta timestamp);
259 // Returns "VIDEO" for a video SourceBufferStream and "AUDIO" for an audio
261 std::string GetStreamTypeName() const;
263 // Returns true if we don't have any ranges or the last range is selected
264 // or there is a pending seek beyond any existing ranges.
265 bool IsEndSelected() const;
267 // Deletes the range pointed to by |*itr| and removes it from |ranges_|.
268 // If |*itr| points to |selected_range_|, then |selected_range_| is set to
269 // NULL. After the range is removed, |*itr| is to the range after the one that
270 // was removed or to |ranges_.end()| if the last range was removed.
271 void DeleteAndRemoveRange(RangeList::iterator* itr);
273 // Helper function used by Remove() and PrepareRangesForNextAppend() to
274 // remove buffers and ranges between |start| and |end|.
275 // |is_exclusive| - If set to true, buffers with timestamps that
276 // match |start| are not removed. If set to false, buffers with
277 // timestamps that match |start| will be removed.
278 // |*deleted_buffers| - Filled with buffers for the current playback position
279 // if the removal range included the current playback position. These buffers
280 // can be used as candidates for placing in the |track_buffer_|.
282 base::TimeDelta start, base::TimeDelta end, bool is_exclusive,
283 BufferQueue* deleted_buffers);
285 bool is_video() const { return video_configs_.size() > 0; }
287 // Callback used to report error strings that can help the web developer
288 // figure out what is wrong with the content.
291 // List of disjoint buffered ranges, ordered by start time.
294 // Indicates which decoder config is being used by the decoder.
295 // GetNextBuffer() is only allows to return buffers that have a
296 // config ID that matches this index. If there is a mismatch then
297 // it must signal that a config change is needed.
298 int current_config_index_;
300 // Indicates which decoder config to associate with new buffers
301 // being appended. Each new buffer appended has its config ID set
302 // to the value of this field.
303 int append_config_index_;
305 // Holds the audio/video configs for this stream. |current_config_index_|
306 // and |append_config_index_| represent indexes into one of these vectors.
307 std::vector<AudioDecoderConfig> audio_configs_;
308 std::vector<VideoDecoderConfig> video_configs_;
310 // True if more data needs to be appended before the Seek() can complete,
311 // false if no Seek() has been requested or the Seek() is completed.
314 // True if the end of the stream has been signalled.
317 // Timestamp of the last request to Seek().
318 base::TimeDelta seek_buffer_timestamp_;
320 // Pointer to the seeked-to Range. This is the range from which
321 // GetNextBuffer() calls are fulfilled after the |track_buffer_| has been
323 SourceBufferRange* selected_range_;
325 // Queue of the next buffers to be returned from calls to GetNextBuffer(). If
326 // |track_buffer_| is empty, return buffers from |selected_range_|.
327 BufferQueue track_buffer_;
329 // The start time of the current media segment being appended.
330 base::TimeDelta media_segment_start_time_;
332 // Points to the range containing the current media segment being appended.
333 RangeList::iterator range_for_next_append_;
335 // True when the next call to Append() begins a new media segment.
336 bool new_media_segment_;
338 // The timestamp of the last buffer appended to the media segment, set to
339 // kNoTimestamp() if the beginning of the segment.
340 base::TimeDelta last_appended_buffer_timestamp_;
341 bool last_appended_buffer_is_keyframe_;
343 // The decode timestamp on the last buffer returned by the most recent
344 // GetNextBuffer() call. Set to kNoTimestamp() if GetNextBuffer() hasn't been
345 // called yet or a seek has happened since the last GetNextBuffer() call.
346 base::TimeDelta last_output_buffer_timestamp_;
348 // Stores the largest distance between two adjacent buffers in this stream.
349 base::TimeDelta max_interbuffer_distance_;
351 // The maximum amount of data in bytes the stream will keep in memory.
354 // Indicates that a kConfigChanged status has been reported by GetNextBuffer()
355 // and GetCurrentXXXDecoderConfig() must be called to update the current
356 // config. GetNextBuffer() must not be called again until
357 // GetCurrentXXXDecoderConfig() has been called.
358 bool config_change_pending_;
360 DISALLOW_COPY_AND_ASSIGN(SourceBufferStream);
365 #endif // MEDIA_FILTERS_SOURCE_BUFFER_STREAM_H_