media/base/stream_parser.h

   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 #ifndef MEDIA_BASE_STREAM_PARSER_H_
   6 #define MEDIA_BASE_STREAM_PARSER_H_
   7
   8 #include <deque>
   9 #include <map>
  10 #include <string>
  11 #include <vector>
  12
  13 #include "base/callback_forward.h"
  14 #include "base/memory/ref_counted.h"
  15 #include "base/memory/scoped_ptr.h"
  16 #include "base/time/time.h"
  17 #include "media/base/demuxer_stream.h"
  18 #include "media/base/media_export.h"
  19 #include "media/base/media_log.h"
  20
  21 namespace media {
  22
  23 class AudioDecoderConfig;
  24 class StreamParserBuffer;
  25 class TextTrackConfig;
  26 class VideoDecoderConfig;
  27
  28 // Abstract interface for parsing media byte streams.
  29 class MEDIA_EXPORT StreamParser {
  30  public:
  31   typedef std::deque<scoped_refptr<StreamParserBuffer> > BufferQueue;
  32
  33   // Range of |TrackId| is dependent upon stream parsers. It is currently
  34   // the key for the buffer's text track config in the applicable
  35   // TextTrackConfigMap (which is passed in StreamParser::NewConfigCB), or
  36   // 0 for other media types that currently allow at most one track.
  37   // WebMTracksParser uses -1 as an invalid text track number.
  38   // TODO(wolenetz/acolwell): Change to size_type while fixing stream parsers to
  39   // emit validated track configuration and buffer vectors rather than max 1
  40   // audio, max 1 video, and N text tracks in a map keyed by
  41   // bytestream-specific-ranged track numbers. See http://crbug.com/341581.
  42   typedef int TrackId;
  43
  44   // Map of text track ID to the track configuration.
  45   typedef std::map<TrackId, TextTrackConfig> TextTrackConfigMap;
  46
  47   // Map of text track ID to decode-timestamp-ordered buffers for the track.
  48   typedef std::map<TrackId, const BufferQueue> TextBufferQueueMap;
  49
  50   // Stream parameters passed in InitCB.
  51   struct InitParameters {
  52     InitParameters(base::TimeDelta duration);
  53
  54     // Stream duration.
  55     base::TimeDelta duration;
  56
  57     // Indicates the source time associated with presentation timestamp 0. A
  58     // null Time is returned if no mapping to Time exists.
  59     base::Time timeline_offset;
  60
  61     // Indicates that timestampOffset should be updated based on the earliest
  62     // end timestamp (audio or video) provided during each NewBuffersCB.
  63     bool auto_update_timestamp_offset;
  64
  65     // Indicates live stream.
  66     DemuxerStream::Liveness liveness;
  67   };
  68
  69   // Indicates completion of parser initialization.
  70   //   success - True if initialization was successful.
  71   //   params - Stream parameters, in case of successful initialization.
  72   typedef base::Callback<void(bool success,
  73                               const InitParameters& params)> InitCB;
  74
  75   // Indicates when new stream configurations have been parsed.
  76   // First parameter - The new audio configuration. If the config is not valid
  77   //                   then it means that there isn't an audio stream.
  78   // Second parameter - The new video configuration. If the config is not valid
  79   //                    then it means that there isn't an audio stream.
  80   // Third parameter - The new text tracks configuration.  If the map is empty,
  81   //                   then no text tracks were parsed from the stream.
  82   // Return value - True if the new configurations are accepted.
  83   //                False if the new configurations are not supported
  84   //                and indicates that a parsing error should be signalled.
  85   typedef base::Callback<bool(const AudioDecoderConfig&,
  86                               const VideoDecoderConfig&,
  87                               const TextTrackConfigMap&)> NewConfigCB;
  88
  89   // New stream buffers have been parsed.
  90   // First parameter - A queue of newly parsed audio buffers.
  91   // Second parameter - A queue of newly parsed video buffers.
  92   // Third parameter - A map of text track ids to queues of newly parsed inband
  93   //                   text buffers. If the map is not empty, it must contain
  94   //                   at least one track with a non-empty queue of text
  95   //                   buffers.
  96   // Return value - True indicates that the buffers are accepted.
  97   //                False if something was wrong with the buffers and a parsing
  98   //                error should be signalled.
  99   typedef base::Callback<bool(const BufferQueue&,
 100                               const BufferQueue&,
 101                               const TextBufferQueueMap&)> NewBuffersCB;
 102
 103   // Signals the beginning of a new media segment.
 104   typedef base::Callback<void()> NewMediaSegmentCB;
 105
 106   // A new potentially encrypted stream has been parsed.
 107   // First parameter - The type of the initialization data associated with the
 108   //                   stream.
 109   // Second parameter - The initialization data associated with the stream.
 110   typedef base::Callback<void(const std::string&, const std::vector<uint8>&)>
 111       EncryptedMediaInitDataCB;
 112
 113   StreamParser();
 114   virtual ~StreamParser();
 115
 116   // Initializes the parser with necessary callbacks. Must be called before any
 117   // data is passed to Parse(). |init_cb| will be called once enough data has
 118   // been parsed to determine the initial stream configurations, presentation
 119   // start time, and duration. If |ignore_text_track| is true, then no text
 120   // buffers should be passed later by the parser to |new_buffers_cb|.
 121   virtual void Init(
 122       const InitCB& init_cb,
 123       const NewConfigCB& config_cb,
 124       const NewBuffersCB& new_buffers_cb,
 125       bool ignore_text_track,
 126       const EncryptedMediaInitDataCB& encrypted_media_init_data_cb,
 127       const NewMediaSegmentCB& new_segment_cb,
 128       const base::Closure& end_of_segment_cb,
 129       const LogCB& log_cb) = 0;
 130
 131   // Called when a seek occurs. This flushes the current parser state
 132   // and puts the parser in a state where it can receive data for the new seek
 133   // point.
 134   virtual void Flush() = 0;
 135
 136   // Called when there is new data to parse.
 137   //
 138   // Returns true if the parse succeeds.
 139   virtual bool Parse(const uint8* buf, int size) = 0;
 140
 141  private:
 142   DISALLOW_COPY_AND_ASSIGN(StreamParser);
 143 };
 144
 145 // Appends to |merged_buffers| the provided buffers in decode-timestamp order.
 146 // Any previous contents of |merged_buffers| is assumed to have lower
 147 // decode timestamps versus the provided buffers. All provided buffer queues
 148 // are assumed to already be in decode-timestamp order.
 149 // Returns false if any of the provided audio/video/text buffers are found
 150 // to not be in decode timestamp order, or have a decode timestamp less than
 151 // the last buffer, if any, in |merged_buffers|. Partial results may exist
 152 // in |merged_buffers| in this case. Returns true on success.
 153 // No validation of media type within the various buffer queues is done here.
 154 // TODO(wolenetz/acolwell): Merge incrementally in parsers to eliminate
 155 // subtle issues with tie-breaking. See http://crbug.com/338484.
 156 MEDIA_EXPORT bool MergeBufferQueues(
 157     const StreamParser::BufferQueue& audio_buffers,
 158     const StreamParser::BufferQueue& video_buffers,
 159     const StreamParser::TextBufferQueueMap& text_buffers,
 160     StreamParser::BufferQueue* merged_buffers);
 161
 162 }  // namespace media
 163
 164 #endif  // MEDIA_BASE_STREAM_PARSER_H_