DRIVE API

Introduction

The Drive API is a REST API with JSON objects.

This documentation is structured as follows. We start with authentication and describe how your application can authenticate itself with it and then use use the returned authorization token to authorize all your calls to the API. Next we dive into the main endpoints of the API: The videos endpoint is used to upload new videos to your account, and to manage the videos you already have there, the jobs endpoint can be used to submit new jobs for encoding by providing an URL to the source video, the account endpoint is used to access and manage your whole Drive account, and finally the analytics endpoint is used to access the analytics data of your videos. Finally we describe how you can use our socket.io events to keep your application informed about the status of the ongoing encoding jobs.

Our API, while considered stable, is continually being improved and polished. Please feel free to contact support if you experience issues when integrating with the Drive API.

URL and endpoints

The URL for API requests is https://drive.api.flowplayer.org/<resource_URI>

The resource_URI is one of:

  • login
  • logout
  • videos
  • jobs
  • account

The requests to these endpoints accept JSON data as input and they return JSON data as output. For best results, you should set your HTTP Content-Type request header to application/json.

Authentication

In authentication the flowplayer.org username and password are used. These are the same credentials that are used to login to the user account in this site. You can sign up here, if you don't already have an account.

Authentication happens by calling POST /login and passing the username and password as inputs. The request returns with a user object as its return value. This object contains an authcode field that is then used to authorize all other API calls.

By default the authcode does not expire before you call POST /logout. This means that you can use the authcode without any additional calls to login to acquire a new authcode. When you are done working with the API, you should call POST /logout to invalidate the authcode.

You can also specify a time-to-live value, ttl, when you login so that the authcode automatically expires after the specified time. In this case the logout call is not necessary as you can rely that the authcode automatically stops working. The authcode remains active as you are working with the API and making calls to it -- the ttl starts counting from zero after each API call.

Login

  • method: POST /login
  • parameters: an object with username, password, and optionally 'ttl'
  • return value: a JSON object representing the authenticated user
    // to authenticate with credentials jane.doe@company.com/mypassword. Specify a time-to-live value of one hour (3600 seconds) for the authcode.
    // POST /login
    // with payload
    {
    username: 'jane.doe@company.com',
    password: 'mypassword',
    ttl: 36000
    }
     
    // response status should be 200 and the response payload is
     
    { user: {
    "id":"567890",
    "email":"jane.doe@company.com",
    "fullName":"Jane Doe",
    "alias":"JaneDoe",
    "authcode":"54ANdWY4UjK9gh1tkJLNTT2sqd5oR9c5"
    }
    }

    JavaScript

The authcode received from the login call is then used to authorize all other calls to the API. The authcode value should be set to request header flowplayer-authcode.

Login example using curl

curl -X POST --include 'https://drive.api.flowplayer.org/login' \
-H 'Content-Type: application/json'
-H 'Accept: application/json'
--data-binary '{"username":"jane.doe@company.com","password":"mypassword"}'
 
// response status should be 200 and the response payload is
 
{ user: {
"id":"10",
"email":"jane.doe@company.com",
"fullName":"Jane Doe",
"alias":"JaneDoe",
"authcode":"54ANdWY4UjK9gh1tkJLNTT2sqd5oR9c5"
}
}

Bash

Logout

  • method: POST /logout
  • "flowplayer-authcode" as request header or alternatively as request param; POST /logout?authcode=[your-authcode]
  • response status 200 indicates a successfull logout

Submitting videos

There are two ways to send videos for encoding. The jobs API provides a way to sumbit an URL to the video file. The encoder downloads the source file from the provided URL. The videos API is used when you want to upload the video using a multipart POST request.

The encoder sends events using socket.io and your application can listen to these events to stay informed on the progress of the encoding. In addition to these socket.io events, there is a callback mechanism which allows you to listen to HTTP requests that are sent when the video encoding is complete.

We have an example node.js script in Github. You can use it to submit videos to Drive, or as an example for your own implementations.

Callbacks

Both the POST /videos and POST /jobs methods allow you to specify a callbackUrl and a verifyToken which are used to implement a callback mechanism. This URL will receive a POST request when the encoding job has finished. If the job was completed successfully, a video object is sent in the payload. If the job ended with an error, an error object is sent.

verifyToken is used to verify that the callback POST request comes from Flowplayer. The verifyToken is sent as a request parameter.

When your server receives the callback, it needs to:

  • Verify the verifyToken matches the one you supplied when submitting the video for encoding. This is a security check so that your server knows the request is being made by Flowplayer.
  • Respond to the callback request with status code 200.

Example

// Submit an encoding job
 
// POST /jobs with payload
{ 'job': {
'url':'https://flowplayer-video.s3.amazonaws.com/test2.flv',
'callbackUrl': 'https://api.myvideosite.com/callback',
'verifyToken': 'ajfdolas123u509jaadf2039ran'
}
}
 
// response status should be 201 "Created", and the job was sent for encoding
// when the encoding job successfully completes I will receive a POST request in URL
// https://api.myvideosite.com/callback?verifyToken=ajfdolas123u509jaadf2039ran
// I verify that verifyToken matches the one I submitted with POST /jobs,
// and I send HTTP status 200 as response.
// The payload of this callback is
 
{
video: {
id: 123,
// all other video attributes, and embedded encodings
}
}
 
// if the encoding job failed, the payload looks like
 
{
error: {
id: 123, // the video ID
description: 'Encoding failed'
}
}

JavaScript

Jobs

The Jobs API is used to submit encoding jobs. Drive's encoder downloads the source video using the the provided URL. Alternatively the Videos API can by used to create encoding jobs using multipart upload requests.

Posting an encoding job

  • method: POST /jobs
  • parameters: JSON job data, see contents below
  • return value: object representing the submitted job

Input parameters are as follows:

fielddefaultdescription
callbackUrlNoneThe URL that will receive a POST request when the encoding job has finished. This callback gets called when the job was successfully completed or finished in an error.
watermarked falseSpecifies whether a Flowplayer watermarked video will be created.
mode'standard'The encoding profile to be used. One of 'standard', 'adaptive', 'premium'.
multiresfalseDEPRECATED, use mode.
notifytrueIf true, send a notification email when the transcoding job has been completed.
publictrueSpecifies whether a public or private video will be created. Private videos are not available for streaming before they are made public.
tagsNoneList of tags to be added for this video. For example ['promo', 'summer', 'sunny']. Tags will be created if the specified tag names are new existing tags don't exist for them.
titleNoneThe title for this video. If not specified, the title will be based on the filename of the source video.
urlNoneThe URL of the video file. The transcoder downloads the source from this location.
verifyTokenNoneA verification token to be sent back in the callback.

Example

// POST /jobs
// with authcode specified in request header 'flowplayer-authcode'
// with following payload:
 
{ 'job': {
'url':'https://flowplayer-video.s3.amazonaws.com/test2.flv',
'notify': false,
'tags': ['promo', 'summer', 'sunny']
}
}
 
// response status should be 201 "Created" and the response payload is
 
{
"job": {
"watermarked": false,
"title": "test2.flv",
"public": true,
"userId": "3",
"notify": false,
"filename": "test2.flv",
"created": "2015-02-11T13:23:57.468Z",
"libraryId": 41,
"id": 51,
"url": "https://flowplayer-video.s3.amazonaws.com/test2.flv"
}
}

JavaScript

Re-encoding

Re-encoding can be used to change the video's encoding profile and to remove or add the Flowplayer watermark. Watermarked videos have a cheaper streaming price.

This method sends the video for re-encoding. Encoding status events are emitted via socket.io.

  • Method: POST /jobs
  • Parameters: a job object with fields mode and optionally watermarked: true

Example

// Re-encode the video using the adaptive profile
// POST /jobs
// with payload
{
job: {
id: 60,
mode: 'adaptive'
}
}
 
// response status code should be 202 'accepted'

JavaScript

Videos

The videos endpoint is used for uploading videos to Drive and for managing its videos.

Video attributes

The following table lists the attributes of the video object, returned by list/show methods.

fielddescription
bytesThe amount in bytes this video has been streamed.
createdThe creation timestamp for this video.
failed(boolean) If true the transcoding of this video failed.
filenameName of the source file.
watermarked(boolean) If true, this is a Flowplayer watermarked video.
hlsResolutionsNumber of HLS target resolutions this video was encoded to.
idThe unique identifier of this video.
modifiedThe modification timestamp.
public(boolean) If true, this is a public video that is available for playback. If false, this is private.
secondsAmount in seconds this video has been viewed in total.
signedUrlA signed URL that can be used the fetch the source file of this video. This URL expires in 60 minutes. This field is only present in the video object returned by GET /videos/:id
snapshotUrlURL of the snapshot image.
tagsTags (list) associated with this video. For example:
[{"id":296,"tag":{"id":270,"name":"summer"}},
{"id":297,"tag":{"id":271,"name":"sunshine"}}]
.
thumbnailUrlURL of the thumbnail image.
titleThe title of this video.
userIdA unique identifier of the Flowplayer user owning this video.
viewCountCurrThe view count for the current subscription period.
viewCountInvoiced The total view count that has been invoiced in previous periods. The overall total view count is viewCountCurr + viewCountInvoiced.
vodResolutionsNumber of VOD (non HLS) resolutions this video has been encoded to.
encodingsList of encodings this video has, one for each format/resolution. See below for details.

Encoding attributes

Each video has a number of encodings.

  • One encoding for the source file. This can be identified by its status value 'original'
  • One encoding for the HLS manifest file, if the video was encoded to multiple resolutions.
  • One mp4 encoding for each resolution the video was encoded to.

The attributes of the encoding object are shown in the table below.

fielddescription
audioBitrateThe bitrate of the audio track.
audiochannels Number of audio channels.
audioCodecThe audio codec name (aac, vorbis)
bitRateThe total bitrate of this encoding.
createdThe creation timestamp of this encoding.
durationDuration in seconds.
filenameThe name of the encoded file.
filesizeThe size of the encoded file, in bytes.
finishedTimestamp when the transcoder completed this encoding.
formatVideo format, one of 'mp4' or 'hls'
heightHeight in pixels.
idThe unique id of this encoding.
modifiedModified timestamp.
posPosition number.
startedTimestamp when the transcoder started processing this encoding.
statusStatus of this encoding, one of 'original', 'pending', 'preparing', 'encoding', 'completing', 'done', 'aborted', 'debranding'. Status is 'done' if this encoding is ready for playback.
Note: Each video has one encoding with status 'original' corresponding to the original source file.
urlThe URL of the file. Typically configured to the video player for playback. With encoding objects sent with events the URL is not available before the encoding has been completed and the 'done' event is sent.
videoBitrateThe bitrate of the video track.
videoCodecVideo codec name (h264, vp8)
videoIdThe unique identifier of the associated video.
widthWidth in pixels.

Uploading

  • method: POST /videos
  • parameters: a form with the file to upload, and form fields as shown below
  • return value: object representing the submitted video

Form fields:

fielddefaultdescription
fileNoneThe file to upload.
notifytrueIf true send a notification email when the transcoding job has been completed.
watermarked falseSpecifies whether a watermarked video will be created.
mode'standard'The encoding profile to be used. One of 'standard', 'adaptive', 'premium'.
multiresfalseDEPRECATED, use mode.
tagsNoneList of tags to be added for this video. For example:
['promo', 'summer', 'sunny']
Tags will be created if the specified tag names are new and existing tags don't yet exist for them.
titlethe value is based on the filename of the source videoThe title for this video.

Example using curl

curl -X POST --include 'https://drive.api.flowplayer.org/videos' \
-H 'flowplayer-authcode: <required>' \
-F 'file=@/Users/kalle/videos/myvideo.mp4' \
-F 'title=My first promo video'
 

// response status should be 201 "Created" and the response payload is
 
{
"video": {
"userId":"3",
"id":5,
"title":"My cool video",
"filename":"5-s-test.flv"
}
}

Bash

Show

  • method: GET /videos/:id
  • return value: JSON video object, with embedded encodings

Example

// GET /videos/54
// response status should be 200 and the returned payload is
 
{ "video": {
"id": 54,
"userId": 3,
"title": "buffalo_soldiers.mp4",
"filename": null,
"snapshotUrl": "https://drive.cdn.flowplayer.org/3/54-snap.jpg",
"thumbnailUrl": "https://drive.cdn.flowplayer.org/3/54-thumb.jpg",
"public": 1,
"watermarked": 0,
"failed": 0,
"viewCountInvoiced": 0,
"viewCountCurr": 0,
"bytes": 0,
"seconds": 0,
"tags": [],
"hlsResolutions": null,
"vodResolutions": 1,
"viewCount": 0,
"modified": "0000-00-00 00:00:00",
"created": "2015-03-02 12:23:08"
"encodings": [
{
"id": 115,
"pos": 0,
"filename": "49879-Dosate.mp4",
"url": null,
"width": 1920,
"height": 1080,
"videoBitrate": 1552343,
"audioBitrate": 131138,
"bitRate": 1687460,
"format": "mp4",
"filesize": 23408442,
"audiochannels": 2,
"duration": 5400,
"videoCodec": "h264",
"audioCodec": "aac",
"started": "0000-00-00 00:00:00",
"finished": "0000-00-00 00:00:00",
"modified": "0000-00-00 00:00:00",
"created": "2015-03-02 12:23:08"
"status": "original"
},
{
"id": 115,
"pos": 1,
"filename": "49879-Dosate.mp4",
"url": "https://drive.flowplayer.org/175011/49879-Dosate.mp4",
"width": 640,
"height": 360,
"videoBitrate": 232369,
"audioBitrate": 64032,
"bitRate": 301102,
"format": "mp4",
"filesize": 4179485,
"audiochannels": 2,
"duration": 5400,
"videoCodec": "h264",
"audioCodec": "aac",
"started": "2015-03-02 12:29:17",
"finished": "2015-03-02 12:31:50",
"modified": "0000-00-00 00:00:00",
"created": "2015-03-02 12:23:08"
"status": "done"
}
]
}
}

JavaScript

List

  • method: GET /videos
  • parameters:
    • tags: List of tags to be used for searching. Tag values need to match exactly in order to be included in the results.
    • search: List of video title search values. Videos whose title matches any of the these search values will be returned.
    • page: Used for paging the returned data. 30 videos are returned per page. All videos are returned if not specified.
  • return value: JSON array with all videos currently stored in the account

Example

// To get videos that have have tag 'promo' or tag 'first' (or both)
// GET /videos?tags=promo%2Cfirst
// response status should be 200 and the response payload is
 
{ "videos": [
{
"id": 54,
"userId": 3,
"title": "buffalo_soldiers.mp4",
"filename": null,
"snapshotUrl": "https://drive.cdn.flowplayer.org/3/54-snap.jpg",
"thumbnailUrl": "https://drive.cdn.flowplayer.org/3/54-thumb.jpg",
"public": 1,
"watermarked": 1,
"failed": 0,
"viewCountInvoiced": 0,
"viewCountCurr": 0,
"bytes": 0,
"seconds": 0,
"tags": [{"id":296,"tag":{"id":270,"name":"promo"}},{"id":297,"tag":{"id":271,"name":"winter"}}],
"hlsResolutions": null,
"vodResolutions": 1,
"viewCount": 0,
"modified": "0000-00-00 00:00:00",
"created": "2015-03-02 12:23:08"
"encodings": [
{
"id": 115,
"pos": 0,
"filename": "49879-Dosate.mp4",
"url": null,
"width": 1920,
"height": 1080,
"videoBitrate": 1552343,
"audioBitrate": 131138,
"bitRate": 1687460,
"format": "mp4",
"filesize": 23408442,
"audiochannels": 2,
"duration": 5400,
"videoCodec": "h264",
"audioCodec": "aac",
"started": "0000-00-00 00:00:00",
"finished": "0000-00-00 00:00:00",
"modified": "0000-00-00 00:00:00",
"created": "2015-03-02 12:23:08"
"status": "original"
},
{
"id": 115,
"pos": 1,
"filename": "49879-Dosate.mp4",
"url": "https://drive.flowplayer.org/175011/49879-Dosate.mp4",
"width": 640,
"height": 360,
"videoBitrate": 232369,
"audioBitrate": 64032,
"bitRate": 301102,
"format": "mp4",
"filesize": 4179485,
"audiochannels": 2,
"duration": 5400,
"videoCodec": "h264",
"audioCodec": "aac",
"started": "2015-03-02 12:29:17",
"finished": "2015-03-02 12:31:50",
"modified": "0000-00-00 00:00:00",
"created": "2015-03-02 12:23:08"
"status": "done"
}
]
}
// Rest of the video objects omitted.
// All videos in the user's drive account are returned in
] }

JavaScript

Update

You can update the title and tags tags of videos.

  • Method: PUT /videos/:id

Example

// To update the tags and the title of video 60. 
// PUT /videos/60
// with payload
 
{
video: {
title: 'High speed downhill'
}
}
 
// response status code should be 200

JavaScript

Publish and unpublish

A video can be public or private. Public videos are available for playback and download, while private videos are not.

After calling this method, it can take a while when the videos are invalidated in the CDN. For example, after making the videos private, the videos can still play for a few minutes as the files are still temporarily available in the CDN, but once the invalidation is complete the new visibility is propagated to all CDN edge locations and access is prevented.

  • Method: PUT /videos/:id
  • Parameters: a video object with a 'public' field specifying the visibility value as a boolean

Example

// To make a video with id 60 private
// PUT /videos/60
// with payload
 
{
video: {
public: false
}
}
 
// response status code should be 200

JavaScript

Deletion

  • Method: DELETE /videos/:id

Example

// To delete the video with id 60
// DELETE /videos/60
 
// response status code should be 204 and the video is gone

JavaScript

Tag management

Tags are used to categorize videos. This is especially useful when you have a large amount of videos in your account.

This section describes the methods available for tag management. These methods work with tags that may or may not be associated with videos in the account. The methods work globally inside the account. There is a separate set of methods that is used to associate these tags to videos and to manipulate the tags associated with videos.

List tags

  • Method: GET /tags
    // To get all tags in this account. The returned tags may or may not be associated to videos.
    // GET /tags
     
    // response status code should be 200 and the return value is
    {
    tags: [
    {"id":273,"name":"arts"},{"id":277,"name":"fashion"},
    {"id":275,"name":"misc"},{"id":276,"name":"portrait"},
    {"id":272,"name":"promo"},{"id":274,"name":"winter"}
    ]
    }

    JavaScript

Show tag

  • Method: GET /tags/:id
    // To show tag with id 602
    // GET /tags/602
     
    // response status should be 200 and the response body contains the tag
    { tag: { id: 602, name: 'crazycanucks' } }

    JavaScript

Create tag

  • Method: POST /tags
  • Parameters: the tag to create
    // To create a tag with name 'newtag'
    // POST /tags
    // with payload
    { tag: { name: 'newtag5' } }
     
    // response status should be 201 and the return value in the response body is the created tag
    { tag: { id: 602, name: 'newtag5' } }

    JavaScript

Update tag

  • Method: PUT /tags/:id
  • Parameters: the tag with the updated name
    // To update tag 602 to have name 'crazycanucks'
    // PUT /tags/602
    // with payload
    { tag: { name: 'crazycanucks' } }
     
    // response status should be 200 and the response body contains the updated tag
    { tag: { id: 602, name: 'crazycanucks' } }

    JavaScript

Delete tag

  • Method: DELETE /tags/:id
    // To delete tag with id 602
    // DELETE /tags/602
     
    // response status should be 204 and the tag is deleted
    // and no longer associated with any videos

    JavaScript

Tagging videos

This section describes how to tag videos and how to remove tags from videos.

You can also specify tags when uploading videos and when posting them as encoding jobs. You can use tags when searching videos.

List video's tags

  • Method: GET /videos/:id/tags
    // To list tags associated with video 7137
    // GET /videos/7137/tags
     
    // response status code should be 200 and the return value is
     
    {
    "tags":[
    {"id":319,"tag":{"id":285,"name":"promo"}},
    {"id":320,"tag":{"id":289,"name":"portrait"}}
    ]
    }
     
    // one tag looks like this
    {"id":319,"tag":{"id":285,"name":"promo"}}
     
    // the first id identifies the association
    // and the second id is the tag's global id

    JavaScript

Tag a video

  • Method: POST /videos/:id/tags
  • Parameters: the tags to associate to the video. You can pass several tags at once.
    // To tag video 602 with 'swedishblonde' and 'vodka'
    // You can use either the tag name or tag id in the tags.
    // Here we pass tag names.
     
    // POST /videos/602/tags
    // with payload
    { tags: [{ name: 'swedishblonde' }, { name: 'vodka' }] }
     
    // response status should be 201 and
    // the return value in the response body contains the created tags
     
    {
    "tags":[
    {"id":329,"videoId":602,"tag":{"name":"swedishblonde","id":297}},
    {"id":330,"videoId":602,"tag":{"name":"vodka","id":298}}
    ]
    }
     
    // In the returned tags the first id identifies the association
    // and the second id is the tag's global id.
    // Use the association id to delete the tag from the video, see below.

    JavaScript

Delete a tag from video

  • Method DELETE /videos/:id/tags/:id
    // To remove tag 405 from video 602
    // DELETE /videos/602/tags/405
     
    // response status should be 204
    // and the tag is no longer associated with the specified video

    JavaScript

Account

Account attributes

The following table lists the attributes of the account object, returned by list/show methods.

fielddescription
idThe account's unique identifier.
userIdThe account owner's unique identifier.
bytesThe accumulated paid streaming amount in bytes for the currect subscription period. This is reset to zero monthly when the subsription period renews.
secondsThe accumulated paid streaming seconds for the currect subscription period. This is reset to zero monthly when the subsription period renews.
planOne of 'subscription' (economy), 'pro', 'enterprise', 'payAsYouGo'
statusThe status of the account. One of 'active', 'canceled', 'unpaid'. If 'unpaid' the latest renewal payment failed.
modifiedModification timestamp.
createdCreation timestamp.
discountSecondsThe accumulated discounted streaming seconds for the currect period. This is reset to zero monthly. Discounted streaming is the result of streaming watermarked videos.
discountBytesThe accumulated discounted streaming amount in bytes for the currect period. This is reset to zero monthly.
reportingPeriodthe interval used for sending report emails. One of 'none', 'day', 'week', 'month'. If 'none' report emails will not be sent.
invoicedTimestampTimestamp of the latest successful subscription renewal.
usageEmailTimestamp Timestamp when the latest usage report email was sent.
videosEmbedded list of video objects this account holds.
Note: This is returned only if you specify an additional videos=true request parameter.

Reactivate

Reactivation means making a canceled or suspended account active again. Reactivation has the followign effects:

  • The outstanding balance and the normal price for a single period will be charged
  • The balance will be reset to $0
  • The account will be immediately activated
  • The billing date will be reset to today

Note that with reactivation you can only have the 'status' field passed in the payload to be updated. If other fields are passed they will be ignored and not updated.

  • Method: PUT /account
  • Parameters: account object with status: 'active'

Example

// To activate the account
// PUT /account
// with payload
 
{
account: {
status: 'active'
}
}
 
// response status code should be 200 'OK'

JavaScript

Update

The following account email settings can be updated:

fielddescription
emailThe email address associated with the account.
reportingPeriodthe interval used for sending report emails. One of 'none', 'day', 'week', 'month'. If 'none' report emails will not be sent.
  • Method: PUT /account
  • Parameters: account object with fields to be updated

Example

// To update account's email settings
// PUT /account
// with payload
 
{
"account": {
"email": "bob@videopromotion.com",
"quotaEmails": true,
"reportingPeriod": 'week'
}
}
 
// response status code should be 200 'OK'

JavaScript

Show

  • Method: GET /account/:id
  • Return value: the account object corresponsing to the specified ID

Examples

// To show my account (the one i'm currently logged in with this API)
// GET /account/19
 
// response status code should be 200 'OK' and the response body is
 
{
"account": {
"id": 19,
"userId": 3,
"bytes": 123875418,
"seconds": 21345,
"discountBytes": 0,
"discountSeconds": 0,
"plan": "pro",
"status": "active",
"reportingPeriod": "week",
"quotaEmails": 1,
"periodEnds": "2015-04-10T21:00:00.000Z",
"usageEmailTimestamp": "2015-04-01T21:00:00.000Z",
"invoicedTimestamp": "2015-04-12T21:00:00.000Z",
"modified": "0000-00-00 00:00:00",
"created": "2015-03-11T08:23:31.000Z",
"videoCount": 23,
"taxable": false,
"rtmpUrl": "rtmp://rtmp.dev.flowplayer.org/cfx/st/"
}
}

JavaScript

// To show my account together with its videos
// GET /account?videos=true
 
// response status code should be 200 'OK' and the response body is
 
{
"account": {
"id": 19,
"userId": 3,
"bytes": 123875418,
"seconds": 21345,
"discountBytes": 0,
"discountSeconds": 0,
"plan": "pro",
"status": "active",
"reportingPeriod": "week",
"quotaEmails": 1,
"periodEnds": "2015-04-10T21:00:00.000Z",
"usageEmailTimestamp": "2015-04-01T21:00:00.000Z",
"invoicedTimestamp": "2015-04-12T21:00:00.000Z",
"modified": "0000-00-00 00:00:00",
"created": "2015-03-11T08:23:31.000Z",
"videoCount": 23,
"taxable": false,
"rtmpUrl": "rtmp://rtmp.dev.flowplayer.org/cfx/st/"
"videos": [
// list of account's video objects
]
}
}

JavaScript

Analytics

Traffic

You can query traffic data of your videos. The data can be queried for the whole account and for individual videos.

  • methods: GET /videos/:id/traffic and GET /account/traffic
  • parameters: query parameters as listed below
  • return value: a list of objects with 2 fields: time and value

You can use following query parameters:

iddefaultdescription
startNoneOptional start value of the time range. Format yyyy-mm-dd, for example: 2013-01-01. Default value is dependent on the specified grouping.
endyesterday Optional end value of the time range. Format yyyy-mm-dd.
grouping dayOne of hour, day, week, month. Specifies the granularity of the results. For example: in a day grouping one value is returned for each day of the time range. In a hour grouping one value is returned for every hour.
typeviewsEither views or bytes. Specifies if the results should be view counts or bytes.

Example

// To get traffic data for video with ID 25
// GET /videos/25/traffic?start=2014-03-21&end=2014-03-23&grouping=day&type=views
 
// Status code should be 200 and the returned data should be a list of time/value pairs.
// The values will be view counts as we requested that with the type parameter.
 
{ traffic:
[
{
"value": 200000,
"time": "2014-03-21T11:20:02.000Z"
},
{
"value": 387123649,
"time": "2014-03-21T12:10:02.000Z"
},
{`
"value": 81328745,
"time": "2014-03-21T14:40:02.000Z"
},
{
"value": 2346115,
"time": "2014-03-21T07:10:02.000Z"
},
{
"value": 12156,
"time": "2014-03-23T09:10:02.000Z"
}
]
}

JavaScript

Retention

Retention data answers following questions: How long do viewers spend watching your videos? At what point do they lose interest or tune out and go elsewhere? The returned data tells the percentage (and count) of viewers that watched the video up to a given time in the video's timeline, see the example below to get the idea.

  • method: GET /videos/:id/retention
  • return value: a list of objects for every second in the video timeline, see below for details

The returned retention data is a list of objects with following fields:

iddescription
secondsThe time of the data point in seconds.
percentageThe percentage of viewers that watched the video up to this time.
countTotal count of viewers that watched the video up to this time.

Example

// To get retention data for video 25
// GET /videos/25/retention
 
// the status could be 200 and the returned data looks like the following
 
{
retention: [
{
"seconds": 0,
"percentage": 99.41,
"count": 747
},
{
"seconds": 1,
"percentage": 98.47,
"count": 735
},
{
"seconds": 2,
"percentage": 97.08,
"count": 701
},
{
"seconds": 3,
"percentage": 95.37,
"count": 690
},
{
"seconds": 4,
"percentage": 95.16,
"count": 687
},
...
{
"seconds": 15,
"percentage": 67.01,
"count": 440
},
...
]
}

JavaScript

Events

You can receive status events via socket.io at different points as the encoding job is processed. These events are fired after you have posted a new video for encoding either by using the videos endpoint or to the jobs endpoint.

Example

This example demonstrates how to establish a socket.io connection and then receive events from the Drive API.

<script src="/socket.io/socket.io.js"></script>
<script>
 
// First establish a connection. We send the flowplayer-authcode we received when authenticating.
var socket = io.connect('https://drive.api.flowplayer.org', { query: "flowplayer-authcode=" + user.authcode });
socket.on("connect", function() {
console.log("connected");
});
socket.on("disconnect", function() {
console.log("disconnected");
});

// handle encoding events, like 'begin', 'done', 'completed'
socket.on('begin', function (data) {
console.log('encoding started for job ' + data.id);
});
</script>

JavaScript

begin

The 'begin' event is emitted when video upload sent with the videos endpoint has completed uploading and the job is sent to encoders. It's also sent when a video encoding job submitted with the jobs endpoint has been received and begins processing.

The following data is sent with 'begin':

fielddescription
watermarked(boolean) true if this event is for a watermarked video.
idThe unique id for the video.
public(boolean) true if the video will be made public when encoding finishes.
titleThe title of the encoded video.
urlThe URL of the source video.

snap

The 'snap' event is emitted when the thumbnail and snapshot images have been extracted from the source video file. Along with the event a metadata object is sent. The object is filled with metadata extracted from the source file, including snapshotUrl, thumbnailUrl which you can use to display a cover image for the video.

The data submitted with the 'snap' event has the properties listed below.

fielddescription
audioBitrateThe bitrate of the audio track.
audioCodecName of the audio codec (aac, mp3)
audioStartTimeThe time in seconds when the audio track starts.
audiochannelsNumber of audio channels.
bitRateTotal bitrate.
durationTotal duration in seconds.
filenameThe name of the source file.
filesizeThe size of the source file in bytes.
formatThe format of the source file, for example: 'mp4', 'avi', 'mov', 'mpg'.
heightHeight in pixels.
idUnique identifier of the video.
percentageAn approximate completion percentage of this encoding job.
snapshotUrlURL of the snapshot image.
thumbnailUrlURL of the thumbnail image.
videoBitrateThe bitrate of the video track.
videoCodecName of the video codec (h264, vp8).
widthWidth in pixels.

status

The 'status' events are sent multiple times as the transcoding of the video progresses. The event object has following properties:

fielddescription
descriptionDescribes the status of the encoding job, for example: "Encoding mp4-216p first pass"
idThe unique identifier of the video being encoded.
percentage An approximate completion percentage of this encoding job. Can be used, for example, to implement a progress bar.

meta

The 'meta' event is sent for each target encoding when the target file as been completed but not yet uploaded to storage. The object sent along with this event contains an encoding object with metadata extracted from the encoded file.

done

The 'done' event is sent for each target encoding when the corresponding file has been uploaded to storage and is ready for playback. The object sent along with this event contains an encoding object for the encoded result file.

defaultCompleted

The 'defaultCompleted' event is emitted when the video's default resolution is ready. The default resolution is 360 pixels in height and contains one encoding in the MP4 format.

For single resolution videos only the default resolutio is encoded.

The payload of this event is a video object containing three encoding objects: the original (corresponding to the source file), and mp4 (encoded target). Example usage scenario: The Flowplayer Drive UI enables preview playback when it receives this event.

completed

The 'completed' event is emitted when the video encoding is complete and the video is ready for playback.

For single resolution videos this event is emitted immediately after the 'defaultCompleted' event. For multiple resolution videos it is emitted when the additional resolutions and HLS encoding have been completed.

The payload of this event is a video object containing all the target encodings in 'done' state, plus one encoding with state 'original' corresponding to the source file.

error

The 'error' event gets emitted if an error happens when processing the video. It has following fields:

iddescription
idThe unique identifier of the video being encoded.
messageA descriptive error message.
detailA more detailed error description.

Examples

Here are two example implementations which may already fulfill your needs or inspire you: