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. 4 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. 9 10 #ifndef MEDIA_FILTERS_SOURCE_BUFFER_STREAM_H_ 11 #define MEDIA_FILTERS_SOURCE_BUFFER_STREAM_H_ 12 13 #include <deque> 14 #include <list> 15 #include <string> 16 #include <utility> 17 #include <vector> 18 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/text_track_config.h" 26 #include "media/base/video_decoder_config.h" 27 28 namespace media { 29 30 class SourceBufferRange; 31 32 // See file-level comment for complete description. 33 class MEDIA_EXPORT SourceBufferStream { 34 public: 35 typedef StreamParser::BufferQueue BufferQueue; 36 37 // Status returned by GetNextBuffer(). 38 // kSuccess: Indicates that the next buffer was returned. 39 // kNeedBuffer: Indicates that we need more data before a buffer can be 40 // returned. 41 // kConfigChange: Indicates that the next buffer requires a config change. 42 enum Status { 43 kSuccess, 44 kNeedBuffer, 45 kConfigChange, 46 kEndOfStream 47 }; 48 49 enum Type { 50 kAudio, 51 kVideo, 52 kText 53 }; 54 55 SourceBufferStream(const AudioDecoderConfig& audio_config, 56 const LogCB& log_cb, 57 bool splice_frames_enabled); 58 SourceBufferStream(const VideoDecoderConfig& video_config, 59 const LogCB& log_cb, 60 bool splice_frames_enabled); 61 SourceBufferStream(const TextTrackConfig& text_config, 62 const LogCB& log_cb, 63 bool splice_frames_enabled); 64 65 ~SourceBufferStream(); 66 67 // Signals that the next buffers appended are part of a new media segment 68 // starting at |media_segment_start_time|. 69 void OnNewMediaSegment(base::TimeDelta media_segment_start_time); 70 71 // Add the |buffers| to the SourceBufferStream. Buffers within the queue are 72 // expected to be in order, but multiple calls to Append() may add buffers out 73 // of order or overlapping. Assumes all buffers within |buffers| are in 74 // presentation order and are non-overlapping. 75 // Returns true if Append() was successful, false if |buffers| are not added. 76 // TODO(vrk): Implement garbage collection. (crbug.com/125070) 77 bool Append(const BufferQueue& buffers); 78 79 // Removes buffers between |start| and |end| according to the steps 80 // in the "Coded Frame Removal Algorithm" in the Media Source 81 // Extensions Spec. 82 // https://dvcs.w3.org/hg/html-media/raw-file/default/media-source/media-source.html#sourcebuffer-coded-frame-removal 83 // 84 // |duration| is the current duration of the presentation. It is 85 // required by the computation outlined in the spec. 86 void Remove(base::TimeDelta start, base::TimeDelta end, 87 base::TimeDelta duration); 88 89 // Changes the SourceBufferStream's state so that it will start returning 90 // buffers starting from the closest keyframe before |timestamp|. 91 void Seek(base::TimeDelta timestamp); 92 93 // Returns true if the SourceBufferStream has seeked to a time without 94 // buffered data and is waiting for more data to be appended. 95 bool IsSeekPending() const; 96 97 // Notifies the SourceBufferStream that the media duration has been changed to 98 // |duration| so it should drop any data past that point. 99 void OnSetDuration(base::TimeDelta duration); 100 101 // Fills |out_buffer| with a new buffer. Buffers are presented in order from 102 // the last call to Seek(), or starting with the first buffer appended if 103 // Seek() has not been called yet. 104 // |out_buffer|'s timestamp may be earlier than the |timestamp| passed to 105 // the last Seek() call. 106 // Returns kSuccess if |out_buffer| is filled with a valid buffer, kNeedBuffer 107 // if there is not enough data buffered to fulfill the request, and 108 // kConfigChange if the next buffer requires a config change. 109 Status GetNextBuffer(scoped_refptr<StreamParserBuffer>* out_buffer); 110 111 // Returns a list of the buffered time ranges. 112 Ranges<base::TimeDelta> GetBufferedTime() const; 113 114 // Returns the duration of the buffered ranges, which is equivalent 115 // to the end timestamp of the last buffered range. If no data is buffered 116 // then base::TimeDelta() is returned. 117 base::TimeDelta GetBufferedDuration() const; 118 119 // Notifies this object that end of stream has been signalled. 120 void MarkEndOfStream(); 121 122 // Clear the end of stream state set by MarkEndOfStream(). 123 void UnmarkEndOfStream(); 124 125 const AudioDecoderConfig& GetCurrentAudioDecoderConfig(); 126 const VideoDecoderConfig& GetCurrentVideoDecoderConfig(); 127 const TextTrackConfig& GetCurrentTextTrackConfig(); 128 129 // Notifies this object that the audio config has changed and buffers in 130 // future Append() calls should be associated with this new config. 131 bool UpdateAudioConfig(const AudioDecoderConfig& config); 132 133 // Notifies this object that the video config has changed and buffers in 134 // future Append() calls should be associated with this new config. 135 bool UpdateVideoConfig(const VideoDecoderConfig& config); 136 137 // Returns the largest distance between two adjacent buffers in this stream, 138 // or an estimate if no two adjacent buffers have been appended to the stream 139 // yet. 140 base::TimeDelta GetMaxInterbufferDistance() const; 141 142 void set_memory_limit_for_testing(int memory_limit) { 143 memory_limit_ = memory_limit; 144 } 145 146 private: 147 friend class SourceBufferStreamTest; 148 149 typedef std::list<SourceBufferRange*> RangeList; 150 151 // Frees up space if the SourceBufferStream is taking up too much memory. 152 void GarbageCollectIfNeeded(); 153 154 // Attempts to delete approximately |total_bytes_to_free| amount of data 155 // |ranges_|, starting at the front of |ranges_| and moving linearly forward 156 // through the buffers. Deletes starting from the back if |reverse_direction| 157 // is true. Returns the number of bytes freed. 158 int FreeBuffers(int total_bytes_to_free, bool reverse_direction); 159 160 // Attempts to delete approximately |total_bytes_to_free| amount of data from 161 // |ranges_|, starting after the last appended buffer before the current 162 // playback position. 163 int FreeBuffersAfterLastAppended(int total_bytes_to_free); 164 165 // Gets the removal range to secure |byte_to_free| from 166 // [|start_timestamp|, |end_timestamp|). 167 // Returns the size of buffers to secure if future 168 // Remove(|start_timestamp|, |removal_end_timestamp|, duration) is called. 169 // Will not update |removal_end_timestamp| if the returned size is 0. 170 int GetRemovalRange(base::TimeDelta start_timestamp, 171 base::TimeDelta end_timestamp, int byte_to_free, 172 base::TimeDelta* removal_end_timestamp); 173 174 // Prepares |range_for_next_append_| so |new_buffers| can be appended. 175 // This involves removing buffers between the end of the previous append 176 // and any buffers covered by the time range in |new_buffers|. 177 // |deleted_buffers| is an output parameter containing candidates for 178 // |track_buffer_| if this method ends up removing the current playback 179 // position from the range. 180 void PrepareRangesForNextAppend(const BufferQueue& new_buffers, 181 BufferQueue* deleted_buffers); 182 183 // Removes buffers, from the |track_buffer_|, that come after |timestamp|. 184 void PruneTrackBuffer(const base::TimeDelta timestamp); 185 186 // Checks to see if |range_with_new_buffers_itr| can be merged with the range 187 // next to it, and merges them if so. 188 void MergeWithAdjacentRangeIfNecessary( 189 const RangeList::iterator& range_with_new_buffers_itr); 190 191 // Returns true if |second_timestamp| is the timestamp of the next buffer in 192 // sequence after |first_timestamp|, false otherwise. 193 bool AreAdjacentInSequence( 194 base::TimeDelta first_timestamp, base::TimeDelta second_timestamp) const; 195 196 // Helper method that returns the timestamp for the next buffer that 197 // |selected_range_| will return from GetNextBuffer() call, or kNoTimestamp() 198 // if in between seeking (i.e. |selected_range_| is null). 199 base::TimeDelta GetNextBufferTimestamp(); 200 201 // Returns the timestamp of the last buffer in the |selected_range_| or 202 // kNoTimestamp() if |selected_range_| is null. 203 base::TimeDelta GetEndBufferTimestamp(); 204 205 // Finds the range that should contain a media segment that begins with 206 // |start_timestamp| and returns the iterator pointing to it. Returns 207 // |ranges_.end()| if there's no such existing range. 208 RangeList::iterator FindExistingRangeFor(base::TimeDelta start_timestamp); 209 210 // Inserts |new_range| into |ranges_| preserving sorted order. Returns an 211 // iterator in |ranges_| that points to |new_range|. 212 RangeList::iterator AddToRanges(SourceBufferRange* new_range); 213 214 // Returns an iterator that points to the place in |ranges_| where 215 // |selected_range_| lives. 216 RangeList::iterator GetSelectedRangeItr(); 217 218 // Sets the |selected_range_| to |range| and resets the next buffer position 219 // for the previous |selected_range_|. 220 void SetSelectedRange(SourceBufferRange* range); 221 222 // Seeks |range| to |seek_timestamp| and then calls SetSelectedRange() with 223 // |range|. 224 void SeekAndSetSelectedRange(SourceBufferRange* range, 225 base::TimeDelta seek_timestamp); 226 227 // Resets this stream back to an unseeked state. 228 void ResetSeekState(); 229 230 // Returns true if |seek_timestamp| refers to the beginning of the first range 231 // in |ranges_|, false otherwise or if |ranges_| is empty. 232 bool ShouldSeekToStartOfBuffered(base::TimeDelta seek_timestamp) const; 233 234 // Returns true if the timestamps of |buffers| are monotonically increasing 235 // since the previous append to the media segment, false otherwise. 236 bool IsMonotonicallyIncreasing(const BufferQueue& buffers) const; 237 238 // Returns true if |next_timestamp| and |next_is_keyframe| are valid for 239 // the first buffer after the previous append. 240 bool IsNextTimestampValid(base::TimeDelta next_timestamp, 241 bool next_is_keyframe) const; 242 243 // Returns true if |selected_range_| is the only range in |ranges_| that 244 // HasNextBufferPosition(). 245 bool OnlySelectedRangeIsSeeked() const; 246 247 // Measures the distances between buffer timestamps and tracks the max. 248 void UpdateMaxInterbufferDistance(const BufferQueue& buffers); 249 250 // Sets the config ID for each buffer to |append_config_index_|. 251 void SetConfigIds(const BufferQueue& buffers); 252 253 // Called to complete a config change. Updates |current_config_index_| to 254 // match the index of the next buffer. Calling this method causes 255 // GetNextBuffer() to stop returning kConfigChange and start returning 256 // kSuccess. 257 void CompleteConfigChange(); 258 259 // Sets |selected_range_| and seeks to the nearest keyframe after 260 // |timestamp| if necessary and possible. This method only attempts to 261 // set |selected_range_| if |seleted_range_| is null and |track_buffer_| 262 // is empty. 263 void SetSelectedRangeIfNeeded(const base::TimeDelta timestamp); 264 265 // Find a keyframe timestamp that is >= |start_timestamp| and can be used to 266 // find a new selected range. 267 // Returns kNoTimestamp() if an appropriate keyframe timestamp could not be 268 // found. 269 base::TimeDelta FindNewSelectedRangeSeekTimestamp( 270 const base::TimeDelta start_timestamp); 271 272 // Searches |ranges_| for the first keyframe timestamp that is >= |timestamp|. 273 // If |ranges_| doesn't contain a GOP that covers |timestamp| or doesn't 274 // have a keyframe after |timestamp| then kNoTimestamp() is returned. 275 base::TimeDelta FindKeyframeAfterTimestamp(const base::TimeDelta timestamp); 276 277 // Returns "VIDEO" for a video SourceBufferStream, "AUDIO" for an audio 278 // stream, and "TEXT" for a text stream. 279 std::string GetStreamTypeName() const; 280 281 // Returns true if we don't have any ranges or the last range is selected 282 // or there is a pending seek beyond any existing ranges. 283 bool IsEndSelected() const; 284 285 // Deletes the range pointed to by |*itr| and removes it from |ranges_|. 286 // If |*itr| points to |selected_range_|, then |selected_range_| is set to 287 // NULL. After the range is removed, |*itr| is to the range after the one that 288 // was removed or to |ranges_.end()| if the last range was removed. 289 void DeleteAndRemoveRange(RangeList::iterator* itr); 290 291 // Helper function used by Remove() and PrepareRangesForNextAppend() to 292 // remove buffers and ranges between |start| and |end|. 293 // |is_exclusive| - If set to true, buffers with timestamps that 294 // match |start| are not removed. If set to false, buffers with 295 // timestamps that match |start| will be removed. 296 // |*deleted_buffers| - Filled with buffers for the current playback position 297 // if the removal range included the current playback position. These buffers 298 // can be used as candidates for placing in the |track_buffer_|. 299 void RemoveInternal( 300 base::TimeDelta start, base::TimeDelta end, bool is_exclusive, 301 BufferQueue* deleted_buffers); 302 303 Type GetType() const; 304 305 // See GetNextBuffer() for additional details. This method handles splice 306 // frame processing. 307 Status HandleNextBufferWithSplice( 308 scoped_refptr<StreamParserBuffer>* out_buffer); 309 310 // See GetNextBuffer() for additional details. This method handles preroll 311 // frame processing. 312 Status HandleNextBufferWithPreroll( 313 scoped_refptr<StreamParserBuffer>* out_buffer); 314 315 // See GetNextBuffer() for additional details. The internal method hands out 316 // single buffers from the |track_buffer_| and |selected_range_| without 317 // additional processing for splice frame or preroll buffers. 318 Status GetNextBufferInternal(scoped_refptr<StreamParserBuffer>* out_buffer); 319 320 // Called by PrepareRangesForNextAppend() before pruning overlapped buffers to 321 // generate a splice frame with a small portion of the overlapped buffers. If 322 // a splice frame is generated, the first buffer in |new_buffers| will have 323 // its timestamps, duration, and fade out preroll updated. 324 void GenerateSpliceFrame(const BufferQueue& new_buffers); 325 326 // If |out_buffer| has splice buffers or preroll, sets |pending_buffer_| 327 // appropriately and returns true. Otherwise returns false. 328 bool SetPendingBuffer(scoped_refptr<StreamParserBuffer>* out_buffer); 329 330 // Callback used to report error strings that can help the web developer 331 // figure out what is wrong with the content. 332 LogCB log_cb_; 333 334 // List of disjoint buffered ranges, ordered by start time. 335 RangeList ranges_; 336 337 // Indicates which decoder config is being used by the decoder. 338 // GetNextBuffer() is only allows to return buffers that have a 339 // config ID that matches this index. If there is a mismatch then 340 // it must signal that a config change is needed. 341 int current_config_index_; 342 343 // Indicates which decoder config to associate with new buffers 344 // being appended. Each new buffer appended has its config ID set 345 // to the value of this field. 346 int append_config_index_; 347 348 // Holds the audio/video configs for this stream. |current_config_index_| 349 // and |append_config_index_| represent indexes into one of these vectors. 350 std::vector<AudioDecoderConfig> audio_configs_; 351 std::vector<VideoDecoderConfig> video_configs_; 352 353 // Holds the text config for this stream. 354 TextTrackConfig text_track_config_; 355 356 // True if more data needs to be appended before the Seek() can complete, 357 // false if no Seek() has been requested or the Seek() is completed. 358 bool seek_pending_; 359 360 // True if the end of the stream has been signalled. 361 bool end_of_stream_; 362 363 // Timestamp of the last request to Seek(). 364 base::TimeDelta seek_buffer_timestamp_; 365 366 // Pointer to the seeked-to Range. This is the range from which 367 // GetNextBuffer() calls are fulfilled after the |track_buffer_| has been 368 // emptied. 369 SourceBufferRange* selected_range_; 370 371 // Queue of the next buffers to be returned from calls to GetNextBuffer(). If 372 // |track_buffer_| is empty, return buffers from |selected_range_|. 373 BufferQueue track_buffer_; 374 375 // The start time of the current media segment being appended. 376 base::TimeDelta media_segment_start_time_; 377 378 // Points to the range containing the current media segment being appended. 379 RangeList::iterator range_for_next_append_; 380 381 // True when the next call to Append() begins a new media segment. 382 bool new_media_segment_; 383 384 // The timestamp of the last buffer appended to the media segment, set to 385 // kNoTimestamp() if the beginning of the segment. 386 base::TimeDelta last_appended_buffer_timestamp_; 387 bool last_appended_buffer_is_keyframe_; 388 389 // The decode timestamp on the last buffer returned by the most recent 390 // GetNextBuffer() call. Set to kNoTimestamp() if GetNextBuffer() hasn't been 391 // called yet or a seek has happened since the last GetNextBuffer() call. 392 base::TimeDelta last_output_buffer_timestamp_; 393 394 // Stores the largest distance between two adjacent buffers in this stream. 395 base::TimeDelta max_interbuffer_distance_; 396 397 // The maximum amount of data in bytes the stream will keep in memory. 398 int memory_limit_; 399 400 // Indicates that a kConfigChanged status has been reported by GetNextBuffer() 401 // and GetCurrentXXXDecoderConfig() must be called to update the current 402 // config. GetNextBuffer() must not be called again until 403 // GetCurrentXXXDecoderConfig() has been called. 404 bool config_change_pending_; 405 406 // Used by HandleNextBufferWithSplice() or HandleNextBufferWithPreroll() when 407 // a splice frame buffer or buffer with preroll is returned from 408 // GetNextBufferInternal(). 409 scoped_refptr<StreamParserBuffer> pending_buffer_; 410 411 // Indicates which of the splice buffers in |splice_buffer_| should be 412 // handled out next. 413 size_t splice_buffers_index_; 414 415 // Indicates that all buffers before |pending_buffer_| have been handed out. 416 bool pending_buffers_complete_; 417 418 // Indicates that splice frame generation is enabled. 419 const bool splice_frames_enabled_; 420 421 DISALLOW_COPY_AND_ASSIGN(SourceBufferStream); 422 }; 423 424 } // namespace media 425 426 #endif // MEDIA_FILTERS_SOURCE_BUFFER_STREAM_H_ 427