The Universal Control (UC) API is a RESTful Web API designed to allow the
core functionality of any network-connected set-top box, personal video
recorder, Internet radio or similar device to be controlled from client
software running on another device on the home network.

The protocol is specified in BBC R&D White Paper 194:

< http://www.bbc.co.uk/rd/publications/whitepaper194.shtml >

A set-top box or other media device runs a UC server that implements the API,
and client devices communicate with the TV/set-top-box via it. Because
it is a web based API, clients could be implemented on a wide range of platforms:
anything from a mobile phone app to a dynamic web page.

The Universal Control API has been designed with two main kinds of use case in mind:
 * Remote control applications running on remote devices such as mobile phones
   and tablets: the UC approach allows the design of the remote APIs to be
   completely customised to take into account the capabilities of specific devices
   or the requirements of particular groups of users, such as people with
   disabilities.
   The API is complementary in this regard to other industry remote UI approaches
   such as DLNA RUI or RVU.
 * Enhanced media experiences under the control of broadcasters and other
   content providers, in which parts of a single media experience are presented on
   multiple devices.  The media industry is currently interested in the idea of 
   "Dual Screen" experiences: the UC API addresses these by providing a distributed,
   scalable way to synchronise the devices taking part in such an experience, and
   supports more advanced use cases that involve content-provider-authored
   applications running on the set-top box as well as on the client devices.

The source files in this repository comprise prototype implementations of
Universal Control API clients and servers:

 * A MythTV-based example server implementation
 * An example remote control client implementation, implemented in HTML,
   Javascript and CSS.

This software is provided for example purposes only, and we provide no guarantee
of it being free from bugs. We do not recommend its use in any mission-critical
environments.



Getting started
---------------

The prototype server adds a UC API server implementation to MythTV. It
requires a slightly customised (patched) build of MythTV at present. See
the INSTALL file for detailed instructions on how to get it up and running.

The client is a simple web based client that requires no installation
process. See the README file in its directory.

The repository also contains some utilities - such as a tool for creating and
decoding 'pairing codes'.



Overview of files:
------------------

/scripts   ... scripts for packaging up UC server and components into
               tarballs for easy installation.

/clients   ... example client(s)

/servers   ... code for UC server

/servers/lib/python   ... various libraries needed by the UC server,
                          including core UC server code that can be reused
                          across different server implementations

/servers/mythtv   ... code specific to UC server for MythTV

/servers/mythtv/scripts/ucserver_mythtv.py  ... the main executable

/servers/platform_extras/mythtv   ... scripts for building a patched mythtv

/utilities  ... useful utilities - eg. one for creating and decoding
                'pairing codes'



Licensing terms and authorship
------------------------------
See 'COPYING' and 'AUTHORS' files.