<?xml version="1.0" encoding="US-ASCII"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml">
<!ENTITY RFC3552 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3552.xml">
<!ENTITY I-D.narten-iana-considerations-rfc2434bis SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.narten-iana-considerations-rfc2434bis.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc strict="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<rfc category="exp" docName="draft-msparks-template-star-00" ipr="trust200902">

  <front>
    <!-- The abbreviated title is used in the page header - it is only necessary if the 
         full title is longer than 39 characters -->

    <title abbrev="STAR: IP &amp; Broadcast Synchronisation">Service synchronisation for Television And Related devices -- STAR</title>

    <!-- add 'role="editor"' below for the editors if appropriate -->

    <!-- Another author who claims to be an editor -->

    <author fullname="Michael Sparks" initials="M." surname="Sparks">
      <organization>BBC Research and Development</organization>

      <address>
        <postal>
          <street>BBC R &amp; D North Lab</street>
          <street>Dock House</street>
          <street>MediaCityUK</street>
          <!-- Reorder these if your country does things differently -->

          <city>Salford</city>

          <region></region>

          <code>M50 2LH</code>

          <country>UK</country>
        </postal>

        <phone>+44 303 040 9510 </phone>

        <email>michael.sparks@bbc.co.uk</email>

        <!-- uri and facsimile elements may also be added -->
      </address>
    </author>

    <date month="June" year="2012" />

    <!-- If the month and year are both specified and are the current ones, xml2rfc will fill 
         in the current day for you. If only the current year is specified, xml2rfc will fill 
	 in the current day and month for you. If the year is not the current one, it is 
	 necessary to specify at least a month (xml2rfc assumes day="1" if not specified for the 
	 purpose of calculating the expiry date).  With drafts it is normally sufficient to 
	 specify just the year. -->

    <!-- Meta-data Declarations -->

    <area>General</area>

    <workgroup>Internet Engineering Task Force</workgroup>

    <!-- WG name at the upperleft corner of the doc,
         IETF is fine for individual submissions.  
	 If this element is not present, the default is "Network Working Group",
         which is used by the RFC Editor as a nod to the history of the IETF. -->

    <keyword>template</keyword>

    <!-- Keywords will be incorporated into HTML output
         files in a meta tag but they have no effect on text or nroff
         output. If you submit your draft to the RFC Editor, the
         keywords will be used for the search engine. -->

    <abstract>
      
      
      <t>Service synchronisation for Television And Related devices (STAR) is
         a suite of application level protocols to enable network connected
         devices to correlate events on a broadcast system with events outside
         that broadcast system. It is a generic suite of protocols, that
         enables playback of content retrieved from over a network such
         that it is synchronised to a broadcast source. It also enables
         correlation of non-broadcast events (such as conversations) to
         broadcast events.</t> 

      <t>Key features of STAR include: 1) The broadcast system does not
         require modification 2) It is designed to work with restricted clients
         limited to stream connections - such as web browsers 3) It is content
         agnostic.</t>

      <t>This specification describes the research implementation as it
         stands today, and is published as a starting point for further
         discussion.</t>

    </abstract>
  </front>

  <middle>
    <section title="Introduction">
      
      <t>The original specification of xml2rfc format is in <xref
  target="RFC2629">RFC&nbsp;2629</xref>.</t>
      <section title="Purpose">
        <t> Broadcast is a well understood single to many push medium,
            with modern television broadcast systems being digital
            broadcast systems. In the USA, the system is ATSC, in
            Europe DVB is common, with DVB-T, DVB-C and DVB-S widely
            deployed.
        </t>
        <t> Whilst such digital systems have variations, they fundamentally
            form a lossy data channel from a broadcaster to an audience
            at a fixed bit rate. This is generally then received by a
            display which is a shared resource, broadly controlled by
            the occupants of a single room. Thus what is displayed or
            played back on the shared display must be of interest to
            all users of that device (or well known arguments ensue).
        </t>
        <t> Digital broadcasts carry a variety of non audio/video data
            including subtitles, audio description (also called narrative
            subtitles for the blind), interactive applications, as well as
            information bundles similar to web pages. Each addition to the
            broadcast uses up the scarce resource. More data can be squeezed
            in at the expense (primarily) of picture quality.  Each change
            presents diminishing returns for the broadcaster, despite
            benefits to the audience, due to the nature of broadcast
            being a single shared push channel. Furthermore, in order
            to "fake" a pull approach for data, information on a data
            channel - such as electronic programme guide (EPG)
            information - is has to be repeatedly pushed in order
            to allow clients timely access to data. This data carousel
            (as it is termed) squeezes the transmission channel even further.
        </t>
        
        <t> 
            Unlike broadcast clients, network clients control their local
            communications channel, leading to clients pulling services
            from servers. Being pull based, they are by their nature
            elective and therefore extremely good for personalised
            experiences. They can tend to suffer efficiency concerns for
            very large concurrent audiences, in particular servicing large
            audiences efficiently without content injection concerns
            is still hard.
        </t>
        
        <t> 
            Work has previously been done have investigating how to marry
            the broadcast and IP world.  However in many cases they have
            sought to change the inherent nature of either broadcast from
            it's shared receiver audio or video nature, or to change
            network delivery to take control away from the receiver.
            That is to try and change the network delivery from a pull
            medium to a push medium.
        </t>
        
        <t> 
            Service Synchronisation for Television and Related Devices
            (STAR) is predicated on the principle of using the broadcast
            data channel for push aspects of a service in a form useful
            for the majority of an audience, and using pull-based network
            delivery for personalisation. 
        </t>
        
        <t> 
            These personalisations need to be synchronised relative to
            the programme being broadcast, and presented to the user at
            appropriate times. To do this we expose key information about
            the broadcast data channel over the network, along with
            defining a means of synchronising with the broadcast data
            channel, and also a standard play out data format which
            can be used by a generic client to play out content
            synchronised to the broadcast.
        </t>
        
        <t> 
            STAR is also assumes that whilst custom clients are possible,
            clients are most likely to be implemented in restriction
            environments such as browsers or virtual machines residing
            in browsers. In practical terms this means that whilst it
            could operate on top of many transports, it is designed to
            primarily operate on top of either TCP or HTTP.
        </t>
        
        <t> 
            Thus STAR comprises a small suite of application level
            protocols that seeks to work with each medium appropriately,
            forming initial research results in this area. This
            specification describes the research implementation as it
            stands today, and is published as a starting point for
            further discussion. 
        </t>
        
        <t> 
            In particular while each protocol could be specified
            separately, but describing them together retains important
            context.
        </t>
        
        
        
      </section>
      <section title="Requirements Language">
        <t>The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
        "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
        document are to be interpreted as described in <xref
        target="RFC2119">RFC 2119</xref>.</t>

        <t>
          An implementation is not compliant if it fails to satisfy
          one or more of the MUST or REQUIRED level requirements for
          the protocols it implements. An implementation that satisfies
          all the MUST or REQUIRED level and all the SHOULD level
          requirements for its protocols is said to be
          "unconditionally compliant"; one that satisfies
          all the MUST level requirements but not all the
          SHOULD level requirements for its protocols is
          said to be "conditionally compliant."
        </t>
      </section>
      
      
      <section title="Terminology">
        <t> 
          This specification uses a number of terms to refer to
          the roles played by participants in, and objects of,
          a STAR system.
        </t>

      <t><list hangIndent="8" style="hanging">
          <t hangText="broadcast">
            <vspace blankLines="0" />
            An audio/visual transmission over radio or similar system
            that also includes a time and data signal - such as digital
            broadcasting or analogue broadcast with a teletext, etc.
            data channel.
          </t>

          <t hangText="digital broadcast">
            <vspace blankLines="0" />
            A broadcast using a digital broadcast standard such as
            Digital Video Broadcasting (DVB), or Advanced Television
            Systems Committee (ATSC). Digital broadcasts typically
            contain audio, video, subtitles, applications, and
            metadata regarding the broadcasts - in terms of content
            and transport.
          </t>

          <t hangText="broadcast receiver">
            <vspace blankLines="0" />
            A standard receiver for a given broadcast system.
          </t>

          <t hangText="broadcast time">
            <vspace blankLines="0" />
            The time specified in a broadcast signal, as recieved
            by a broadcast reciever.
          </t>

          <t hangText="broadcast bridge">
            <vspace blankLines="0" />
            A broadcast receiver that stores metadata from a given
            broadcast service. It acts as a server on the network
            available to be queried by a client. (ie it bridges the
            push of broadcast and the pull from a network client)
          </t>

          <t hangText="play out script">
            <vspace blankLines="0" />
            Data file that is used to schedule playback of events
            relative to given times based on event type
          </t>

          <t hangText="content server">
            <vspace blankLines="0" />
            A server that a client can retrieve play out scripts from
            as well as additional content.
          </t>

          <t hangText="client">
            <vspace blankLines="0" />
            A network connected device capable of playing out 1 or more
            form of synchronised content. Performs synchronisation with
            the broadcast bridge, retrieves content from the content
            server for play out.
          </t>

          <t hangText="client clock">
            <vspace blankLines="0" />
            The actual system clock of the client device. Assumed to be
            poor quality and unchangeable.
          </t>

          <t hangText="application clock">
            <vspace blankLines="0" />
            A corrected software clock based synchronisation with
            the broadcast bridge. Does not have a defined accuracy
            level. 
          </t>

          <t hangText="broadcast time server port">
            <vspace blankLines="0" />
            A TCP socket listening on the broadcast bridge for a client
            to connect to. Provides a basic "NOW" time service for client
            application clocks to synchronised against. Connection is
            closed by the server.
          </t>

          <t hangText="echo broadcast time server port">
            <vspace blankLines="0" />
            A TCP socket listening on the broadcast bridge for a client
            to connect to. Provides a basic "NOW" time service for
            client application clocks to synchronised against. Does
            this after receiving data from the client. All data sent
            by the client is echoed back to the client. Connection is
            closed by the server.
          </t>

          <t hangText="repeating echo broadcast time server port">
            <vspace blankLines="0" />
            A TCP socket listening on the broadcast bridge for a client
            to connect to. Provides a basic "NOW" time service for
            client application clocks to synchronised against. Does
            this after receiving data from the client. All data sent
            by the client is echoed back to the client.  Connection is
            closed by the client.
          </t>

        </list></t>

      </section>
      <section title="Notational Conventions and Generic Grammar">
          <t>
              STAR uses the same notational conventions and generic
              grammar as HTTP/1.1 as defined in RFC 2616. For the
              purposes of this document:
          </t>

          <figure align="center">
            <artwork align="left"><![CDATA[
    NUMBER    = 1*DIGIT
    TIMESTAMP = NUMBER "." NUMBER
    COMMAND   = 1*ALPHA
    ARGUMENT  = *OCTET
    STATUS    = "OK" | "ERROR"
    COMMANDTAG = 1*ALPHA
    JSONRESPONSE = 1*OCTET
            ]]></artwork>
          </figure>
          <t>
              JSONRESPONSE is required to be a valid JSON object. JSON
              is defined in RFC 4627.
          </t>

      </section>
    </section>

    <section title="STAR System Overview">
          <figure align="center" anchor="top_level" title="Top level">
            <artwork align="left"><![CDATA[
+------------------------------------------------------------+
|                                                            |
|    RF       IP                                             |
|  +-----+  +-----+   +-----------------------------------+  |
|  |  B <---->    |   |                                   |  |
|  |  r  |  |  B  |   |  STAR ADDITIONAL SERVICES SERVER  |  |
|  |  o  |  |  r  |   |    ^                      ^       |  |
|  |  a  |  |  i  |   +----|----------------------|-------+  |
|  |  d  |  |  d  |        |                      |          |
|  |  c  |  |  g  |   +----|----------------------|-------+  |
|  |  a  |  |  e <----->   V                      V       |  |
|  |  s  |  |     |   |            STAR CLIENT            |  |
|  |  t  |  |    <----->                                  |  |
|  +-----+  +-----+   +-----------------------------------+  |
|                                                            |
+------------------------------------------------------------+
            ]]></artwork>
          </figure>
      <t>
          STAR consists of 4 main subsystems:
      </t>
      <t>
        <list style="symbols">
          <t>A broadcast system, including a broadcast system and a
             broadcast client</t>

          <t>A broadcast bridge</t>

          <t>A STAR client</t>

          <t>A STAR additional services server</t>
        </list>
      </t>
      <t>
          The STAR client protocol is specifically designed to allow
          clients to be implemented inside a web browser or similarly
          restricted environment (eg flash or java plugins).  Tighter
          synchronisation accuracy could be achieved by mandating a
          less restricted environment, but to do so would restrict
          STAR's applicability &amp; implementability needlessly.
      </t>
      <t>
          Communications in a STAR system includes:
      </t>
      <t>
        <list style="symbols">
          <t>Broadcast within the broadcast system</t>
          <t>The broadcast bridge's reception and analysis of
             the broadcast</t>
          <t>Time synchronisation between the STAR client and the
             broadcast bridge</t>
          <t>Programme information services provided by the broadcast
             bridge to the STAR client</t>
          <t>Synchronised data services from the STAR additional services
             server provided to the STAR client. These fall into two
             categories:
              <list style="symbols">
                <t>Play out scripts</t>
                <t>Additional data sources</t>
              </list></t>
        </list>
      </t>

      <t>
          The rest of this section follows the communication in the system.
      </t>
      <section title="The Broadcast System">
        <t>
            The broadcast system is a digital television service.
            Such broadcast systems have the following core
            characteristics:
            <list style="symbols">
                <t>An audio and video (maybe) service per channel</t>
                <t>A time service giving the current time. For example the
                  time and date (TDT) table in DVB suffices here. TDT data
                  is typically broadcast once per second, and represents
                  the time "now".</t>
                <t>A programme service describing what programme is on "now".
                  In DVB the event information table information contains
                  a "now and next" service. The now and next service data is
                  sent regularly, but is additionally updated when the
                  broadcast programme changes.</t>
            </list>
        </t>
        <t>
            Some analogue television services also contain this
            information, but for the purposes of discussion this
            document assumes a digital television service.
        </t>
        <t>
            This protocol assumes that the existing broadcast service
            and broadcast client (eg a TV) are left unmodified. If a
            service on a non-broadcast client is being played out
            simultaneously with the broadcast service, then this
            service needs to be synchronised to the time as received
            by a broadcast receiver.
        </t>
      </section>
      <section title="The Broadcast Bridge and Broadcast System">
        <t>
            The broadcast bridge bridges the "push" of the broadcast
            world, and the "pull" of the IP based world. In particular,
            it is a server that contains a broadcast client receiver,
            and makes available a time service to synchronise against,
            and now/next programme services over IP for network based
            clients.
        </t>
        <t>
            The broadcast bridge uses the time signal to synchronise
            a local server clock. In particular a DVB based broadcast
            bridge can retrieve TDT packets, and use their regularity
            to set a local clock time and rate of advance.
        </t>
        <t>
            The broadcast bridge also receives the now and next data
            services, and keeps track of what programmes are being
            broadcast. This information is then made available over
            IP. Additionally, the broadcast time at which the now
            and next information changes is monitored. For the
            purposes of STAR, this change time is denoted to be
            "time zero" for the given programme.
        </t>
        <t>
            It is worth noting that whether this is actually time zero
            depends upon the configuration of the broadcast service.
            Furthermore the accuracy of time zero also depends upon
            the configuration of the broadcast service.
        </t>
        <t>
            It is also possible for the broadcast service to include
            a special marker including the time the programme actually
            started via the related content table.
        </t>
        <t>
            Additionally, there may be other means to determine the
            start of the programme. The broadcast bridge is responsible
            for obtaining this time, and making this available to
            clients.
        </t>
      </section>
      <section title="Broadcast Bridge Time Services and STAR Client">
        <t>
            The broadcast bridge makes available a time service for
            the STAR client to synchronise against.
        </t>
          <figure align="center" anchor="time_sync" title="Time Synchronisation, Relevant subsystems">
            <artwork align="left"><![CDATA[
+------------------------------------------------------------+
|  .                                                         |
|  . RF  .  . IP  .                                          |
|  .     |  |     |   .                                      |
|  |    <---->    |   .                                      |
|  |  S  |  |  B  |   |                                      |
|  |  y  |  |  r  |   |--------+                             |
|  |  s  |  |  i  |   |        |                             |
|  |  t  |  |  d <-----> TIME  |           .                 |
|  |  e  |  |  g  |   |  SYNC  |           .              |  |
|  |  m  |  |  e  |   |        |           |              |  |
|  +-----+  +-----+   +-----------------------------------+  |
|    RF       IP      STAR CLIENT                            |
|                                                            |
+------------------------------------------------------------+
            ]]></artwork>
          </figure>
        <t>
            This has the following characteristics:
            <list style="symbols">
                <t>The client can request the current time from the
                   broadcast bridge. </t>
                <t>The client can request the current time from the
                   broadcast bridge with a payload which the broadcast
                   bridge includes in its response.</t>
                <t>The time services are available over both TCP and
                   HTTP</t>
            </list>
        </t>
        <t>
            The current time service can be used to derive a broad view
            of time - that is the current time as seen by a broadcast
            receiver. This can be accurate within a delta proportional
            to the network round trip time.
        </t>
        <t>
            The echoing time service can be used to calculate an approximation
            of the network round trip time. This may be useful in circumstances
            where the network round trip time is likely to be too large
            relative to the additional service intended to be synchronised
            against the broadcast service.
        </t>
        <t>
            The reason for using TCP and HTTP and not UDP are as follows:
            <list style="symbols">
                <t>A tool - dvbdate - exists that provides a means of
                   configuring an NTP server, which can then be used for
                   synchronising time over UDP.</t>
                <t>Restricted clients - such as browsers or plugins - were
                   considered desirable.</t>
                <t>UDP is not available to browser based components</t>
                <t>TCP is commonly available from browser plugins</t>
                <t>HTTP is natively available to browser based clients</t>
            </list>
        </t>
        <t>
            Thus UDP has not been viewed as appropriate.
        </t>
      </section>
      <section title="Broadcast Bridge Programme Services and STAR Client">
        <t>
            IP based programme services available are provided by the
            broadcast bridge to enable a client to determine which
            programme is currently being broadcast. This can be
            correlated with other IP based services to locate
            appropriate data on for playback synchronous to the
            broadcast service. 
        </t>
        <t>
            Prerequisites for this to work:
            <list style="symbols">
                <t>The programme services must include the actual start
                   time of a programme as broadcast.</t>
                <t>This may be queried over TCP or HTTP, for the same
                   reasons as the time services.</t>
            </list>
        </t>
        <t>
            The broadcast bridge also provides facilities for:
            <list style="symbols">
                <t>Identifying what channels the bridge covers,
                   by name and service id</t>
                <t>Summary information across all channels</t>
                <t>Detailed information on the channel's current state,
                   based on channel or serviceid</t>
            </list>
        </t>
        <figure align="center" anchor="prog_services" title="Programme Services interaction ">
            <artwork align="left"><![CDATA[
+------------------------------------------------------------+
|  .                  +--------+                             |
|  . RF  .  . IP  .   |        |                             |
|  .     |  |    <-----> PROG  |                             |
|  |    <---->    |   |  SYNC  |                             |
|  |  S  |  |  B  |   |        |                             |
|  |  y  |  |  r  |   |--------+                             |
|  |  s  |  |  i  |   .        .                             |
|  |  t  |  |  d  |   .                    .                 |
|  |  e  |  |  g  |                        .              |  |
|  |  m  |  |  e  |   .                    |              |  |
|  +-----+  +-----+   +-----------------------------------+  |
|    RF       IP      STAR CLIENT                            |
|                                                            |
+------------------------------------------------------------+
            ]]></artwork>
        </figure>
      </section>


      <section title="STAR Additional Services Server">
        <t>
            The STAR additional services server provides 2 core services:
            <list style="symbols">
                <t>Play out scripts, which describe what events to play out when</t>
                <t>Data storage for data to playback from playout scripts.</t>
            </list>
        </t>
        <t>
            Play out scripts are not required to be limited to playback
            of data from the data storage. In all cases it is expected
            that these scripts and data are to be retrieved over HTTP.
        </t>
        <figure align="center" anchor="playout_systems" title="Playout subsystems' interactions">
            <artwork align="left"><![CDATA[
      . - --------------------------------------+
                                                |
         STAR ADDITIONAL SERVICES SERVER        |
         +-----------------------------------+  |
         |         |          |              |  |
         .         | Play out |  Additional  |  |
                   | Scripts  | data sources |  |
                   |     ^    |      ^       |  |
                  -------|-----------|-------+  |
                         |           |          |
               .---------|-----------V-------+  |
                  |      V    | Output Dev 1 |  |
                  |           |--------------|  |
                  |           | Output Dev 2 |  |
                  |  Play out |--------------|  |
                --+           | Output Dev 3 |  |
                  |   Core    |--------------|  |
                  |           |    ...       |  |
         .        |           |--------------|  |
         |        |           | Output Dev N |  |
.        +-----------------------------------+  |
.        STAR CLIENT                            |
|                                               |
+-----------------------------------------------+
            ]]></artwork>
        </figure>

        <t>
            A client may have many output means, which can be considered
            to include text, links, audio, video, and event send messages
            to a serial port for controlling (for example) arduino based
            devices, synchronous to the broadcast.
        </t>
        <t>
            Three possible alternatives to a play out script delivered
            over HTTP are as follows:
            <list style="symbols">
                <t>To repeatedly poll the server with a "what do I do
                   now message". For services with low levels of service,
                   this may be appropriate, but for nationwide services,
                   this is not a scalable approach, and was discounted on
                   that basis.</t>
                <t>To open a connection to the server, and wait for event
                   data to be sent over the connection. Whilst this limits
                   connection set up and tear down, this could for popular
                   events require a server handle millions of connections
                   held open for long periods of time and data delivered
                   instantaneously to all the clients concurrently. This
                   was not deemed scalable.</t>
                <t>The client opens an XMPP connection, and receiving data
                   over that connection from an XMPP group. This is a
                   promising approach, but raises the implementation bar
                   to that of implementing an XMPP client. It also requires
                   the client to remain connected.</t>
            </list>
        </t>
        <t>
            In all 3 cases, unlike the downloaded file approach, these
            approaches preclude pre-caching data for playback. For this
            reason, a play out file was considered more appropriate.
        </t>
        <section title="Playout Scripts">
          <t>
              Playout scripts are files consisting of a list of events.
              This file is UTF8 encoded, and contains a JSON object.
              Events denote times into the programme, the type of the
              event, and an opaque data blob relating to the event.
              The interpretation of the blob depends on the type. 3
              types are considered critical:
              <list style="symbols">
                  <t>Plain text</t>
                  <t>Base 64 encoded data.</t>
                  <t>URLs</t>
              </list>
          </t>
        </section>
        <section title="Additional data sources">
          <t>
              Due to the fact that additional data sources may be linked
              to by an URL may be audio, video, text, web pages, and more.
              If the client does not understand how to interpret the URL,
              it should pass the interpretation over to a web browser.
          </t>
        </section>
      </section>
      <section title="Full Glass System View">
        <t>
            <xref target="glass_view"></xref> shows all the subsystems
            and their interactions.
        </t>
        <figure align="center" anchor="glass_view" title="Glass view">
            <artwork align="left"><![CDATA[
+------------------------------------------------------------+
|                                                            |
|    RF       IP      STAR ADDITIONAL SERVICES SERVER        |
|  +-----+  +-----+   +-----------------------------------+  |
|  |  B <----> B  |   |         |          |              |  |
|  |  r  |  |  r  |   | Content | Play out |  Additional  |  |
|  |  o  |  |  o  |   |  Server | Scripts  | data sources |  |
|  |  a  |  |  a  |   |     ^   |     ^    |      ^       |  |
|  |  d  |  |  d  |   +-----|---------|-----------|-------+  |
|  |  c  |  |  c  |         |         |           |          |
|  |  a  |  |  a  |   +-----|---------|-----------V-------+  |
|  |  s  |  |  s  |   |     V  |      V    | Output Dev 1 |  |
|  |  t  |  |  t <-----> PROG  |           |--------------|  |
|  |     |  |     |   |  SYNC  |           | Output Dev 2 |  |
|  |  S  |  |  B  |   |        |  Play out |--------------|  |
|  |  y  |  |  r  |   |--------+           | Output Dev 3 |  |
|  |  s  |  |  i  |   |        |   Core    |--------------|  |
|  |  t  |  |  d <-----> TIME  |           |    ...       |  |
|  |  e  |  |  g  |   |  SYNC  |           |--------------|  |
|  |  m  |  |  e  |   |        |           | Output Dev N |  |
|  +-----+  +-----+   +-----------------------------------+  |
|                     STAR CLIENT                            |
|                                                            |
+------------------------------------------------------------+
            ]]></artwork>
        </figure>
      </section>
    </section>

    <section title="STAR Time Synchronisation">
        <t>
            Clock synchronisation is a complex topic, and this specification
            takes a necessarily simplistic view for the following reasons:
            <list style="symbols">
                <t>Expected clients include javascript within a browser.
                   This means sync will happen over HTTP. The many layers
                   involved limit the effectiveness of aiming for extremely
                   tight sync.</t>
                <t>STAR time synchronisation is therefore primarily concerned
                   with synchronising browser events, and simplicity aids
                   implementation.</t>
                <t>For some applications, accuracy of within a second or
                   so is acceptable. For others, accuracy down to 40ms is
                   desirable. Going beyond this would appear to require a
                   UDP based service.</t>
            </list>
        </t>
        <figure align="center" anchor="time_sync2" title="Time Synchronisation, Relevant subsystems">
            <artwork align="left"><![CDATA[
+------------------------------------------------------------+
|  .                                                         |
|  . RF  .  . IP  .                                          |
|  .     |  |     |   .                                      |
|  |    <---->    |   .                                      |
|  |  S  |  |  B  |   |                                      |
|  |  y  |  |  r  |   |--------+                             |
|  |  s  |  |  i  |   |        |                             |
|  |  t  |  |  d <-----> TIME  |           .                 |
|  |  e  |  |  g  |   |  SYNC  |           .              |  |
|  |  m  |  |  e  |   |        |           |              |  |
|  +-----+  +-----+   +-----------------------------------+  |
|    RF       IP      STAR CLIENT                            |
|                                                            |
+------------------------------------------------------------+
            ]]></artwork>
        </figure>

        <t>
            Application clock synchronisation occurs as follows:
            <list style="symbols">
                <t>The client synchronises an application clock against a
                   broad view of time with the broadcast bridge.</t>
                <t>The client may attempt to calculate the error incurred
                   by the network traversal - the network delta. The
                   approach taken is deliberately simple at the possible
                   expense of accuracy.</t>
            </list>
        </t>

      <section title="Broad View of Time synchronisation over TCP">
        <t>
            The client connects to the broadcast time server port on the
            broadcast bridge. The client does not send any data. The
            server's response is a sequence of octets, that are terminated
            by the server closing the connection.
        </t>
        <t>
            The sequence of octets sent forms a TIMESTAMP as defined
            above. That time-stamp is a string representation of a
            floating point value. That float represents the number of
            seconds since the beginning of the Unix epoch - ie the
            number of seconds since 00:00:00 UTC on 1 January 1970.
        </t>
        <t>
            The time obtained is a broadcast time as defined above.
            This defines the broadcast view of time (BVT) according
            to a broadcast receiver at a given instant. These are
            received by the client at a given local clock (LC) times
            from the client clock. 
        </t>
        <t>
            In order to gain a broad view of time, the client needs
            to get two such timestamps - BVT1 and BVT2. These correspond
            to local clock times LC1 and LC2. The further these sets
            of timestamps, the better.
        </t>
        <t>
            Using these times, the client can define a local application
            clock using BVT1, BVT2, LC1, and LC2.  For brevity this is
            defined here in python:
        </t>
        <figure align="center">
            <artwork align="left"><![CDATA[
   class BroadViewClock(object):
       def __init__(self, BVT1, BVT2, LC1, LC2):
           "Configure application clock"
           remote_elapsed = BVT2 - BVT1
           local_elapsed = LC2 - LC1

           self.ratio = remote_elapsed / local_elapsed
           self.remote_baseline = BVT1
           self.local_baseline = LC1

       def sleep(self, time_in_remote_seconds):
           "Sleep for a period time counted in broadcast seconds"
           sleeptime = time_in_remote_seconds / self.ratio
           time.sleep(sleeptime)
           
       def time(self):
           "Return the current time according to broadcast"
           now = time.time()
           local_elapsed = now - self.local_baseline
           remote_elapsed = local_elapsed * self.ratio
           remote_now = self.remote_baseline + remote_elapsed
           return remote_now

   ApplicationClock = BroadViewClock(BVT1, BVT2, LC1, LC2)
            ]]></artwork>
        </figure>

        <t>
            The accuracy of this broad view of time application clock
            depends on the network latency between the client and the
            broadcast bridge. For some applications, this delay will be
            acceptable. For many applications it will be desirable to
            attempt to eliminate the network delta.
        </t>
      </section>

      <section title="Network Delta Corrected Time Synchonisation over TCP">
        <t>
            The client initialises a client application clock which is
            a BroadViewClock as defined in 2.1 above. The client connects
            to the echo broadcast time server port on the broadcast bridge.
        </t>
        <t>
            Upon connecting the client sends time request of the following
            form:
        </t>

        <figure align="center">
            <artwork align="left"><![CDATA[
    TIMEREQUEST = TIMESTAMP CRLF
            ]]></artwork>
        </figure>

        <t>
            That is it send an octet stream which is a string representation
            of a float, representing a timestamp of the number of seconds
            since the start of the unix epoch, followed by a CRLF sequence.
        </t>

        <t>
            The server response is as follows:
        </t>

        <figure align="center">
            <artwork align="left"><![CDATA[
    BLOBRESPONSE = 1*OCTET
    ECHOTIME = BLOBRESPONSE " " TIMESTAMP
            ]]></artwork>
        </figure>

        <t>
            The server then terminates the connection. BLOBRESPONSE as
            defined here is whatever data the client sends the server.
            Whilst the client MUST send data in the form defined as
            TIMEREQUEST, the server must be lenient and respond with
            whatever was sent as blob response.
        </t>

        <t>
            Using the BroadViewClock, the client can build on BroadViewClock
            to create a new application clock which removes the network
            delta as follows:
        </t>

        <figure align="center">
            <artwork align="left"><![CDATA[
class NetworkCorrectedBroadcastClock(object):
    def __init__(self, application_clock, network_delta):
        self.application_clock = application_clock
        self.network_delta = network_delta
        
    def sleep(self, delay):
        self.application_clock.sleep(delay)
        
    def time(self):
        self.application_clock.time() + self.network_delta
            ]]></artwork>
        </figure>
        <figure align="center">
            <artwork align="left"><![CDATA[
BVT1, BVT2, LC1, LC2 -- Obtained as before
CoarseApplicationClock = BroadViewClock(BVT1, BVT2, LC1, LC2)

TOLERANCE = 0.01 # 10ms
WITHIN_TOLERANCE = False
            ]]></artwork>
        </figure>
        <figure align="center">
            <artwork align="left"><![CDATA[
while not WITHIN_TOLERANCE:
    sendtime = CoarseApplicationClock.time()
    sendtime_for_network = str(float(sendtime))
    
    # sendtime_for_network and BLOBRESPONSE should be identical
    BLOBRESPONSE, TIMESTAMP = EchoTimeRequest(sendtime_for_network,
                                              server=broadcastbridge,
                                              port=echo_time_port)
            ]]></artwork>
        </figure>
        <figure align="center">
            <artwork align="left"><![CDATA[
    # Assuming network delays are constant  within a certain delta,
    # the following two values should be identical or close to
    # identical
    remote_now = float(TIMESTAMP)
    now = CoarseApplicationClock.time()
            ]]></artwork>
        </figure>
        <figure align="center">
            <artwork align="left"><![CDATA[
    if abs(remote_now - now) < TOLERANCE: 
        WITHIN_TOLERANCE = True
    
# Assume network is symmetrical
network_delta = (remote_now - sendtime)/2


BetterApplicationClock = NetworkCorrectedBroadcastClock(
                                            CoarseApplicationClock,    
                                            network_delta)
            ]]></artwork>
        </figure>

        <t>
            At this point the client then has a network corrected local
            clock locked to the same clock as broadcast, within a reasonable
            tolerance.
        </t>
      </section>
    </section>
    <section title="STAR Broadcast Bridge Programme Services over TCP">
      <figure align="center" anchor="prog_time_sync" title="Programme Time Synchronisation, Relevant subsystems">
          <artwork align="left"><![CDATA[
+------------------------------------------------------------+
|                                                            |
.                                                            .
.                 .   +---------- -                          .
|           .     .   |        |                             |
|  .     .  .    <-----> PROG  |                             |
|  |    <---->    |   |  SYNC  |                             |
|  |  S  |  |  B  |   |        |                             |
|  |  y  |  |  r  |   |--------+                             |
|  |  s  |  |  i  |   |        .                             |
|  |  t  |  |  d  |   .                                      |
|  |  e  |  |  g  |   .                                      |
|  |  m  |  |  e  |                                          |
|  +-----+  +-----+   STAR CLIENT                            |
|    RF       IP                                             |
|                                                            |
+------------------------------------------------------------+
          ]]></artwork>
      </figure>

      <t>
          Programme Services are provided on a request/response basis.
      </t>
  
      <t>
          The client connects to the broadcast bridge programme port
          and sends a REQUEST matching the following:
      </t>
  
      <figure align="center">
          <artwork align="left"><![CDATA[
     REQUEST = COMMAND " " ARGUMENT CRLF
          ]]></artwork>
      </figure>
    
      <t>
          Note that the command is terminated by a blank line.
      </t>

      <t>
          The server sends a RESPONSE as follows:
      </t>

      <figure align="center">
          <artwork align="left"><![CDATA[
     RESPONSE = STATUS " " COMMANDTAG " " JSONRESPONSE
          ]]></artwork>
      </figure>

      <t>
          The response is terminated by closing the connection.
      </t>

      <t>
          If the status is ERROR, the client should handle the error
          gracefully. COMMANDTAG is always relative to the command the
          client sent to the server.
      </t>

      <t>
          Commands the broadcast bridge MUST implement:
          <list style="symbols">
              <t>time</t>
              <t>echotime</t>
              <t>summary</t>
          </list>
      </t>

      <t>
          Commands the broadcast bridge SHOULD implement:
          <list style="symbols">
              <t>services</t>
              <t>channels</t>
              <t>channel</t>
              <t>service</t>
          </list>
      </t>
      <t>
          Note: The server is expected to lower case all commands and
          arguments on the way into the server.
      </t>
      <section title="command: time">
        <t>
            This provides an alternative interface to the timing subsystem,
            and can be used in much the same way. It has a higher parsing
            overhead, and hence speed penalty.
        </t>

        <section title="Arguments">
          <t>
              None
          </t>
        </section>
        <section title="Response format">

          <t>
              The response is a JSON object with 3 name value pairs:
              <list style="symbols">
                  <t>time - Number of seconds since the Unix Epoch. The timezone is defined to be UTC.</t>
                  <t>
                      elemental - 9 element array representation of the same time, consisting of:
                      <list style="symbols">
                          <t>year - integer representing the full year </t>
                          <t>month - integer in range 1..12</t>
                          <t>day of month - integer day of the month</t>
                          <t>hour - integer</t>
                          <t>minute - integer</t>
                          <t>seconds - integer</t>
                          <t>weekday - integer in range 0..6, where monday is 0.</t>
                          <t>day of year - counting from 1</t>
                          <t>
                              daylight savings flag
                              <list style="symbols">
                                  <t>0 means no daylight savings adjustment has taken place</t>
                                  <t>1 means time is adjusted for daylight savings</t>
                              </list>
                          </t>
                      </list>
                  </t>
                  <t>textual - Again, the same time as a human readable time/date. This should be treated as human readable and machine opaque.</t>
              </list>
          </t>
        </section>
        <section title="Example">
          <figure align="center">
              <artwork align="left"><![CDATA[
  SEND: time
  RECV: OK TIME {"elemental": [2010, 7, 5, 17, 21, 10, 0, 186, 1],
  "textual": "Mon Jul  5 17:21:10 2010", "time": 1278346870.0}
              ]]></artwork>
          </figure>
        </section>
      </section>

      <section title="command: echotime">
        <t>
            This provides an alternative interface to the timing subsystem,
            and can be used in much the same way. It has a higher parsing
            overhead, and hence speed penalty.
        </t>

        <section title="Arguments">
          <t>
              TIMESTAMP - as defined above
          </t>
        </section>
        <section title="Response format">
          <t>
              The response is a JSON object with 4 name value pairs:
              <list style="symbols">
                  <t> time - Number of seconds since the Unix Epoch. The
                      timezone is defined to be UTC. </t>
                  <t> elemental - 9 element array representation of time as
                      defined before in section 4.1.2 </t>
                  <t> textual - Same time as a human readable time/date.
                      As in 4.1.2 this is defined as machine opaque and human
                      readable. </t>
                  <t> echo - Contains whatever the client sent as TIMESTAMP </t>
              </list>
          </t>
        </section>
        <section title="Example">
          <figure align="center">
              <artwork align="left"><![CDATA[
  SEND: echotime 1278346870.0
  RECV: OK TIME {"echo": "1278346870.0", "elemental": [2010, 7, 5,
     17, 21, 15, 0, 186, 1], "textual": "Mon Jul  5 17:21:15 2010",
     "time": 1278346875.0}
              ]]></artwork>
          </figure>
        </section>
      </section>

      <section title="command: summary">
        <t>
            Provides a quick lookup mechanism of channel name, programme
            and start time.
        </t>

        <section title="Arguments">
          <t>
              None
          </t>
        </section>
        <section title="Response format">
          <t>
              The response is a JSON object with as many name value pairs
              as channels the broadcast bridge can receive. Each pair has
              the same format:
              <list style="symbols">
                  <t> channelname - which may be either:
                  <list style="symbols">
                    <t> the human readable name of the channel from the
                        broadcasting system </t>
                    <t> The symbolic service id for the channel on this
                        broadcast system.</t>
                  </list>
                  </t>
                  <t> A value is an array consisting of 2 values
                  <list style="symbols">
                    <t> First value is TIMESTAMP when programme started </t>
                    <t> Second value is Programme name</t>
                  </list>
                  </t>
              </list>
              This format means that the summary contains duplication of
              information. The reason for this is to enable clients to be
              simpler to implement.
          </t>
        </section>
        <section title="Example">
          <figure align="center">
              <artwork align="left"><![CDATA[
  SEND: summary
  RECV: OK SUMMARY {"bbc one": [1278346448.0, "The Weakest Link"],
    "bbc two": [1278346554.0, "Escape to the Country"], 
    "cbeebies": [1278346632.0, "ZingZillas"], 
    "cbbc channel": [1278346613.0, "ROY"], 
    "bbc radio 1": [1278342000.0, "Scott Mills"],
    "bbc radio 2": [1278345900.0, "Simon Mayo"],
    "bbc radio 3": [1278345610.0, "In Tune"],
    "bbc radio 4": [1278345610.0, "PM"],
    "4168": [1278346448.0, "The Weakest Link"],
    "4287": [1278346554.0, "Escape to the Country"], 
    "4672": [1278346632.0, "ZingZillas"], 
    "4608": [1278346613.0, "ROY"], 
    "6720": [1278342000.0, "Scott Mills"],
    "6784": [1278345900.0, "Simon Mayo"],
    "6848": [1278345610.0, "In Tune"],
    "6912": [1278345610.0, "PM"]}
              ]]></artwork>
          </figure>
        </section>
      </section>

      <section title="command: services">
        <t>
            This command returns the list of services available on the bridge.
            The reason for this is to accommodate automated lookups based upon
            service ids used in the broadcast system rather than based on
            channel name.
        </t>

        <section title="Arguments">
          <t>
              None
          </t>
        </section>
        <section title="Response format">
          <t>
              The response is a JSON object which is an array of integers,
              each one representing the service ids which may be queried.
          </t>
        </section>
        <section title="Example">
          <figure align="center">
              <artwork align="left"><![CDATA[
  SEND: services
  RECV: OK SERVICES  [4288, 4544, 6016, 5952, 6784, 4168, 5760,
    6720, 5888, 4352, 4416, 6848, 5632, 4608, 4672, 7168, 4736,
    5824, 6912, 5696, 4287]
              ]]></artwork>
          </figure>
        </section>
      </section>


      <section title="command: channels">
        <t>
            This command returns the list of channels available on
            the bridge. This uses the names of the channels as used
            by the broadcast system.
        </t>

        <section title="Arguments">
          <t>
              None
          </t>
        </section>
        <section title="Response format">
          <t>
              The response is a JSON object which is an array of strings,
              where each string is a channel name available on the bridge.
          </t>
        </section>
        <section title="Example">
          <figure align="center">
              <artwork align="left"><![CDATA[
  SEND: channels
  RECV: OK CHANNELS  ["bbc one", "bbc two", "cbeebies",
    "cbbc channel", "bbc radio 1",  "bbc radio 2",
    "bbc radio 3", "bbc radio 4"]
              ]]></artwork>
          </figure>
        </section>
      </section>


      <section title="command: channel">
        <t>
            This command returns all the information the broadcast bridge
            has on a particular channel at that instant. This provides a
            bridged version of the current "now and next" information for
            the channel. In particular, the dates and time information are
            provided "as is" from the broadcast system.
        </t>

        <section title="Arguments">
          <t>
              *OCTET - String that represents a channel name
          </t>
        </section>
        <section title="Response format">
          <t>
              Contains a JSON object with 2 name value pairs:
              <list style="symbols">
                  <t> channel - value is a string with the channel name </t>
                  <t> info - value is another JSON object with 3 name value pairs:
                  <list style="symbols">
                    <t> changed - value is a floating point value which is the number of seconds since the Unix Epoch. Represents when the now and next information changed. </t>
                    <t> NOW - now/next JSON object (see below) where the "when" value is "NOW" </t>
                    <t> NEXT - now/next JSON object (see below) where the "when" value is "NEXT"</t>
                  </list>
                  </t>
              </list>
          </t>
          <t>
              A now/next JSON object is a JSON object with 8 name value pairs:
              <list style="symbols">
                    <t> name - string with the name of the programme the now/next object refers to </t>
                    <t> description - a string containing a human readable description of the programme. </t>
                    <t> startdate - an array of integers, representing [year, month, day] </t>
                    <t> starttime - an array of integers, representing [hours, minutes, seconds] </t>
                    <t> duration - an array of integers, representing [hours, minutes, seconds] </t>
                    <t> when - a string which is either "NOW" or "NEXT" </t>
                    <t> service - an integer which is the broadcast service id </t>
                    <t> transportstream - an integer which is the broadcast service id </t>
              </list>
          </t>
        </section>
        <section title="Example">
          <figure align="center">
              <artwork align="left"><![CDATA[
  SEND: channel bbc one
  RECV: OK CHANNEL  {
    "channel": "bbc one",
    "info": 
      {"NEXT": 
          {"startdate": [2010, 7, 5],
          "name": "BBC News at Six",
          "service": 4168,
          "when": "NEXT",
          "duration": [0, 30, 0],
          "starttime": [17, 0, 0],
          "transportstream": 4168,
          "description": "The latest national and international 
                          news stories from the BBC News team,
                          followed by weather. [S]"
          },
              ]]></artwork>
          </figure>
          <figure align="center">
              <artwork align="left"><![CDATA[
      "changed": 1278346448.0,
              ]]></artwork>
          </figure>
          <figure align="center">
              <artwork align="left"><![CDATA[
      "NOW": {"startdate": [2010, 7, 5],
              "name": "The Weakest Link",
              "service": 4168,
              "when": "NOW",
              "duration": [0, 45, 0],
              "starttime": [16, 15, 0],
              "transportstream": 4168,
              "description": "Anne Robinson presents the quick-
                          fire general knowledge quiz in which
                          contestants must decide at the end
                          of each round which of their number
                          should be eliminated. [S]"
              }
      }
  }
              ]]></artwork>
          </figure>
        </section>
      </section>

      <section title="command: service">
        <t>
            This command returns all the information the broadcast bridge
            has on a particular channel, identified by broadcast system
            service id at that instant.
        </t>

        <section title="Arguments">
          <t>
              *OCTET - String that represents a service number 
          </t>
        </section>
        <section title="Response format">
          <t>
              The response format is the same as the command "channel"
          </t>
        </section>
        <section title="Example">
          <figure align="center">
              <artwork align="left"><![CDATA[
  SEND: service 4287
  RECV: OK CHANNEL {
    "info": {
        "channel": "bbc two"
          "NEXT": {
                  "startdate": [2010, 7, 5], "
                  "name": "Eggheads", 
                  "service": 4287, 
                  "when": "NEXT", 
                  "duration": [0, 30, 0], 
                  "starttime": [17, 0, 0], 
                  "transportstream": 4168, 
                  "description": "General knowledge quiz in which
                    teams from all over the UK battle to beat the
                    Eggheads, some of the country's top quiz
                    champions. Also in HD. [S]"},
              ]]></artwork>
          </figure>
          <figure align="center">
              <artwork align="left"><![CDATA[
          "changed": 1278346554.0,
              ]]></artwork>
          </figure>
          <figure align="center">
              <artwork align="left"><![CDATA[
          "NOW": {
                  "startdate": [2010, 7, 5],
                  "name": "Escape to the Country", 
                  "service": 4287, 
                  "when": "NOW", "duration": [0, 45, 0],
                  "starttime": [16, 15, 0], 
                  "transportstream": 4168, 
                  "description": "New Forest: Series in which
                  prospective buyers are helped to find their dream
                    home in the country. Jules Hudson helps a couple
                    with a budget of 650,000 pounds find a house in
                      the New Forest. [S]"}
          },
    }
              ]]></artwork>
          </figure>
        </section>
      </section>
    </section>

    <section title="STAR Broadcast Bridge Programme Services over HTTP">
      <section title="Mapping to HTTP from the TCP Service">
        <t>
            This provides a basic web based API to access the same
            commands as the TCP command format.
        </t>

        <t>
            The broadcast bridge presents itself on the following form of URL:
        </t>
          <figure align="center">
              <artwork align="left"><![CDATA[
    http://example.com/bridge?command=<CMD>
    http://example.com/bridge?command=<CMDA>&args=<ARG>
              ]]></artwork>
          </figure>

        <t>
            The response type for URLs of the format above is
            application/json, and the format/structure matches the
            TCP version precisely.
        </t>
    
        <t>
            CMD is any command from the TCP version which does not take
            any arguments.
        </t>
    
        <t>
            CMDA is any command from the TCP version which takes at least
            one argument. The argument it takes is passed through in args.
        </t>
      </section>

      <section title="Example Mappings">
        <section title="command: time">
          <figure align="center">
              <artwork align="left"><![CDATA[
http://example.com/bridge?command=time
              ]]></artwork>
          </figure>
        </section>

        <section title="command: echotime">
          <figure align="center">
              <artwork align="left"><![CDATA[
http://example.com/bridge?command=echotime&args=1278346870.0
              ]]></artwork>
          </figure>
        </section>

        <section title="command: summary">
          <figure align="center">
              <artwork align="left"><![CDATA[
http://example.com/bridge?command=summary
              ]]></artwork>
          </figure>
        </section>

        <section title="command: services">
          <figure align="center">
              <artwork align="left"><![CDATA[
http://example.com/bridge?command=services
              ]]></artwork>
          </figure>
        </section>

        <section title="command: channels">
          <figure align="center">
              <artwork align="left"><![CDATA[
http://example.com/bridge?command=channels
              ]]></artwork>
          </figure>
        </section>

        <section title="command:  channel">
          <figure align="center">
              <artwork align="left"><![CDATA[
http://example.com/bridge?command=channel&args=bbc%20one
              ]]></artwork>
          </figure>
        </section>

        <section title="command:  service">
          <figure align="center">
              <artwork align="left"><![CDATA[
http://example.com/bridge?command=service&args=4287
              ]]></artwork>
          </figure>
        </section>

      </section>
    </section>

    <section title="STAR Additional Services Server">
        <t>
            After synchronising a clock, and after retrieving programme
            start times, the STAR client (which may be a javascript based
            client inside a web page) can then choose to retrieve a play
            out script from the STAR additional services server. How this
            happens precisely is left as an exercise to an implementer.
        </t>
        <t>
            One approach that is feasible is as follows:
            <list style="symbols">
                <t> A broadcaster publishes a schedule online with programme
                    names, times and a unique id. </t>
                <t> Using the broadcast bridge, the STAR client identifies
                    the current programme, allowing the identification of
                    the unique id. </t>
                <t> The STAR client can then request from a web service the
                    specific play out script for that programme. </t>
            </list>
            There are clearly other feasible approaches, and STAR is not
            prescriptive about any particular approach.
        </t>
        <t>
            That play out script MAY be delivered over HTTP.
        </t>
    </section>


    <section title="STAR Playout Scripts">

      <section title="MIME type">
        <t>
            The MIME type of play out script is  application/json. 
        </t>
      </section>
      <section title="File Format">
        <t>
            The STAR play out script
            <list style="symbols">
                <t> is a UTF8 encoded </t>
                <t> contains a JSON encoded object. </t>
            </list>
        </t>
        <t>
            The JSON object:
            <list style="symbols">
                <t> is an array of events</t>
            </list>
        </t>
        <t>
            Each event is an array consisting of 3 values:
            <list style="symbols">
                <t> The first value is a float representing a timestamp - see 7.3 </t>
                <t> The second is an event type - see 7.4 </t>
                <t> The third is event data - see 7.5 </t>
            </list>
        </t>

      </section>
      <section title="Timestamps">
        <t>
            Timestamps are defined to be relative to time zero of
            the programme as defined above.
        </t>
      </section>
      <section title="Event types">
        <t>
            Event type is defined as follows
        </t>
        <figure align="center">
              <artwork align="left"><![CDATA[
EVENT TYPE    = *ENCODINGTAG   DATATYPETAG
ENCODINGTAG    = ( "INLINE" | "BASE64"|"URL") ";"
DATATYPETAG   = MIMETYPE | CUSTOMTYPE
CUSTOMTYPE    = DOMAIN "/" *OCTECT
              ]]></artwork>
        </figure>
        <t>
          ie An optional (encoding tag and semicolon) preceding a base type.
        </t>
        <section title="Datatype Tags">
          <t>
              A base type may be:
              <list style="symbols">
                  <t> a standard MIME Type </t>
                  <t> An application's custom type. As defined above an
                      application's custom type is defined in terms of
                      DOMAINNAME followed by a "/" followed by any text.
                      It is up to the entity that owns the domain DOMAINNAME
                      to publish and manage that namespace. </t>
              </list>
          </t>



        </section>
        <section title="Encoding Tags">
          <t>
              The encoding tag defines how to interpret the encoding of
              the event data:
              <list style="symbols">
                  <t> "INLINE" - means to treat the event data as raw data of
                      the type given (eg textual)</t>
                  <t> "BASE64" - means  that the event data inline is the
                      data of the given datatype, but is base64 encoded.
                      (This allows for example a small audio/wav file to be
                      represented inline. This is expected to be a rare
                      necessity but potentially useful)</t>
                  <t> "URL" - means to treat the event data as an URL to
                      download and interpret at the given time.</t>
              </list>
          </t>
          <t>
              Given the encoding tag is optional, if the encoding tag is
              not supplied, then the following rules are used to determine
              the encoding:
              <list style="symbols">
                  <t> If the datatype tag is the MIME type "text/plain" then
                      the encoding tag is inline</t>
                  <t> Otherwise the encoding tag is assumed to be URL (This
                      allows for example a small audio/wav file to be
                      represented inline. This is expected to be a rare
                      necessity but potentially useful)</t>
              </list>
          </t>
        </section>
      </section>
      <section title="Event data encoding">
          <t>
              The actual event data interpretation is just a string. 
          </t>
          <t> If the data encoding is an URL:
              <list style="symbols">
                  <t> Then the STAR client accesses the resource indicated
                  by the URL and uses that resource as the event data. </t>
              </list>
          </t>
          <t> If the data encoding is BASE64:
              <list style="symbols">
                  <t> Then the STAR client decodes the BASE64 encoded data,
                      and uses that as the event data </t>
              </list>
          </t>
          <t> Otherwise the data encoding is INLINE:
              <list style="symbols">
                  <t> This means the STAR client just treats the raw data
                      as the event data. </t>
              </list>
          </t>
          <t>
              The data is then interpreted according to local rules for
              the given MIME type. 
          </t>
      </section>


      <section title="Example">
        <t>
          Given the following (tidied) example:
        </t>
        <figure align="center">
              <artwork align="left"><![CDATA[
[[0, "text/plain", "Programme Start"],
 [0.5, "audio/wav", "http://www.example.com/example.wav"],
 [1.0, "BASE64;image/vnd.microsoft.icon", 'AAABAAIAEBAAAAAAABo...'],
 [1.5, "URL;example.com/game", "http://www.example.com/games/gam"],
 [2.0, "example.com/serial", "http://www.example.com/ardunio/robo"],
 ...
]
              ]]></artwork>
        </figure>
        <t>
            Time 0 is interpreted as as text/plain - which may be displayed
            on a screen, or spoken.
        </t>
        <t>
            Time 0.5 is interpreted as an URL to download and then treat
            as an audio/wav file.
        </t>
        <t>
            Time 1.0 is interpreted an inline embedded ".ico" file, which
            is base 64 encoded in the data field.
        </t>
        <t>
            Time 1.5 is interpreted as an URL to download and then treat
            according to the rules defined by the entity owning "example.com"
            as the datatype "example.com/game".
        </t>
        <t>
            Time 2.0 is interpreted as an URL to download and then treat
            according to the rules defined by the entity owning
            "example.com" as the datatype "example.com/serial".
            For example, this could mean to take whatever data is sent
            back and to send that to the serial port, controlling an
            arduino controlled robot.
        </t>
      </section>
    </section>

    <section title="Future Expansion">
      <t>
          Future expansion of datatype tags is provided through the standard
          IANA MIME types, and also by the custom datatype tag formats which
          may be managed by the owner of a domain name.
      </t>
    </section>

    <section title="IANA Considerations">
      <t>This memo includes no request to IANA.</t>
      <t>
          This document describes an experimental protocol. It re-uses the
          existing IANA namespace for defining datatype tags, and additionally
          defines a mechanism for users of the protocol to define their own
          namespace for defining datatype tags, and maintaining this within
          their organisation.
      </t>

      <t>
          As a result this protocol has no IANA considerations.
      </t>
    </section>


    <section title="Security Considerations">
      <t>All drafts are required to have a security considerations section.
      See <xref target="RFC3552">RFC 3552</xref> for a guide.</t>
      <t>
          This section is meant to inform application developers,
          information providers, and users of the security limitations
          in STAR as described by this document. The discussion does not
          include definitive solutions to the problems revealed, though
          it does make some suggestions for reducing security risks.
      </t>

      <t>
          It is not warranted to be exhaustive.
      </t>

      <section title="Personal Information - Abuse of Server Logs">
        <t>
            The server enables the maintainer of the broadcast bridge to
            identify what programmes particular IPs are using. If the
            maintainer of the broadcast bridge or additional services
            server store cookies, then they are potentially able to
            identify particular individuals. 
        </t>
        <t>
              Since the event file format
            is defined to automatically download URLS in the file, if
            the client does this at the same time as the moment in the
            programme occurs, then the maintainer of the broadcast bridge
            is able to track which users are watching how much of what
            programme through the broadcast bridge log data.
        </t>
        <t>
           The client is not required to download the URLs at that instant,
           and may download the content beforehand, which mitigates this
           risk.
        </t>
</section>

      <section title="Data encoding and decoding">
        <t>
            JSON format data is directly interpretable in a number of
            languages, including actionscript, javascript, and python. If
            the creator of the client fails to use a parser, this opens
            the client up to well known attacks.
        </t>

        <t>
            Similarly, assuming BASE64 encoded data is BASE64 encoded without
            any conversion errors would open up the client to well known
            attacks.
        </t>
      </section>

      <section title="Denial of Service">
        <t>
            It is possible for a badly crafted file to cause a denial of
            service attack on the additional services store. For example,
            if all the timestamps were "0", this would mean "interpret all
            these events as being at time 0". This could cause a very large
            number of concurrent requests against the additional services
            store, albeit by accident. Hijacking of a site and replacement
            of the play out script with a malicious play out script could
            result in a similar effect.
        </t>
      </section>
    </section>

    <section anchor="Acknowledgements" title="Acknowledgements">
      <t>
          This specification makes heavy use of the augmented BNF and generic
          constructs defined by David H. Crocker for RFC 822. 
      </t>
      <t>
          Also, this specification is inspired by HTTP to be content agnostic
          and extensible, and additionally by the semantic web approach of
          allowing namespaces interpretation to be owned by a group.
      </t>
      <t>
          The time synchronisation approach is based very loosely on a
          simplification of the core ideas of a number of time synchronisation
          protocols.
      </t>
    </section>


    <!-- Possibly a 'Contributors' section ... -->


  </middle>

  <!--  *****BACK MATTER ***** -->

  <back>
    <!-- References split into informative and normative -->

    <!-- There are 2 ways to insert reference entries from the citation libraries:
     1. define an ENTITY at the top, and use "ampersand character"RFC2629; here (as shown)
     2. simply use a PI "less than character"?rfc include="reference.RFC.2119.xml"?> here
        (for I-Ds: include="reference.I-D.narten-iana-considerations-rfc2434bis.xml")

     Both are cited textually in the same manner: by using xref elements.
     If you use the PI option, xml2rfc will, by default, try to find included files in the same
     directory as the including file. You can also define the XML_LIBRARY environment variable
     with a value containing a set of directories to search.  These can be either in the local
     filing system or remote ones accessed by http (http://domain/dir/... ).-->

    <references title="Normative References">
      <!--?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml"?-->
      &RFC2119;

<!--      <reference anchor="min_ref"> -->
        <!-- the following is the minimum to make xml2rfc happy -->
<!--
        <front>
          <title>Minimal Reference</title>

          <author initials="authInitials" surname="authSurName">
            <organization></organization>
          </author>

          <date year="2006" />
        </front>
      </reference> -->
    </references>

    <references title="Informative References">
      <!-- Here we use entities that we defined at the beginning. -->

      &RFC2629;

      &RFC3552;

 <!--      &I-D.narten-iana-considerations-rfc2434bis; -->

      <!-- A reference written by by an organization not a person. -->

<!--      <reference anchor="DOMINATION"
                 target="http://www.example.com/dominator.html">
        <front>
          <title>Ultimate Plan for Taking Over the World</title>

          <author>
            <organization>Mad Dominators, Inc.</organization>
          </author>

          <date year="1984" />
        </front>
      </reference> -->
    </references>

    <section anchor="app-additional" title="Additional Stuff">
      <t>This becomes an Appendix.</t>
    </section>

    <!-- Change Log

Based upon draft-davies-template-bare.xml

v00 2010-12-12 MPS Started!
v01 2011-01-04 MPS Finally finished version 1 of this (!)

                      -->

  </back>
</rfc>
