FLVio MediaKit - Getting Started

Overview

This document describes how to get started with the FLVio MediaKit API.

Register an account

The first step is to register a FLVio account, if you haven't done so already. Go to FLVio Sign up and create an account. By default, you will get a Free Trial account. You can upgrade to a full account at any time.

Control Panel

Once you have created a FLVio account, you can login to the Control Panel. This is where you can view and modify your account details (like e-mail address and password) and view your usage reports.

Write Code

FLVio is a web service. This means you need to write code to integrate it with your own application. As a RESTful HTTP API, the amount of code you actually need to write is minimal. To make this even easier, client code samples for various languages are provided.

A brief introduction to the API is given below. For more details see the FLVio Support section and refer to the API Reference Guide.

API Introduction

FLVio provides a RESTful HTTP API. That is, it uses the well known HTTP standard in a way that it was originally designed for. FLVio data (media items) are exposed as resources, one resource per URL (just like the web) which can be created/read/updated/deleted by HTTP calls, using the standard methods GET/HEAD/PUT/POST/DELETE. This makes it extremely easy to make API calls as almost every practical programming language contains a HTTP client library.

All FLVio resources are represented by URLs. The base URL is https://mediakit.flvio.com/api/v1 and all resources are represented by paths below this.

For example, to fetch a list of all media items within your account you would create a HTTP GET request for the resource https://mediakit.flvio.com/api/v1/media . It is not a coincidence that a normal web browser can be used to fetch this resource representation. In fact, a web browser makes a practical debugging tool when working with a RESTful HTTP API. See API Debugging Tips for more information.

All resources below https://mediakit.flvio.com/api/v1 require authentication before they will be revealed. FLVio uses the simple HTTP Basic Auth mechanism for authentication. This is secure as all FLVio API requests are protected by SSL (HTTPS). The FLVio MediaKit API username/password are the same as what you use to access the Control Panel.

Web browsers support HTTP Basic Auth so if you point a web browser at https://mediakit.flvio.com/api/v1/media you should be prompted for a username and password. Enter your FLVio username/password and you should see a very plain page, containing nothing but your username.

Most FLVio resources are represented as XHTML. XHTML is a well-known XML format, making it convenient for programmers as well as users testing the API with a web browser. If you use a web browser to fetch a representation you can "View Source" to see the actual XHTML that your program would receive.

New FLVio accounts contain no media items and so the media list representation is quite bare. For an account containing media items the representation would look something like this:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head><title>Media</title></head>
<body>
 <div id="username">demo</div>
 <ul id="media">
  <li class="mediaitem" id="mediaitem_2">
   <a class="apiurl" href="media/2">API URL</a>
   <a class="asseturl" href="media/2/assets">Assets</a>
   <dl class="details">
    <dt>id</dt> <dd>2</dd>
   </dl>
  </li><li class="mediaitem" id="mediaitem_3">
   <a class="apiurl" href="media/3">API URL</a>
   <a class="asseturl" href="media/3/assets">Assets</a>
   <dl class="details">
    <dt>id</dt> <dd>3</dd>
   </dl>
  </li>
 </ul>
</body>
</html>

Why is this data represented as XHTML? A few reasons:

XHTML is valid XML with a defined schema (DTD) and so is easy to parse.
XHTML tags are more familiar to many people than a custom XML schema.
XHTML contains all the elements necessary to represent simple data structures: lists, definitions, etc.
XHTML can be rendered by web browsers, so debugging is easy.

Upload a video

To upload a video to FLVio you simply make a HTTP PUT request to the resource URL (with an identifier defined by you) with the video data in the request body.

An example request is:

PUT https://mediakit.flvio.com/api/v1/media/123

The "123" at the end of the URL is the media identifier. It is defined by you and can be any alphanumeric string. The body of the PUT request should contain the raw bytes of the video file.

As per the HTTP/1.1 standard, the request should contain a "Content-Length" header specifying the size of the request body (i.e. the video file).

We also recommend you specify the original filename with the "X-Flvio-Filename" header.

So the example becomes (including headers):

PUT https://mediakit.flvio.com/api/v1/media/123
Content-Length: 123456
X-Flvio-Filename: myvideo.mpg

This example is just pseudo code, not necessarily valid HTTP. How this is actually done with your programming language's HTTP client library will vary depending on the language and the library.

If the PUT request is successful (the HTTP response should be 201 "Created") then FLVio has accepted the video file and queued it behind the scenes to be re-encoded into Flash Video (or whatever target formats you specify - see API Ref).

How do you know when the re-encode has finished? You can poll the server for the status of a video using a HEAD request. The response of a HEAD request will contain a "X-Flvio-Status" header, set to one of "queued", "ready" or "failed". It is recommended that you poll every 60 seconds or so. Videos are usually encoded within 60 seconds, although some may take longer depending on size, quality, number of targets, etc.

For example, the response to:

HEAD https://mediakit.flvio.com/api/v1/media/123

might be:

HTTP/1.1 200 OK
Date: Thu, 28 Aug 2008 07:38:23 GMT
Server: CherryPy/3.1.0
Content-Length: 123456
Content-Disposition: attachment; filename="myvideo.mpg"
Last-Modified: Thu, 28 Aug 2008 07:38:23 GMT
Accept-Ranges: bytes
X-Flvio-Status: ready
Content-Type: video/mpeg
X-Flvio-Published: true
Keep-Alive: timeout=5, max=100
Connection: Keep-Alive

You can see from the "X-Flvio-Status" header that the status is "ready" so the video has been encoded successfully.

Video Assets

Uploaded videos are re-encoded to specified formats. By default, videos are re-encoded to Flash Video (FLV) format, optimised for playback within a web browser by Flash Player. Videos can be re-encoded to multiple formats, if required. It is common to re-encode to both FLV and H.264 formats for optimal video quality across all versions of Flash Player. See Encoding H.264 Video for more information.

Each re-encoded video format is called an "asset". An asset is produced for each "target" specified by the PUT request (only FLV by default) as well as a thumbnail image (the "thumb" asset).

To view the encoded assets for a media item make a HTTP GET request to https://mediakit.flvio.com/api/v1/media/<id>/assets

For example:

GET https://mediakit.flvio.com/api/v1/media/123/assets

This returns a representation of all assets for the media item as XHTML. An example may look like:

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head><title>Assets</title></head>
<body>
 <div id="username">demo</div>
 <div id="mediaid">123</div>
 <ul id="assets">
  <li class="asset" id="asset_thumb">
   <a class="serveurl" href="http://media.serve.flvio.com/media/mediakit/thumb/demo/123.jpg">Public URL</a>
   <dl class="details">
    <dt>name</dt>
      <dd>thumb</dd>

    <dt>type</dt>
      <dd>image</dd>
    <dt>extension</dt>
      <dd>jpg</dd>
    <dt>contenttype</dt>
      <dd>image/jpeg</dd>

    <dt>width</dt>
      <dd>534</dd>
    <dt>height</dt>
      <dd>400</dd>
   </dl>
  </li><li class="asset id="asset_flv"">
   <a class="serveurl" href="http://media.serve.flvio.com/media/mediakit/flv/demo/123.flv">Public URL</a>

   <dl class="details">
    <dt>name</dt>
      <dd>flv</dd>
    <dt>type</dt>
      <dd>video</dd>
    <dt>extension</dt>

      <dd>flv</dd>
    <dt>contenttype</dt>
      <dd>video/x-FLV</dd>
    <dt>width</dt>
      <dd>534</dd>
    <dt>height</dt>

      <dd>400</dd>
    <dt>duration</dt>
      <dd>14.55</dd>
   </dl>
  </li>
 </ul>
</body>
</html>

Each asset has an "a" tag referencing the public URL for the file.

http://media.serve.flvio.com/media/mediakit/flv/demo/123.flv

This is the URL you would use on your website to refer to the video (or thumbnail image). For example:

<img src="http://media.serve.flvio.com/media/mediakit/thumb/demo/123.jpg" alt="Thumbnail" />

More information

The API Reference contains all the gory details about the API.

See the FLVio Support section for more documentation.

If you have problems please feel free to contact us with your query.

Updated:	2008-09-03
Version:	1.0.1
Copyright:	Locayta LTD 2008. All rights reserved.