FLVio MediaKit - Quick Start

Overview

This document covers the basics of using the API to upload, inspect, and serve a video using the FLVio MediaKit, from a language-agnostic point of view, using plain text examples of what is transmitted to and from the server.

Note:

The FLVio MediaKit uses an SSL certificate for HTTPS encryption. As such, the examples in this document represent the data transmitted before and after encryption is applied. Most programming languages provide libraries for SSL encryption and HTTPS communication.

Step 2: Generate an ID for your video

FLVio refers to your videos using unique IDs. IDs can be any alphanumeric string, for example a reference to a Primary Key in some Videos table of a database, a GUID generated per video, or an MD5 hash of the video's content. IDs are specific to your account, so you don't need to worry about stamping over someone else's videos.

Step 3: Upload the video to the MediaKit

FLVio accepts videos uploaded using HTTP PUT, using HTTP Basic Authentication. There are numerous options for uploading, which are specified as HTTP Headers, and are covered in full detail in the API Reference.

To upload a video, you perform an HTTP PUT request to the API URL for the Media Item you want to create, eg:

https://mediakit.flvio.com/api/v1/media/UNIQUE_ID

A basic upload request will therefore look like this:

PUT https://mediakit.flvio.com/api/v1/media/UNIQUE_ID HTTP/1.0
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Length: 34358670
X-Flvio-Filename: my_video.mpg

[video data]

Notes:

The UNIQUE_ID in this example is the ID you generated for the video in the previous step.
The Authorization header should use an appropriate HTTP Basic Authentication token, generated using your API username and password. How to do this is beyond the scope of this document, but most languages have a facility to do this.
The Content-Length header must be provided. It should be the file size of your video in bytes. Again, most languages' HTTP libraries will generate this automatically.
The X-Flvio-Filename header is used to tell FLVio MediaKit the filename of your video. This is useful to assist the MediaKit in detecting the video format.

The MediaKit should respond with a response code of 201 ("Created"). At this point the video is queued to be converted.

Step 4: Inspect your media

You can easily view all your Media Items in a web browser by entering the following location:

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

The browser will prompt you for your username and password and use these to authenticate with the MediaKit. A basic XHTML page will be returned to you. You will see a list of all your uploaded videos on this page, and if you view the source of this page, it will 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" lang="en" xml:lang="en">
<head><title>Media</title></head>
<body>
 <div id="username">nick</div>
 <ul id="media">
  <li class="mediaitem" id="mediaitem_UNIQUE_ID">
   <a class="apiurl" href="1">API URL</a>
   <a class="asseturl" href="1/assets">Assets</a>
   <dl class="details">
    <dt>id</dt> <dd>1</dd>
   </dl>
  </li>
 </ul>
</body>

This page can be processed using an XML or XHTML parser by your application if you need a list of videos currently uploaded.

Note:

The id attribute of each li element is prefixed with "mediaitem_" to ensure that the markup conforms to XHTML standards, which specify that id attributes must begin with a letter. If you are processing it, you should remove this prefix to get your video's unique ID.

You will notice two links for each Media Item: "API URL" and "Assets".

API URL

The API URL is the URL you uploaded your video to, using HTTP PUT. You can also retrieve your original video using HTTP GET on this URL:

GET https://mediakit.flvio.com/api/v1/media/UNIQUE_ID HTTP/1.0
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

The server will respond:

HTTP/1.1 200 OK
Date: Thu, 04 Sep 2008 16:30:05 GMT
Server: CherryPy/3.1.0
Content-Length: 34358670
Content-Disposition: attachment; filename="my_video.mpg"
Last-Modified: Thu, 04 Sep 2008 16:30:06 GMT
Accept-Ranges: bytes
X-Flvio-Status: ready
Content-Type: video/x-msvideo
X-Flvio-Published: true
Connection: close

[your video's content]

You can also use the HTTP HEAD method to retrieve only the headers for the Media Item. This is useful for checking if the video has been converted (the X-Flvio-Status header), and whether or not its assets are published (publicly available). For more information on these headers, please refer to the full API Reference.

After transferring a video to FLVio your application may poll the API to determine when the video has been encoded and is ready for playback. Polling the media URL with a HEAD request, every few minutes, is a typical strategy. The X-Flvio-Status header will indicate whether the video is ready (or, alternatively, has failed encoding).

Assets

If you follow the link to a Media Item's assets, you will get another simple XHTML page detailing which assets are associated with your video. By default when you upload a video, two assets are generated:

The 'thumb' asset is generated with a thumbnail of the first frame of your video

The 'flv' asset is the Flash Video format of your video.

Notes:

You can request other assets (video formats) to be generated using the upload API. See the full API Reference for more information.
If your video has not been converted yet, this page will give a 404 status.

Each asset also has a definition list of attributes for the asset. For example, the thumb asset has width and height attributes.

You will also notice that each asset has a public URL link associated with each one. This is the URL that you can embed on your website (eg, in an image or video player), and does not require your authentication details to access.

Further Resources

The MediaKit Getting Started Guide gives a more formal introduction to the FLVio MediaKit API and the principles used, such as REST.

The full API Reference details the full specification of the API, including deleting and replacing videos, converting to formats other than FLV, and changing the dimensions of the encoded assets.

Updated:	2008-09-19
Version:	1.0
Copyright:	Locayta Ltd 2008. All rights reserved.