From 0b003d38194bc26dd5f4ceacdf0f660754900dfe Mon Sep 17 00:00:00 2001
From: Joey Parrish <joeyparrish@google.com>
Date: Mon, 27 Apr 2015 11:05:03 -0700
Subject: [PATCH] Document clock sync and CORS issues.

Closes #53.

Change-Id: I5c28336e839d109ca09013011ec4a31823257027
---
 tutorials/live.html | 56 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)

diff --git a/tutorials/live.html b/tutorials/live.html
index 3c481d3772..58f716b550 100644
--- a/tutorials/live.html
+++ b/tutorials/live.html
@@ -81,3 +81,59 @@ <h3 class="tutorial-heading">
 For an example of a UI which uses the SeekRangeChanged event, see controls.js.
 </p>
 
+
+<h3 class="tutorial-heading">
+Clock Synchronization
+</h3>
+
+<p>
+Segment availability for live streams is based on the current time.  You cannot
+access segments from the future, but the manifest may give you enough detail to
+know their locations in advance. Therefore, if the client's clock is not synced
+with the server's clock, the client might request unavailable segments.
+</p>
+
+<p>
+Clock synchronization between client and server is important. In the DASH spec,
+it states (under heading A.3.1) that "clients are expected to synchronize their
+clocks to a globally accurate time standard."  It does not specify how, though.
+</p>
+
+<p>
+Shaka Player uses a very simple mechanism for clock sync. When the library asks
+the server for a manifest, the HTTP Date response header is used to synchronize
+the client's {@link shaka.util.Clock virtual clock} with the server. All timing
+for the live stream is based on this virtual clock, rather than the system time
+of the client.  This has a few advantages.
+</p>
+
+<p>
+Rather than requiring synchronization to a globally accurate time standard, our
+mechanism requires only that the server time is consistent between the manifest
+and the web server.  This self-consistency is a lighter-weight requirement than
+the one in the DASH specification, and one which we think is easier to satisfy.
+</p>
+
+<p>
+The HTTP specification requires the Date header for all responses, so it should
+always be present.  By using the Date header, we avoid the need for out-of-band
+clock synchronization mechanisms.
+</p>
+
+
+<h3 class="tutorial-heading">
+Clock Synchronization vs CORS
+</h3>
+
+<p>
+If your application operates <a href="http://goo.gl/meEW9Q">same-origin</a>, no
+special configuration is required for clock synchronization.  If manifests come
+from another origin, your server must allow Cross-Origin Resource Sharing, also
+known as <a href="http://goo.gl/vqldIX">CORS</a>. The response for the manifest
+must include the "Access-Control-Expose-Headers" header with "Date" in the list
+of values. If this is not given, the browser will not permit the application to
+read the Date header. Chrome will log an error message to the JS console saying
+"Refused to get unsafe header".  (Note that this is coming directly from Chrome
+and cannot be silenced by the library.)
+</p>
+