HandrollTV API

Introduction

 

Our API provides the following methods for generating HTML5 video players and Timelines:

·       Create Video Timeline: for one or more video files

·       Add Name-Value Pair Metadata: add metadata to the Timeline

·       Retrieve Video Timeline: get the Timeline for a specific video

Handroll Timeline

While most video frameworks make the video file itself the container, we have chosen to make the Timeline our governing structure in an open XML framework. Metadata and events related to the video are expressed in the Timeline and travel with the video wherever it is embedded. Over the coming months we will be expanding the Timeline and API to be more social, semantic and segmentable.

Authentication

There are no developer keys or authentication in this release, but watch for updates as they are added.

Communication

We are still experimenting with metadata structures and building out the Timeline calls, so please watch for our updates on Twitter as the API evolves:

@handrolltv

We really want to hear from you as you use the service.

Email us at:    dev@handroll.tv

Or online at:   http://handroll.uservoice.com/forums/60433-general 

Creating a Video Timeline

Method: POST
Parameters: 
src (URL to a valid HTML5 video source - eg http://www.host.com/video.mp4)
URL: http://www.handroll.tv/api/timeline
Returns: New unique timeline id (string)
Status Codes: 201 (success), 500 (error)

Adding NVP Metadata to a Timeline

The Handroll API allows the adding of unlimited numbers of named-value-pairs to a timeline. This allows a developer to add and access all sorts of information on the timeline, without being limited to those in the official spec.

Method: POST
Parameters: 
key (string)
value (string)
URL: http://www.handroll.tv/api/metadata/[timeline_id]
Returns: [NULL]
Status Codes: 200 (success), 404 (cannot find timeline id), 400 (problem with key or value parameters)

Retrieving a Video Timeline

Method: GET
Parameters: [None]
URL: http://www.handroll.tv/api/timeline/[timeline_id].json
Returns: Video timeline (JSON)
Status Codes: 200 (success), 404 (cannot find timeline id)

Anatomy of a Timeline

In this example we have a Handroll Timeline with the ID of abc123. There is one video in this timeline located at http://www.handroll.tv/demo.mp4. Through the Handroll API additional metadata about this video has been added including a locationwith geographic latitude and longitude information, a URL and a Twitter username that all relate to this timeline. The timeline also comes with a section for authoritative data - this is contained in the readonly node.

<?xml version="1.0"?>
<rollup version="0.1" id="abc123">
  <video src="http://www.handroll.tv/demo.mp4">
    <metadata>
      <location>geolat:40.7204;geolong:-73.9933</location>
      <url>http://www.handroll.tv</url>
      <twitter>handrolltv</twitter>
    </metadata>
  </video>
  <readonly>
    <impressions>500</impressions>
    <plays>250</plays>
  </readonly>
</rollup>