Add docs for live streaming events.

Issue #21.

Change-Id: Id45875f7b2630320c2bbeba98a97ff5e8ecfb3dd

lib/player/dash_video_source.js

@@ -36,6 +36,7 @@ goog.require('shaka.util.TypedBind');
  * @property {boolean} bubbles true
  * @property {number} start The earliest time that can be seeked to, in seconds.
  * @property {number} end The latest time that can be seeked to, in seconds.
+ * @export
  */
 
 

tutorials/live.html

@@ -0,0 +1,83 @@
+<!--
+ Copyright 2015 Google Inc.
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+-->
+
+<h3 class="tutorial-heading">
+Live Streaming Issues
+</h3>
+
+<p>
+Shaka Player supports live streaming since v1.3.0.  Live streams are handled by
+{@link shaka.player.DashVideoSource}, and there is no difference in the API for
+live vs static content.
+</p>
+
+<p>
+Live content can, however, contain large timestamps. This can make the built-in
+controls on the video tag (or any other naive UI) confusing. The currentTime on
+the video may report as something like 397002:54:56. This is not a very helpful
+or meaningful number to the user. Plus, if the video "started" over 300k+ hours
+ago, seeking to 0 is not realistic.  The server is surely not keeping that much
+content sitting around.
+</p>
+
+<p>
+In reality, live content limits the range in which the user may seek.  One live
+stream may allow the user to seek backward 5 minutes, while another may allow 4
+hours. If a user tries to seek to a point outside of this range, the player can
+clamp this value to one within the seek range. Better still is to show the user
+a meaningful range of content in the seek UI.
+</p>
+
+
+<h3 class="tutorial-heading">
+Seek Range Events
+</h3>
+
+<p>
+{@link shaka.player.DashVideoSource.event:SeekRangeChanged} events give the app
+the information it needs to present a better live stream UI.  An app which does
+not support live streams may safely ignore them.  An app which does not support
+seeking in a live stream may also ignore them.
+</p>
+
+<p>
+A SeekRangeChanged event contains "start" and "end" timestamps which define the
+range of time which is currently seekable.  Over time, this window of available
+content will move to the right in the video timeline.
+</p>
+
+<p>
+The "end" time corresponds to the most recent available live content. Therefore
+to jump forward to the "live edge", the application would set video.currentTime
+to the range's "end" time.
+</p>
+
+<p>
+Rather than display actual timestamps from the video stream, which may be quite
+large, we recommend displaying an offset from the live edge.  For example, when
+the user is watching content 1 minute and 30 seconds behind the live edge, show
+"-1:30".
+</p>
+
+<p>
+During live playback, the user's offset from the live edge is roughly constant,
+so any time code displayed would only be changed by buffering or seeking.
+</p>
+
+<p>
+For an example of a UI which uses the SeekRangeChanged event, see controls.js.
+</p>
+

tutorials/live.json

@@ -0,0 +1,3 @@
+{
+  "title": "Live Streaming"
+}