Render inband text tracks in the media pipeline

media/base/text_renderer.h

+// Copyright (c) 2013 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+#ifndef MEDIA_BASE_TEXT_RENDERER_H_
+#define MEDIA_BASE_TEXT_RENDERER_H_
+
+#include <map>
+
+#include "base/callback.h"
+#include "base/memory/scoped_ptr.h"
+#include "base/memory/weak_ptr.h"
+#include "media/base/demuxer_stream.h"
+#include "media/base/media_export.h"
+#include "media/base/pipeline_status.h"
+#include "media/base/text_track.h"
+
+namespace base {
+class MessageLoopProxy;
+}
+
+namespace media {
+
+class TextCue;
+
+// Receives decoder buffers from the upstream demuxer, decodes them to text
+// cues, and then passes them onto the TextTrack object associated with each
+// demuxer text stream.
+class MEDIA_EXPORT TextRenderer {
+ public:
+  // |message_loop| is the thread on which TextRenderer will execute.
+  //
+  // |add_text_track_cb] is called when the demuxer requests (via its host)
+  // that a new text track be created.
+  TextRenderer(const scoped_refptr<base::MessageLoopProxy>& message_loop,
+               const AddTextTrackCB& add_text_track_cb);
+  ~TextRenderer();
+
+  // Establish representation invariants for the TextRenderer.

[acolwell GONE FROM CHROMIUM, 2013/10/21 20:10:40]

nit: Remove this comment since it seems unnecessarily cryptic.

[Matthew Heaney (Chromium), 2013/10/23 05:09:01]

Done.

+  // |ended_cb| is executed when all of the text tracks have reached
+  // end of stream, following a play request.
+  void Initialize(const base::Closure& ended_cb);
+
+  // Start text track cue decoding and rendering, executing |callback| when
+  // playback is underway.
+  void Play(const base::Closure& callback);
+
+  // Temporarily suspend decoding and rendering, executing |callback| when
+  // playback has been suspended.
+  void Pause(const base::Closure& callback);
+
+  // Discard any text data, executing |callback| when completed.
+  void Flush(const base::Closure& callback);
+
+  // Stop all operations in preparation for being deleted, executing |callback|
+  // when complete.
+  void Stop(const base::Closure& callback);
+
+  // Add new |text_stream|, having the indicated |kind|, |label|, and
+  // |language|, to the text stream collection managed by this text renderer.
+  void AddTextStream(DemuxerStream* text_stream,
+                     TextKind kind,

[acolwell GONE FROM CHROMIUM, 2013/10/21 20:10:40]

nit: Use const TextTrackConfig& here.

[Matthew Heaney (Chromium), 2013/10/23 05:09:01]

Done.

+                     const std::string& label,
+                     const std::string& language);
+
+  // Remove |text_stream| from the text stream collection.
+  void RemoveTextStream(DemuxerStream* text_stream);
+
+  // Returns true if there are extant text tracks.
+  bool HasTracks() const;
+
+ private:
+  // Callback delivered by the demuxer |text_stream| when
+  // a read from the stream completes.
+  void BufferReady(DemuxerStream* text_stream,
+                   DemuxerStream::Status status,
+                   const scoped_refptr<DecoderBuffer>& input);
+
+  // Dispatches the decoded cue delivered on the demuxer's |text_stream|.
+  void CueReady(DemuxerStream* text_stream,
+                const scoped_refptr<TextCue>& text_cue);
+
+  // Dispatched when the AddTextTrackCB completes, after having created
+  // the TextTrack object associated with |text_stream|.
+  void OnAddTextTrackDone(DemuxerStream* text_stream,
+                          scoped_ptr<TextTrack> text_track);
+
+  scoped_refptr<base::MessageLoopProxy> message_loop_;
+  base::WeakPtrFactory<TextRenderer> weak_factory_;
+  base::WeakPtr<TextRenderer> weak_this_;
+  const AddTextTrackCB add_text_track_cb_;
+
+  // Callbacks provided during Initialize().
+  base::Closure ended_cb_;
+
+  // Callback provided to Pause().
+  base::Closure pause_cb_;
+
+  // Callback provided to Stop().
+  base::Closure stop_cb_;
+
+  // Simple state tracking variable.
+  enum State {
+    kUninitialized,
+    kPausePending,
+    kPaused,
+    kPlaying,
+    kEnded,
+    kStopPending,
+    kStopped
+  };
+  State state_;
+
+  // To determine read progress.
+  enum ReadState {
+    kReadIdle,
+    kReadPending
+  };
+  typedef std::map<DemuxerStream*, ReadState> ReadStateMap;
+  ReadStateMap read_state_;
+
+  typedef std::map<media::DemuxerStream*, media::TextTrack*> TextTrackMap;
+  TextTrackMap text_track_map_;

[acolwell GONE FROM CHROMIUM, 2013/10/21 20:10:40]

nit: Create a TextTrackState object that holds the ReadState & TextTrack so you
only have to maintain 1 map.

[Matthew Heaney (Chromium), 2013/10/23 05:09:01]

Done.

+
+  // Indicates how many read requests are in flight.
+  int pending_read_count_;
+
+  // Indicates how many text streams have not delivered end-of-stream yet.
+  int pending_eos_count_;
+
+   DISALLOW_IMPLICIT_CONSTRUCTORS(TextRenderer);
+};
+
+}  // namespace media
+
+#endif  // MEDIA_BASE_TEXT_RENDERER_H_