VMS API Guide

1.1 Introduction

The Blue Billywig Video Management System (VMS) has got a RESTFUL API, which makes it possible to access and manage various functionality and data as available within the platform.

The full Blue Billywig VMS technically consists of:

  • Audio/video playout infrastructure
  • Multimedia asset management system
  • Apache Solr supported search engine backend
  • OpenX supported integrated ad management backend
  • Content management integration components and widgets
  • Format Engine (for video post-processing and transcoding)

This manual provides technical information concerning the Blue Billywig VMS API and is roughly divided into the following functional layers:

  • Public API: read-only access interface, used to access playout-, mediaclip-data and more.
  • Private API: read/write acces interface, used to fully manage data and functionality within the platform.
  • Authentication/authorisation mechanism: As used and needed for accessing the private API functionality.

1.2 More information

This manual provides technical information concerning the Blue Billywig VMS API, on our support website you can also find other manuals, which provide more information on for example the subject; VMS interface, player functionailty or RPC.<br/> If you need more information than documented, please contact support.

Note: Take a look into the VMS RPC manual, the RPC can be very useful for use of the Blue Billywig VMS API.

Entities and data types

The BB VMS consists of various API-manageable entities and data types. In the following paragraphs these are listed and provided with a brief description. More inside information can be found in the Public API and Private API chapters.

Entities are components within the platform which can consist of data and functionality. The available entities are listed below:

Entity Description
Publication Manage and access publication global data and functionality.
Mediaclip Manage and access mediaclip data
Mediacliplist Manage and access mediacliplist data
Playout Manage and access playout configurations
Player Access player configurations
Campaign Manage and access commercial campaigns
Language Manage and access language data as configured in the publication
Subtitle Manage and access subtitle data as linked to a mediaclip
User Manage and access user configurations

Publication

The publication is the VMS root entity. By default all API actions will be filtered to only show and be able to modify content that belongs to the current publication context.

For example: When an application uses the API entrance http://bb.bbvms.com/api/mediaclip, the only content that will be shown and can be modified is content owned by the "bb" publication.

Mediaclip

A mediaclip is a typical content item and container for all media references and metadata of one item within the VMS. It's comparable to an article within a content management system (CMS). In the next paragraphs the mediaclip XML representation is explained divided in sections.

Note: Besides the XML format the mediaclip entity can also be retrieved in JSON format. More on this can be found in the public and private API chapters.

The header contains the most essential information. Below the XML of the header is shown and all attributes are described.

[xml]
<media-clip mediatype="video" usetype="editorial" 
            sourcetype="on_demand" id="2119581"
            userid="148" originalfilename="Bluebillywig Branded - Final-4. H.264 1080p.mov"
            sourceid="" status="published" length="168" src="/bb/media/2013/02/15/2119581.mov"
            url="http://bb.bbvms.com/mediaclip/2119581.xml" 
            title="Blue Billywig Strategic Online Video">

Header attributes

Key Type Description
mediatype string The mediatype of the mediaclip, see the media types paragraph for more information.
usetype string The use type of a mediaclip, see the use types paragraph for more information.
sourcetype string The sourcetype attribute respresents the way the mediaclip is broadcasted. Possible values are "on_demand" or "live"
id int The mediaclipid, the unique identifier for a mediaclip within the VMS.
userid int Userid of the user who created the mediaclip.
originalfilename string The original filename as provided/uploaded to the VMS
sourceid string A sourceid makes is possible to set an identifier from for example asset management system (optional).
status string The status attribute can contain two different statuses: "published" meaning the item is public and "draft", meaning the item is not publicly available.
length string The length of the media (video/audio) in seconds.
src string The location of the source-file/video
url string The location of the metadata XML of the mediaclip
title string The title of the mediaclip

The header is followed by the date marks:

[xml]
<date published="Fri, 15 Feb 2013 14:04:47 +0100" 
      created="Fri, 15 Feb 2013 13:57:20 +0100"           modified="Tue, 30 Jul 2013 17:26:53 +0200"
      embargofrom="Thu, 15 Feb 2013 00:00:00 +0200"
        embargoto="Sat, 15 Feb 2014 00:00:00 +0200"/>

Date attributes

Key Type Description
published date Represents the date and time the mediaclip was first published. This date isn't altered, when the mediaclip was unpublished and will be republished again.
created date Represents the date and time the mediaclip is created.
modfied date Represents the date and time the mediaclip was modfied.
embargofrom date If an embargo is set, this represents the date and time from which the mediaclip is publicy available.
embargoto date If an embargo is set, this represents the date and time until which the mediaclip is publicy available.

The date is followed by multiple fields containing more information about the content of the item.

[xml]
 <description>
     Video will become the most important content in the worldwide media consumption. Blue         Billywig enables organisations to get the most out of their video.
 </description>
 <author>Blue Billywig</author>
 <copyright>Blue Billywig</copyright>
 <deeplink url="http://www.bluebillywig.com"/>
 <location>51.69162816088143,5.414062499999952</location>
 <categorization>
     <category-tree type="keywords">
         <category name="Blue Billywig"/>
         <category name="Video Management System"/>
         </category-tree>
</categorization>

Metadata fields

Field Type Description
description string Contains a brief description about the content.
author string Can hold the author of the content.
copyright string Can hold the copyrighter of the content.
deeplink string Can hold the url to the page on where the mediaclip is embed.
location mixed Can hold latitude and longitude of the location where the item was recorded or related to.

Next the exports could be listed if there where any exports to for example Youtube or Facebook.

[xml]
<exports totalviews="0">
    <exportitem id="70460" prio="" createddate="Fri, 15 Feb 2013 14:54:09 +0100"                     updateddate="Fri, 15 Feb 2013 14:54:09 +0100" publisheddate="" status="exported"                     message="" externalid="" externalviews="0">
        <exportchannel id="235" name="BBFBpage" exportsystemid="3" exportsystemname="Facebook"                     authtokenid="178" status="active">
            <fieldset name="config">
                <field name="fbpagename">Blue Billywig</field>
                <field name="fbpageid">266122176736872</field>
                <field name="playout">VidCompare</field>
            </fieldset>
        </exportchannel>
    </exportitem>
    <exportitem id="70458" prio="" createddate="Fri, 15 Feb 2013 14:51:16 +0100"             updateddate="Fri, 15 Feb 2013 14:51:16 +0100" publisheddate="" status="exported"             message="" externalid="" externalviews="0">
        <exportchannel id="254" name="MG" exportsystemid="3" exportsystemname="Facebook"                 authtokenid="197" status="active">
            <fieldset name="config">
                <field name="playout">demofilms</field>
            </fieldset>
        </exportchannel>
    </exportitem>
</exports>

Export fields

Field Type Description
exports container Contains exports made to other platforms.
exportitem container Contains information concerning the export to another platform.
exportchannel container Contains information concerning the exportchannel as configured within the VMS.

Next auxiliary-fields are defined, which are used for grouping all textual meta information together. A few elements (categorization tree, description, title author and copyright are also returned at the root level, this is for legacy compatibility reasons.

The auxiliary fields container element is customizable and can be extended with any number of extra fields using the field element:

<field name="somenewfield">somenewfield contents</field>

These extra fields can be made available in the VMS user interface by configuring them in the publication’s main configuration, however they will always be available in the XML API.

[xml]
<auxiliary-fields>
    <field name="mainCat">News</field>
    <field name="subCat">Politics</field>    
    <field name="company">Test</field>
</auxiliary-fields>

Next some additional fields could be available.

[xml]
<stats>
    <results>
        <mediaclip>
            <id descr="ID">2119581</id>
                <totalViewsAllTime descr="Total views">4032</totalViewsAllTime>
            </mediaclip>
    </results>
</stats>
<subtitles>
    <subtitle id="61" name="" default="true" publicationid="1" createddate="Wed, 22 May 2013 09:53:11 +0200" updateddate="Tue, 28 May 2013 10:46:41 +0200" isocode="nl" languageid="1" languagename="Nederlands"             status="published"/>
</subtitles>
<nametags>
    <nametag id="63" name="" default="true" publicationid="1" createddate="Mon, 17 Jun 2013 10:12:52 +0200" updateddate="Mon, 17 Jun 2013 10:14:55 +0200" isocode="nl" languageid="1" languagename="Nederlands"         tatus="published"/>
</nametags>
<timelines>
    <timeline id="244"/>
</timelines>

Additional fields

Field Type Description
stats container If the mediaclip have been published and there have been views, some statistics information will be available.
subtitles container If their have been subtitles configured to a mediaclip, these are listed within this container.
nametags container If their have been nametags configured to a mediaclip, these are listed within this container.
timelines container If a timeline is added to a mediaclip timelines contain the timelines and their id(entifier).

References to multiple representations of the clips audiovisual content called assets, are listed in the assets container.

[xml]
<assets>
    <asset id="1360933047387513" media-clipid="2119581" media-type="thumbnailset" width="" height="" bandwidth="" jobqid="2" src="/bb/media/2013/02/15/1360933047387513/thumbnailset-1360933047387513.xml" filename="thumbnailset-1360933047387513.xml" length="0"/>
    <asset id="1360933047621483" media-clipid="2119581" media-type="MP4_MAIN" width="360" height="200" bandwidth="200" jobqid="143" src="/bb/media/2013/02/15/asset-1360933047621483.mp4" filename="asset-1360933047621483.mp4" length="168"/>
    <asset id="1360933047728053" media-clipid="2119581" media-type="MP4_MAIN" width="360" height="200" bandwidth="400" jobqid="144" src="/bb/media/2013/02/15/asset-1360933047728053.mp4" filename="asset-1360933047728053.mp4" length="168"/>
    <asset id="1360933047783310" media-clipid="2119581" media-type="MP4_IPOD" width="496" height="288" bandwidth="800" jobqid="145" src="/bb/media/2013/02/15/asset-1360933047783310.mp4" filename="asset-1360933047783310.mp4" length="168"/>
    <asset id="1360933047841188" media-clipid="2119581" media-type="MP4_MAIN" width="720" height="400" bandwidth="1200" jobqid="146" src="/bb/media/2013/02/15/asset-1360933047841188.mp4" filename="asset-1360933047841188.mp4" length="168"/>
    <asset id="1360933047877766" media-clipid="2119581" media-type="MP4_HD" width="1280"     height="720" bandwidth="2000" jobqid="147" src="/bb/media/2013/02/15/asset-1360933047877766.mp4" filename="asset-1360933047877766.mp4" length="168"/>
</assets>

Asset atributes

Key Type Description
id int The id(entifier) of the asset
media-clipid string The mediaclip to which the asset is related to.
media-type int The type of media of the asset.
width int The width of the asset (video).
height int The height of the asset (video).
bandwidth int The (minimal) bandwith needed to broadcast the asset fluently.
jobqid int The transcoding job id.
src string The location of the asset.

References to thumbnails related to the mediaclip are listed within the thumbnails container.

[xml]
<thumbnails>
        <thumbnail id="1374591860101059" src="/bb/media/2013/07/23/1374590095103873.jpg"                 sourceid="273c72b8906557be64cce830d9cd2896" main="false" width="720" height="400"/>
        <thumbnail id="1374591860544147" src="/bb/media/2013/07/23/1374590095721340.jpg"                 sourceid="134ff2a33b3886581ce0046771b6d1fb" main="false" width="720" height="400"/>
        <thumbnail id="1374591860819525" src="/bb/media/2013/07/23/1374590096092123.jpg"                 sourceid="dfe5545139820a474bea12cc46828f17" main="false" width="720" height="400"/>
        <thumbnail id="1374591861102754" src="/bb/media/2013/07/23/1374590096415857.jpg"                 sourceid="00fa178824a0619bd9c743c4b17c0883" main="false" width="720" height="400"/>
</thumbnails>

Thumbnail atributes

Key Type Description
id int The id(entifier) of the thumbnail
src string The location of the thumbnail.
sourceid string The location of the thumbnail.
main string If set to true the thumbnail will be displayed in the player.
width int The width of the thumbnail.
height int The height of the thumbnail.

In the last jobs container, the transcoding jobs are listed. Each job also contains a status attribute, which can be used to check whether all assets are transcoded.

[xml]
<jobs>
    <job id="1206332" name="" createddate="2013-02-15 13:57:20" updateddate="0000-00-00             00:00:00" starteddate="2013-02-15 13:57:27" finisheddate="2013-02-15 13:57:34" media-            clipid="2119581" queuename="bb-snapshots" jobqid="2" status="transcoded"/>
    <job id="1206333" name="" createddate="2013-02-15 13:57:20" updateddate="0000-00-00             00:00:00" starteddate="2013-02-15 13:57:27" finisheddate="2013-02-15 13:58:54" media-            clipid="2119581" queuename="h264-360x200-200" jobqid="143" status="transcoded"/>
    <job id="1206334" name="" createddate="2013-02-15 13:57:20" updateddate="0000-00-00 00:00:00"             starteddate="2013-02-15 13:57:27" finisheddate="2013-02-15 13:58:43" media-clipid="2119581"             queuename="h264-360x200-400" jobqid="144" status="transcoded"/>
</jobs>

Mediaclip data types

In the following paragraphs types for the mediaclip entities are described.

Use types

A mediaclip entity can have two different use types.

Use type Description
editorial For clips/video's the editorial use type is used.
commercial The commercial use-type is used for creatives.

Note: The use type commercial is a legacy designation, in the front-end it's known as creative.

Source types

A mediaclip entity can have two different source types.

Use type Description
on_demand This source type is used for static/non-live video or audio items, which are requested on-demand by the end-user.
live This source type is used for live-streams, for example a rtmp-stream.

Media types

The mediaclip entity can respresent different media types. Some of the media types are only available for one of the use types.

Media type Use type Description
video editorial/commercial Used for video content.
audio editorial/commercial Used for audio content.
image editorial/commercial Used for images.
document editorial Used for documents or files, like PDF, Word-dcouments, txt-files, etc.
interactive commercial Used for interactive content (SWF/Flash movie).
text commercial Used for (commercial) textual content/advertisement.
mainroll commercial Used for (video) advertisement(s).

Supported media containers/extensions are: mp4, mov, mpg, mpeg, f4v, flv, 3gp, vob, mkv, asf, mts, ts, mpeg2, avi, wmv, m4v, dv, mxf, mp3, wav, aif, aiff, wma, au, snd, ogg, m4a, aac, gif, jpg, jpeg, bmp, png, bmp, tiff, tif, swf and aif.

Supported document types/extensions are: pdf, html, doc, docx, xlsx, ppt, pptx, txt, xls, csv, zip and rar.

Mediacliplist

A Mediacliplist represents a set of mediaclips directly (static mediacliplist) or indirectly through a stored query (dynamic mediacliplist). Below In the next paragraphs the mediacliplist XML representation is explained divided in sections.

Below the different parts the XML representation of static mediacliplist are shown. The first section presents the header, containing the most essential information of the mediacliplist.

[xml]
<?xml version="1.0"?>
<media-clips id="1224863963707263" type="static" status="draft" title="Jan Mulder" count="2">

Date attributes

Key Type Description
id int The mediacliplistid, the unique identifier for a mediacliplist within the VMS.
type string The type of a mediacliplist, possible values are static or dynamic
status string The status attribute represents whether a mediacliplist is public available "published" or not publicly available "draft".
title string The title of the mediacliplist.
count int The numbers of mediaclips/items within the cliplist. This attribute is only available for static meidacliplists.

The header is followed by some fixed metadata fields, which are used to describe the contents of the mediacliplist. And also it's possible to add a number of custom fields, similar to a medicalip.

[xml]
<description></description>
<author>Jan Mulder</author>
<copyright></copyright>

Metadata fields

Field Type Description
description string Contains a brief description about the content.
author string Can hold the author of the content.
copyright string Can hold the copyrighter of the content.

Similar as in a mediaclip multiple custom fields can be added to the auxiliary fields container element. In the example below an extra title field is added.

[xml]
<auxiliary-fields>
    <field name="title">Jan Mulder</field>
</auxiliary-fields>

Depending on the mediacliplist type, next the linked mediaclips will be included for the static mediacliplist or the search query parameters for a dynamic mediacliplist. The included mediaclips data is formated as the mediaclip XML. The search query parameters are included as shown below.

[xml]
<search sort="createddate asc" limit="1">
    <query type="daterange" datefield="createddate" operator="and" not="false" from="20120522" to="20120622"/>
    <query type="daterange" datefield="publisheddate" operator="and" not="false" from="20130225" to="20130325"/>
    <query type="field" fieldname="type" content="mediaclip"/>
    <filters/>
</search>

In the above example all mediaclips are included in the dynamic mediacliplist which are created and published between certain date ranges and of the type mediaclip.

Player

For the player entity there is an XML view which represents the configuration of available options and default values for that specfic audio/video player.

[xml]
<player id="48" name="Blue Billywig Standard v4.3.15 " 
    updateddate="2013-10-29 13:01:56" 
    publicationid="234" 
    status="active" 
    type="swf" 
    src="/publications/somepublication/player/flash/flexplayer.swf" 
    html5src="/publications/somepublication/player/html5/generic/">

Header attributes

Key Type Description
id int The player id, the unique identifier of a player within the VMS.
updateddate date The last date and time the player configuration was updated.
publicationid int The id of the publication to which the player belongs to.
status string The status attribute represents whether a player is active and public available or not and inactive.
type string The (default used) type of the player.
src string The path to the player application.
html5src string If available the path to an alternate HTML5 player (optional).

The rest of the xml provides a list of options and how they should be represented in a user interface (The VMS client). Below a couple of these options are shown.

[xml]
        <fieldset name="config">
            <category name="Appearance" description="">
            <subcategory name="Size" description="">
                <field type="int" name="width" itype="text" label="Width" tooltip="Use a percentage for                     a responsive playout (eg 100%)." priority="mandatory" extendable="" visible="">720
                </field>
                <field type="int" name="height" itype="text" label="Height" tooltip="Use a percentage                     for a responsive playout (eg 100%)." priority="mandatory" extendable=""                     visible="">404</field>
                <field type="boolean" name="autoHeight" itype="checkbox" label="Calculated height"                     tooltip="Calculate the playout height based on the given width and mediaclip                     aspectratio (overrides default height)." priority="stress" extendable="" visible="">
                    <options>
                        <option label="false" selected="true">false</option>
                        <option label="true">true</option>
                    </options>
                </field>
            </subcategory>
            <subcategory name="Color" description="">
                <field type="100slider" name="alphaControlBar" itype="text" label="Skin Background                     opacity ( 0 - 100 )" priority="" extendable="" visible="">60</field>
                <field type="string" name="skin_backgroundColor" itype="color" label="Skin Background                     Color" priority="" extendable="" visible="">ffffff</field>
                <field type="string" name="skin_foregroundColor" itype="color" label="Skin Foreground                     Color" priority="" extendable="" visible="">000033</field>
                <field type="string" name="skin_widgetColor" itype="color" label="Skin Widget Color"                     priority="" extendable="" visible="">ffffff</field>
            </subcategory>

    </fieldset>
</player>

Playout

The playout is configuration of a player based on the configurable options of concerning player entity. This configuration is eventually used for the presentation and playback of the player as seen by the end-user/viewer.

Header attributes

Key Type Description
id int The playout id, the unique identifier of a playout within the VMS.
name string The human readable name of the player as specified by the user.
status string The status attribute represents whether a playout is active and public available or not and inactive.
label string The system label/name used by the VMS platform, which is for example included in the Javascript embed-code to specify the playout to be used.
playerid int The related/configured player (entity) id.
writeprotected bool The writeprotected attribute determines whether the playout configuration can be altered by any VMS-user (false) or only by administrtors (true)

Next the fieldset container is set,containing multiple field elements. Each configures a certain player (enitity) option.

[xml]
    <fieldset name="config" writeprotected="true">
        <field name="width">368</field>
        <field name="height">207</field>
        <field name="autoplay">false</field>
        <field name="controlBar">Show</field>
        <field name="progressBar">Show</field>
        <field name="timeDisplay">Show progress and total time</field>
        <field name="volume">Show</field>
        <field name="fullScreen">Show</field>
        <field name="embedCode">Show</field>
        <field name="hyvesLink">Show</field>
        <field name="nuJijLink">Show</field>
        <field name="mySpaceLink">Show</field>
        <field name="facebookLink">Show</field>
        <field name="share">Show</field>
        <field name="info">Show</field>
    </fieldset>    
</playout>

Subtitle

The subtitle entity is a child of and related to the mediaclip entity. The subtitle entity consists of a track of subtitles that can be delviered in the following standard formats:

  • W3C timed text xml format (Timed Text (TT) Authoring Format V1.0)
  • SRT format

Its purpose is to deliver multilingual captions in a Blue Billywig (Flash) or device (Phone, Smart TV, Tablet) player that supports captions.

Example srt format:

[srt]
1
00:00:20,000 --> 00:00:24,400
Altocumulus clouds occur between six thousand

2
00:00:24,600 --> 00:00:27,800 
and twenty thousand feet above ground level.

For more information on the w3c timed text xml or srt format see:
http://www.w3.org/TR/ttaf1-dfxp/
http://en.wikipedia.org/wiki/SubRip

Languages

The language entity contains information about the available/configured languages for a certain publication. The configured languages will determine which subtitles can be added to a mediclip.

[xml]
<languages publicationid="12" count="4">
    <language id="13" name="English" publicationid="12" createddate="Wed, 30 Nov -001 00:00:00 +0100"         updateddate="Wed, 10 Mar 2010 11:07:08 +0100" isocode="en" default="true" status="draft"/>
    <language id="14" name="Dutch" publicationid="12" createddate="Wed, 30 Nov -001 00:00:00 +0100"         updateddate="Wed, 10 Mar 2010 11:08:31 +0100" isocode="nl" default="false" status="published"/>
    <language id="15" name="French" publicationid="12" createddate="Wed, 30 Nov -001 00:00:00 +0100"         updateddate="Wed, 10 Mar 2010 11:09:00 +0100" isocode="fr" default="false" status="published"/>
    <language id="16" name="Arabic" publicationid="12" createddate="Mon, 31 May 2010 17:25:49 +0200"         updateddate="Mon, 31 May 2010 17:25:49 +0200" isocode="ar" default="false" status="published"/>
</languages>

language attributes

Key Type Description
id int The language id, the unique identifier of a language configuartion within the VMS.
name string The human readable name of the language and used within the VMS.
publicationid int The id of the publication to which the language entity is related to.
createddate date Represents the date and time the language entity is created.
updateddate date Represents the date and time the entity was modfied.
isocode string The iso standard code of the language.
default bool The language which is used as default (true).
status string The status of the language whether it's available (published) or not.

Authentication and authorisation

Organisation

The organisational entity structure of the BB authorisation model is as follows:

Publication
    User
        Role
            Permission(s)

The highest hierarchical level is “Publication”. The Publication context is automatically fetched using the HTTP HOST header. E.g.: When the url http://bb.vms.bluebillywig.lan/api/bbauth?action=checkSession is called, the publication context will be bb, or whatever publication that is configured to be related to this host header.

By default, a user has read/write rights for all content in the home publication, and other publications that have shared access enabled.

The uri /api/bbauth is the main interface to the Blue Billywig authentication and authorization classes. It has one major parameter: action

All valid actions usable by external systems are described in the next sections.

We recommend using our RPC to log in to the vms as this will simplify the login process. The RPC also has basic functionality to call the api. We have a PHP RPC which is documented here as well as a Java RPC which is documented here.

 

Login to the VMS platform

To login into the Blue Billywig VMS platform a couple of actions have to be taken.

First a random key needs to be retrieved.

Request
/api/getRandom

Result
The returned XML will contain a random-key.

Example
/api/getRandom

[xml]
<?xml version="1.0"?>    
<response code="200" error="false">ktxqwgcb9h</response>

Next the password needs to be calculated. The plaintext password first needs to be encoded with md5 encoding and after that with base64 encoding. After this action the retrieved random-key needs to be added as postfix of the just encoded password. And finally this whole password string needs to be md5 and base64 encoded for the second time.

Example
Below a password encoding example in PHP is shown.

[php]
$encodedPassword = base64_encode(md5(base64_encode(md5($myplaintextpassword)).$randomkey));

After the password is encoded the actual login action can be executed, using the get_user action.

Request
/api/bbauth?action=get_user

Attribute Type Description
Required parameters    
username string The username of a VMS user/account.
password string The encoded password.

Result
If the login was successful a XML message containing the user information will be returned. If it was unsuccessful a login failed message will be returned.

Example
/api/bbauth?action=get_user&username=support@bluebillywig.com&password=Hdjsd7ds32f23FAKel923K

Successful authentication

[xml]
<?xml version="1.0"?>    
<user id="35" name="testuser@bluebillywig.com" firstname="Test" lastname="User" gender="male" email="support@bluebillywig.com">

Failed authentication

[xml]
<?xml version="1.0"?>    
<response code="404" error="true">no user context or user is not authenticated</response>

Checking a VMS session

To check whether the session is still valid the checkSession action is used.

Request
/api/bbauth?action=checkSession

Result
A XML response is returned, containing a message and code whether the session still exists.

Example
/bbauth?action=checkSession

[xml]
<?xml version="1.0"?>
<response code="200" error="false">a valid session exists</response>

Logoff from the VMS platform

To end a VMS session, the logoff action is used.

Request
/api/bbauth?action=logoff

Result
The result will show whether the action was successful or failed.

Example
/api/bbauth?action=logoff

[xml]
<response code="200" error="false">the session has been destroyed</response>

Public content API

With the Public content API it's possible to embed a player on your page, get mediaclip information, generate SEO/Facebook metadata, generate a sitemap, retrieve subtitles or get the vodcast source. All of these API calls are publicly available, but read only.

Mediaplayer Javascript Embed Code

Javascript code that renders a player using Playout options, publication data and content data as specified.

The Mediaplayer Embed Controller delivers players and content on websites or in apps. Several playout related options can be specified/overruled by issueing query string parameters. For a full list of playout options see [ Player API Guide ].

Request
/p/{playout name}/{content type identifier}/{content id}.js?[query_string]

Parameter Type Description
Required parameters    
{id} int The id of the media-clip
{playout name} string The name of the playout to be used
{content type identifier} string c (clip), l (list) or q (query).
{content id} int The id of the clip or cliplist, or the query in case of a 'q' content type identifier
Optional parameters    
[query_string] string several options. eg. autoPlay, width, height autoMute

Mediaplayer Standalone/html Embed code

HTML code that renders a script tag to javascript code that renders a player using Playout options, publication data and content data as specified.

The Mediaplayer Embed Controller delivers players and content on websites or in apps. Several playout related options can be specified/overruled by issueing query string parameters. For a full list of playout options see [ Player API Guide ]. This Standalone/HTML embed controller wraps around the Javascript embed controller and can be used to link straight to a VMS video, or to include a VMS video in an iframe. Any (query string) arguments are passed on to the javascript embed controller that is rendered within the result body of this controller.

Request
/p/{playout name}/{content type identifier}/{content id}.html?[query_string]

Parameter Type Description
Required parameters    
{id} int The id of the media-clip
{playout name} string The name of the playout to be used
{content type identifier} string c (clip), l (list) or q (query).
{content id} int The id of the clip or cliplist, or the query in case of a 'q' content type identifier
Optional parameters    
[query_string] string several options. eg. autoPlay, width, height autoMute

Mediaclip API

The Public Mediaclip API provides public access to media-clip (metadata) content in several ways:

JSON/JSONP

Full metadata and asset references export in JSON or JSONP format or a json formatted error response.

See chapter [[media_content_types]] for a full description of the formatted content. The optional url parameter [callback] can be used to format the result in a wrapper function (JSONP). The callback function will be named according to the contents of the [callback] url parameter.

Request
/json/mediaclip/{id}?[callback]

Parameter Type Description
Required parameters    
{id} int The id of the media-clip
Optional parameters    
[callback] string The desired name of the callback (JSONP).

Example
/json/mediaclip/1120920

[json]
{
    id: "1120920",
    type: "MediaClip",
    mediatype: "video",
    fitmode: "none",
    usetype: "editorial",
    sourcetype: "on_demand",
    originalfilename: "BBW_Final_H264_single_korter.mov",
    length: "285",
    sourceid: "",
    title: "Blue Billywig Strategic Online Video",
    description: "Net zo gemakkelijk video op een website zetten als een plaatje.",
    deeplink: "http://www.bluebillywig.com",
    gendeeplink: "",
    copyright: "Blue Billywig",
    author: "Blue Billywig",
    status: "published",
    publicationid: "1",
    createddate: "2011-03-02T16:24:29Z",
    updateddate: "2011-03-02T16:50:44Z",
    publisheddate: "2011-03-02T16:29:35Z",
    date: {
        created: "Wed, 02 Mar 2011 17:24:29 +0100",
        updated: "Wed, 02 Mar 2011 17:50:44 +0100",
        published: "Wed, 02 Mar 2011 17:29:35 +0100"
    },
    src: "/bb/media/2011/03/02/1120920.mov",
    cat: [
        "blue billywig",
        "online video platform",
        "vms",
        "video streaming"
    ],
    thumbnails: [
        {
            src: "/bb/media/2011/03/02/1299083083056283/1299083083056283_116.jpg",
            width: "640",
            height: "360",
            main: "false"
        }
    ],
    assets: [
        {
            mediatype: "MP4_MAIN",
            src: "/bb/media/2011/03/02/asset-1299083083421265.mp4",
            length: "285",
            width: "360",
            height: "200",
            bandwidth: "200"
        },
        {
            mediatype: "MP4_HD",
            src: "/bb/media/2011/03/02/asset-1299083192232962.mp4",
            length: "285",
            width: "1280",
            height: "720",
            bandwidth: "2000"
        }
    ],
    subtitles: null,
    nametags: null,
    exports: [
        {
            id: "65539",
            prio: "",
            createddate: "2012-12-04T13:07:43Z",
            updateddate: "2012-12-04T13:07:43Z",
            publisheddate: false,
            status: "exported",
            message: "",
            externalid: "",
            externalviews: "0",
            exportchannel: {
                id: "235",
                type: "ExportChannel",
                name: "BBFBpage",
                exportsystemid: "3",
                exportsystemname: "Facebook",
                authtokenid: "178",
                status: "active",
                fbpagename: "Blue Billywig",
                fbpageid: "266122176736872",
                playout: "VidCompare",
                config: {
                    fbpagename: "Blue Billywig",
                    fbpageid: "266122176736872",
                    playout: "VidCompare"
                }
            }
        }
    ],
    timelines: null
}

XML

Full metadata and asset references export in XML format.

See chapter [[media_content_types]] for a full description of the formatted content.
There are no required or optional parameters.

Request
/mediaclip/{id}.xml

Parameter Type Description
Required parameters    
{id} int The id of the media-clip

Direct call to asset

Redirect directly to one of the media-clips assets. A HTTP 302 response will take care of the actual redirect.

This uri should be called with a clip id and a mediatype which can be any one of: * MP4_IPOD : video format supported on iPhone (3g+), iPod Touch, iPad 1, most * MP4_MAIN: Standard Definition version (typically 720x400@1.2Mbps) * MP4_HD: High Definition version (typically 1280x720@2Mbps)
Note: {mediatype} is case sensitive

Request
/mediaclip/{id}/redirect/{mediatype}

Parameter Type Description
Required parameters    
{id} int The id of the media-clip
{mediatype} string MP4_IPOD, MP4_MAIN OR MP4_HD

Example

[CLI]
#!/bin/bash
     wget http://bb.bbvms.com/mediaclip/1114195/redirect/MP4_HD  
--2013-10-03 16:36:40--  http://bb.bbvms.com/mediaclip/1114195/redirect/MP4_HD
Resolving bb.bbvms.com (bb.bbvms.com)... 217.115.196.80
Connecting to bb.bbvms.com (bb.bbvms.com)|217.115.196.80|:80... connected.
HTTP request sent, awaiting response... 302 Found
Location: http://d2rvackbgybhru.cloudfront.net/bb/media/2013/07/24/asset-1374675163357241.mp4 [following]
--2013-10-03 16:36:41--  http://d2rvackbgybhru.cloudfront.net/bb/media/2013/07/24/asset-1374675163357241.mp4
Resolving d2rvackbgybhru.cloudfront.net (d2rvackbgybhru.cloudfront.net)... 54.230.128.15, 54.230.129.56, 54.230.129.101, ...
Connecting to d2rvackbgybhru.cloudfront.net (d2rvackbgybhru.cloudfront.net)|54.230.128.15|:80... connected.
HTTP request sent, awaiting response... 200 OK
Length: 43024619 (41M) [video/mp4]
Saving to: `MP4_HD'

Image resizer

The media-clip image resizer can be used to fetch an automatically resized main thumbnail image of the specified media-clip.
URI Structure: /mediaclip/{id}/pthumbnail/{width}/{height}.{extension} Where {id} is the id of a publicly available (i.e. the clip will need to be published) media-clip
and {width} is either default or the desired width in pixels. Both {width} and {height} can be set to default, which means the original size will be used.
For automatically generated thumbnails (through the VMS transcoding backend) the default resolution is 1920x1080. If the source video has a lower resolution than 1920x1080, thumbnails will use that resolution as a max. Aspect ratio is automatically calculated to fit the measurements of the source material. {extension} can be set to either jpg or png. If the original image is a png image with alpha channel transparency, the transparency layer is preserved in the resized result.

Request
/mediaclip/{id}/pthumbnail/{width}/{height}.{extension}?[playButton]

Parameter Type Description
Required parameters    
{id} int The id of the media-clip
{width} int Desired width in pixels or "default"
{height} int Desired height in pixels or "default"
{extension} string Desired file extension: png or jpg
optional parameters    
[playButton] boolean Show a play button on the thumbnail.

 

Example
http://bb.bbvms.com/mediaclip/2079210/pthumbnail/default/default.jpg

QR Code generator

The QR Code generator automatically generates a QR Code of the media-clip deeplink.

If the deeplink field is filled and starts with a valid http/https protocol identifier, the contents of this field are used. Otherwise, if a deeplink generator is configured (see VMS User Manual - Settings)., the generated deeplink url is used.

Request
/mediaclip/{id}-qrcode.png

Parameter Type Description
Required parameters    
{id} int The id of the media-clip

Example
http://bb.bbvms.com/mediaclip/1120920-qrcode.png

Media Cliplist API

The Public Media Cliplist API provides public access to media-cliplist (metadata) content in either json(p) or XML format. Only publicly available (ie. mediaclips that are published) content items (media-clips) will be shown. - embargoed media-clips (clips that have a published date before the configured from date and/or after the configured to date) [ see user manual ] - draft media-clips (status=draft) - deleted media-clips (status=deleted)
are automatically filtered out of the response, even if they are directly related to the requested media-cliplist.

JSON/JSONP

/json/mediacliplist/{cliplist id}

Parameter Type Description
Required parameters    
{cliplist id} int The id of the media-cliplist

Example
http://bb.bbvms.com/json/mediacliplist/1374673191341240

[json]
{
    id: "1374673191341240",
    type: "MediaClipList",
    mediatype: "video",
    listtype: "static",
    usetype: "editorial",
    sourcetype: null,
    title: "videositemap",
    description: null,
    deeplink: null,
    copyright: "",
    author: null,
    status: "published",
    date: {
        created: "Wed, 24 Jul 2013 15:39:51 +0200",
        updated: "Wed, 24 Jul 2013 16:06:07 +0200",
        published: "Wed, 24 Jul 2013 15:40:07 +0200"
    },
    cat: [
        "interactieve video",
        "timeline"
    ],
    thumbnails: [
        {
            src: "/bb/media/2013/07/08/1373291871541490.jpg",
            width: "720",
            height: "400",
            main: "true"
        },
        ...
    ],
    items: [
        {
            id: "2191579",
            type: "MediaClip",
            mediatype: "video",
            fitmode: null,
            usetype: "editorial",
            sourcetype: "on_demand",
            originalfilename: "succesvolle_interactieve_video's_1280x720.mp4",
            length: "206",
            sourceid: "",
            title: "Interview over succesvolle interactieve video",
            description: null,
            deeplink: "http://www.bluebillywig.com/nl/nieuws/succesvolle-interactieve-video",
            gendeeplink: "",
            copyright: null,
            author: null,
            status: "published",
            publicationid: "1",
            createddate: "2013-07-08T13:42:44Z",
            updateddate: "2013-07-22T12:57:14Z",
            publisheddate: "2013-07-08T13:56:52Z",
            date: {
                created: "Mon, 08 Jul 2013 15:42:44 +0200",
                updated: "Mon, 22 Jul 2013 14:57:14 +0200",
                published: "Mon, 08 Jul 2013 15:56:52 +0200"
            },
            src: "/bb/media/2013/07/08/2191579.mp4",
            cat: [
                "interactieve video",
                "timeline"
            ],
            thumbnails: [
                {
                    src: "/bb/media/2013/07/08/1373291871541490.jpg",
                    width: "720",
                    height: "400",
                    main: "true"
                }
            ],
            assets: [
                {
                    mediatype: "MP4_HD",
                    src: "/bb/media/2013/07/08/asset-1373290974179145.mp4",
                    length: "206",
                    width: "1280",
                    height: "720",
                    bandwidth: "2000"
                },
                ...
            ],
            subtitles: null,
            nametags: null,
            exports: null,
            timelines: null
        },
        ...
    ]
}

XML

Request
/mediacliplist/{cliplist id}.xml

Parameter Type Description
Required parameters    
{cliplist id} int The id of the media-cliplist

Example
http://bb.bbvms.com/mediacliplist/1374673191341240.xml

[xml]
<?xml version="1.0"?>
<media-clips id="1374673191341240" type="static" mediatype="video" status="published" title="videositemap" count="3">
    <description></description>
    <author></author>
    <copyright></copyright>
    <deeplink url="" />
    <date published="Wed, 24 Jul 2013 15:40:07 +0200" created="Wed, 24 Jul 2013 15:39:51 +0200" modified="Wed, 24 Jul 2013 16:06:07 +0200" />
    <auxiliary-fields>
        <field name="language" />
    </auxiliary-fields>
    <media-clip mediatype="video" usetype="editorial" sourcetype="on_demand" id="2191579" originalfilename="jeroen_meeter_over_succesvolle_interactieve_video's_1280x720.mp4" sourceid="" status="published" length="206" src="/bb/media/2013/07/08/2191579.mp4" url="http://bb.bbvms.com/mediaclip/2191579.xml" title="Interview Jeroen over succesvolle interactieve video">
        <date published="Mon, 08 Jul 2013 15:56:52 +0200" created="Mon, 08 Jul 2013 15:42:44 +0200" modified="Mon, 22 Jul 2013 14:57:14 +0200" />
        <description />
        <author />
        <copyright />
        <deeplink url="http://www.bluebillywig.com/nl/nieuws/jeroen-meeter-over-succesvolle-interactieve-video" />
        <location>52.11426443322473,5.126770019531306</location>
        <categorization>
            <category-tree type="keywords">
                <category name="interactieve video" />
                ...
            </category-tree>
        </categorization>
        <exports />
        <auxiliary-fields />
        <assets>
            <asset id="1373290974328351" media-clipid="2191579" media-type="MP4_HD" width="1280" height="720" bandwidth="2000" exactlength="206045" jobqid="147" src="/bb/media/2013/07/08/asset-1373290974328351.mp4" filename="asset-1373290974328351.mp4" length="206" />
            ...
        </assets>
        <thumbnails>
            <thumbnail id="1373292723919449" src="/bb/media/2013/07/08/1373291871541490.jpg" sourceid="232e9dc5959bdb0d4a9d8fbfc3094279" main="true" width="720" height="400" />
            ...
        </thumbnails>
    </media-clip>
    ...
</media-clips>

External metadata generator (SEO/FB)

Retrieve Microdata tags for Search Engine Optimisation (SEO) and Open Graph tags for Facebook embedding (FB). The tags will be filled with values based on the metadata of a mediaclip saved within the VMS.

The result can be delivered in XML or JSON format, so it can be parsed by your web-application/CMS. The Microdata tags should be placed in the body of a HTML page and the Open Graph tags in the head.

Request /microdata/?{c}=&{p}=&{OG}=

Parameter Type Description
Required parameters    
c int The id of the mediaclip.
p string The playout to be used in generated embed-url's and so on Facebook.
OG int Retrieve the Open Graph tags. To retrieve the data, the value needs to be set to 1.*
MD int Retrieve the Microdata tags. To retrieve the data, the value needs to be set to 1.*
Optional parameters    
MC int Include the Metadata of the mediaclip. To retrieve the data, the value needs to be set to 1.
title string Set another title and overrule the one saved within the VMS.
description string Set another description and overrule the one saved within the VMS.
url string Set another reference url and overrule the (generated) deeplink as saved within the VMS.
appid string Set another Facebook App-id.
tagName string Overrule the tag used to encapsulate the microdata tags. Default: span
contextIdentifier string Set a context identifier which will be included several video url's.
rf string The return format of the data; possible values are xml or json.
callback string The desired name of the callback (JSONP).

*At least one of these parameters needs to be set.

Example
/microdata/?c=1075272&p=default&fbapp=1235813&mst=0&MD=1&OG=1&cxi=fbEmded&rf=json

[JSON]
{  
   "fb":{  
      "tags":{  
         "fb:app_id":{  
            "tag":"<meta property=\"fb:app_id\" content=\"123581321\">"
         }
      },
      "tags_blob":"\n<meta property=\"fb:app_id\" content=\"123581321\">"
   },
   "og":{  
      "tags":{  
         "comment_opengraph":{  
            "tag":"<!-- Open Graph tags -->"
         },
         "og:title":{  
            "tag":"<meta property=\"og:title\" content=\"Fennesz &#34;Caecilia&#34;\" \/>",
            "value":"Fennesz &#34;Caecilia&#34;"
         },
         "og:type":{  
            "tag":"<meta property=\"og:type\" content=\"video\" \/>",
            "value":"video"
         },
         "og:site_name":{  
            "tag":"<meta property=\"og:site_name\" content=\"Blue Billywig\">",
            "value":"Blue Billywig"
         },
         "og:url":{  
            "tag":"<meta property=\"og:url\" content=\"http:\/\/bb.dev.bbvms.com\/view\/fbEmbed.html\"\/>",
            "value":"http:\/\/bb.dev.bbvms.com\/view\/fbEmbed.html"
         },
         "og:description":{  
            "tag":"<meta property=\"og:description\" content=\"Fennesz &#34;Caecilia&#34; from endless summer.\" \/>",
            "value":"Fennesz &#34;Caecilia&#34; from endless summer."
         },
         "og:image":{  
            "tag":"<meta property=\"og:image\" content=\"http:\/\/bb.dev.bbvms.com\/mediaclip\/1075272\/pthumbnail\/130\/130.jpg\">",
            "value":"http:\/\/bb.dev.bbvms.com\/mediaclip\/1075272\/pthumbnail\/130\/130.jpg"
         },
         "comment_video":{  
            "tag":"<!-- specific for video: -->"
         },
         "og:video":{  
            "tag":"<meta property=\"og:video\" content=\"http:\/\/bb.dev.bbvms.com\/p\/default\/playere21dd4abf727a1124a115a67d029c838.swf?defaultMediaAssetPath=https:\/\/d3mxuwgars1eqe.cloudfront.net&server=http:\/\/bb.dev.bbvms.com\/&clipXmlUrl=http:\/\/bb.dev.bbvms.com\/mediaclip\/1075272.xml&cxi=fbEmded\"\/>",
            "value":"http:\/\/bb.dev.bbvms.com\/p\/default\/playere21dd4abf727a1124a115a67d029c838.swf?defaultMediaAssetPath=https:\/\/d3mxuwgars1eqe.cloudfront.net&server=http:\/\/bb.dev.bbvms.com\/&clipXmlUrl=http:\/\/bb.dev.bbvms.com\/mediaclip\/1075272.xml&cxi=fbEmded"
         },
         "og:video:type":{  
            "tag":"<meta property=\"og:video:type\" content=\"application\/x-shockwave-flash\" \/>",
            "value":"application\/x-shockwave-flash"
         },
         "og:video:url":{  
            "tag":"<meta property=\"og:video:url\" content=\"http:\/\/bb.dev.bbvms.com\/p\/default\/playere21dd4abf727a1124a115a67d029c838.swf?defaultMediaAssetPath=https:\/\/d3mxuwgars1eqe.cloudfront.net&server=http:\/\/bb.dev.bbvms.com\/&clipXmlUrl=http:\/\/bb.dev.bbvms.com\/mediaclip\/1075272.xml&cxi=fbEmded\" \/>",
            "value":"http:\/\/bb.dev.bbvms.com\/p\/default\/playere21dd4abf727a1124a115a67d029c838.swf?defaultMediaAssetPath=https:\/\/d3mxuwgars1eqe.cloudfront.net&server=http:\/\/bb.dev.bbvms.com\/&clipXmlUrl=http:\/\/bb.dev.bbvms.com\/mediaclip\/1075272.xml&cxi=fbEmded"
         },
         "og:video:secure_url":{  
            "tag":"<meta property=\"og:video:secure_url\" content=\"https:\/\/bb.dev.bbvms.com\/p\/default\/playere21dd4abf727a1124a115a67d029c838.swf?defaultMediaAssetPath=https:\/\/d3mxuwgars1eqe.cloudfront.net&server=https:\/\/bb.dev.bbvms.com\/&clipXmlUrl=https:\/\/bb.dev.bbvms.com\/mediaclip\/1075272.xml&cxi=fbEmded\"\/>",
            "value":"https:\/\/bb.dev.bbvms.com\/p\/default\/playere21dd4abf727a1124a115a67d029c838.swf?defaultMediaAssetPath=https:\/\/d3mxuwgars1eqe.cloudfront.net&server=https:\/\/bb.dev.bbvms.com\/&clipXmlUrl=https:\/\/bb.dev.bbvms.com\/mediaclip\/1075272.xml&cxi=fbEmded"
         },
         "og:video_html5":{  
            "tag":"<meta property=\"og:video\" content=\"https:\/\/d3mxuwgars1eqe.cloudfront.net\/media\/2013\/12\/20\/asset-1387533066583800.mp4\" \/>",
            "value":"video"
         },
         "og:video:type_html5":{  
            "tag":"<meta property=\"og:video:type\" content=\"video\/mp4\" \/>",
            "value":"video\/mp4"
         },
         "og:video:url_html5":{  
            "tag":"<meta property=\"og:video:url\" content=\"https:\/\/d3mxuwgars1eqe.cloudfront.net\/media\/2013\/12\/20\/asset-1387533066583800.mp4\" \/>",
            "value":"https:\/\/d3mxuwgars1eqe.cloudfront.net\/media\/2013\/12\/20\/asset-1387533066583800.mp4"
         },
         "og:video:secure_url_html5":{  
            "tag":"<meta property=\"og:video:secure_url\" content=\"https:\/\/d3mxuwgars1eqe.cloudfront.net\/media\/2013\/12\/20\/asset-1387533066583800.mp4\" \/>",
            "value":"https:\/\/d3mxuwgars1eqe.cloudfront.net\/media\/2013\/12\/20\/asset-1387533066583800.mp4"
         },
         "og:video_directLink":{  
            "tag":"<meta property=\"og:video\" content=\"https:\/\/d3mxuwgars1eqe.cloudfront.net\/media\/2013\/12\/20\/asset-1387533066583800.mp4\" \/>",
            "value":"video"
         },
         "og:video:type_directLink":{  
            "tag":"<meta property=\"og:video:type\" content=\"text\/html\" \/>",
            "value":"text\/html"
         },
         "og:video:width":{  
            "tag":"<meta property=\"og:video:width\" content=\"396\" \/>",
            "value":"396"
         },
         "og:video:height":{  
            "tag":"<meta property=\"og:video:height\" content=\"223\" \/>",
            "value":223
         }
      },
      "tags_blob":"\n<!-- Open Graph tags -->\n<meta property=\"og:title\" content=\"Fennesz &#34;Caecilia&#34;\" \/>\n<meta property=\"og:type\" content=\"video\" \/>\n<meta property=\"og:site_name\" content=\"Blue Billywig\">\n<meta property=\"og:url\" content=\"http:\/\/bb.dev.bbvms.com\/view\/fbEmbed.html\"\/>\n<meta property=\"og:description\" content=\"Fennesz &#34;Caecilia&#34; from endless summer.\" \/>\n<meta property=\"og:image\" content=\"http:\/\/bb.dev.bbvms.com\/mediaclip\/1075272\/pthumbnail\/130\/130.jpg\">\n<!-- specific for video: -->\n<meta property=\"og:video\" content=\"http:\/\/bb.dev.bbvms.com\/p\/default\/playere21dd4abf727a1124a115a67d029c838.swf?defaultMediaAssetPath=https:\/\/d3mxuwgars1eqe.cloudfront.net&server=http:\/\/bb.dev.bbvms.com\/&clipXmlUrl=http:\/\/bb.dev.bbvms.com\/mediaclip\/1075272.xml&cxi=fbEmded\"\/>\n<meta property=\"og:video:type\" content=\"application\/x-shockwave-flash\" \/>\n<meta property=\"og:video:url\" content=\"http:\/\/bb.dev.bbvms.com\/p\/default\/playere21dd4abf727a1124a115a67d029c838.swf?defaultMediaAssetPath=https:\/\/d3mxuwgars1eqe.cloudfront.net&server=http:\/\/bb.dev.bbvms.com\/&clipXmlUrl=http:\/\/bb.dev.bbvms.com\/mediaclip\/1075272.xml&cxi=fbEmded\" \/>\n<meta property=\"og:video:secure_url\" content=\"https:\/\/bb.dev.bbvms.com\/p\/default\/playere21dd4abf727a1124a115a67d029c838.swf?defaultMediaAssetPath=https:\/\/d3mxuwgars1eqe.cloudfront.net&server=https:\/\/bb.dev.bbvms.com\/&clipXmlUrl=https:\/\/bb.dev.bbvms.com\/mediaclip\/1075272.xml&cxi=fbEmded\"\/>\n<meta property=\"og:video\" content=\"https:\/\/d3mxuwgars1eqe.cloudfront.net\/media\/2013\/12\/20\/asset-1387533066583800.mp4\" \/>\n<meta property=\"og:video:type\" content=\"video\/mp4\" \/>\n<meta property=\"og:video:url\" content=\"https:\/\/d3mxuwgars1eqe.cloudfront.net\/media\/2013\/12\/20\/asset-1387533066583800.mp4\" \/>\n<meta property=\"og:video:secure_url\" content=\"https:\/\/d3mxuwgars1eqe.cloudfront.net\/media\/2013\/12\/20\/asset-1387533066583800.mp4\" \/>\n<meta property=\"og:video\" content=\"https:\/\/d3mxuwgars1eqe.cloudfront.net\/media\/2013\/12\/20\/asset-1387533066583800.mp4\" \/>\n<meta property=\"og:video:type\" content=\"text\/html\" \/>\n<meta property=\"og:video:width\" content=\"396\" \/>\n<meta property=\"og:video:height\" content=\"223\" \/>"
   },
   "md":{  
      "tags":{  
         "comment_microdata":{  
            "tag":"<!--  =======================  Schema.org microdata  ======================= -->"
         },
         "span_open":{  
            "tag":"<span itemscope itemtype=\"http:\/\/schema.org\/VideoObject\">",
            "value":"video"
         },
         "name":{  
            "tag":"<meta itemprop=\"name\" content=\"Fennesz &#34;Caecilia&#34;\" \/>",
            "value":"Fennesz &#34;Caecilia&#34;"
         },
         "duration":{  
            "tag":"<meta itemprop=\"duration\" content=\"T3M56S\" \/>",
            "value":"T3M56S"
         },
         "thumbnailUrl":{  
            "tag":"<meta itemprop=\"thumbnailUrl\" content=\"http:\/\/bb.dev.bbvms.com\/mediaclip\/1075272\/pthumbnail\/130\/130.jpg\" \/>",
            "value":"http:\/\/bb.dev.bbvms.com\/"
         },
         "embedURL":{  
            "tag":"<meta itemprop=\"embedURL\" content=\"http:\/\/bb.dev.bbvms.com\/p\/default\/playere21dd4abf727a1124a115a67d029c838.swf?defaultMediaAssetPath=https:\/\/d3mxuwgars1eqe.cloudfront.net&server=http:\/\/bb.dev.bbvms.com\/&clipXmlUrl=http:\/\/bb.dev.bbvms.com\/mediaclip\/1075272.xml&cxi=fbEmded\" \/>",
            "value":"http:\/\/bb.dev.bbvms.com\/p\/default\/playere21dd4abf727a1124a115a67d029c838.swf?defaultMediaAssetPath=https:\/\/d3mxuwgars1eqe.cloudfront.net&server=http:\/\/bb.dev.bbvms.com\/&clipXmlUrl=http:\/\/bb.dev.bbvms.com\/mediaclip\/1075272.xml&cxi=fbEmded"
         },
         "uploadDate":{  
            "tag":"<meta itemprop=\"uploadDate\" content=\"2013-12-17T09:35:35+02:00\"\/>",
            "value":"2013-12-17T09:35:35+02:00"
         },
         "dateCreated":{  
            "tag":"<meta itemprop=\"dateCreated\" content=\"2013-12-17T09:35:35+02:00\"\/>",
            "value":"2013-12-17T09:35:35+02:00"
         },
         "dateModified":{  
            "tag":"<meta itemprop=\"dateModified\" content=\"2014-03-11T15:55:19+02:00\"\/>",
            "value":"2014-03-11T15:55:19+02:00"
         },
         "datePublished":{  
            "tag":"<meta itemprop=\"datePublished\" content=\"2013-12-17T09:41:40+02:00\"\/>",
            "value":"2013-12-17T09:41:40+02:00"
         },
         "keywords":{  
            "tag":"<meta itemprop=\"keywords\" content=\"fennesz touch records caecilia endless summer\"\/>",
            "value":"fennesz touch records caecilia endless summer"
         },
         "description":{  
            "tag":"<meta itemprop=\"description\" content=\"Fennesz &#34;Caecilia&#34; from endless summer.\" \/>",
            "value":"Fennesz &#34;Caecilia&#34; from endless summer."
         },
         "span_close":{  
            "tag":"<\/span>"
         }
      },
      "tags_blob":"\n<!--  =======================  Schema.org microdata  ======================= -->\n<span itemscope itemtype=\"http:\/\/schema.org\/VideoObject\">\n<meta itemprop=\"name\" content=\"Fennesz &#34;Caecilia&#34;\" \/>\n<meta itemprop=\"duration\" content=\"T3M56S\" \/>\n<meta itemprop=\"thumbnailUrl\" content=\"http:\/\/bb.dev.bbvms.com\/mediaclip\/1075272\/pthumbnail\/130\/130.jpg\" \/>\n<meta itemprop=\"embedURL\" content=\"http:\/\/bb.dev.bbvms.com\/p\/default\/playere21dd4abf727a1124a115a67d029c838.swf?defaultMediaAssetPath=https:\/\/d3mxuwgars1eqe.cloudfront.net&server=http:\/\/bb.dev.bbvms.com\/&clipXmlUrl=http:\/\/bb.dev.bbvms.com\/mediaclip\/1075272.xml&cxi=fbEmded\" \/>\n<meta itemprop=\"uploadDate\" content=\"2013-12-17T09:35:35+02:00\"\/>\n<meta itemprop=\"dateCreated\" content=\"2013-12-17T09:35:35+02:00\"\/>\n<meta itemprop=\"dateModified\" content=\"2014-03-11T15:55:19+02:00\"\/>\n<meta itemprop=\"datePublished\" content=\"2013-12-17T09:41:40+02:00\"\/>\n<meta itemprop=\"keywords\" content=\"fennesz touch records caecilia endless summer\"\/>\n<meta itemprop=\"description\" content=\"Fennesz &#34;Caecilia&#34; from endless summer.\" \/>\n<\/span>"
   }
}

Sitemap generator

The VMS has an integrated video sitemap generator that delivers standards compliant video sitemap xml. See sitemaps.org for documentation on the video sitemap format.

The sitemap generator can be invoked in several ways:

Full sitemap

When /sitemap is issued a sitemap containing the latest 10.000 published (and not under embargo) media-clips of mediatype video will be output in video sitemap xml format.

Request
/sitemap?[forcePfx]=true&[urlprefix]=&[urlpostfix]=

Parameter Type Description
Optional parameters    
[forcePfx] bool Should prefix and/or postfix be used for the clip urls
[urlPrefix] string Will be pasted in front of the id of the clip in the generated url. Should start with a valid protocol identifier.
[urlPostfix] string Will be pasted after the id of the clip in the generated url.

Cliplist as sitemap

When /sitemap/{cliplist id}.xml is issued a sitemap containing the latest 10.000 published (and not under embargo) media-clips of mediatype video will be output in video sitemap xml format.

Request
/sitemap/{cliplist id}.xml?[forcePfx]=true&[urlprefix]=&[urlpostfix]=

Parameter Type Description
Required parameters    
{cliplist id} int the id of the cliplist that is used for the sitemap output
Optional parameters    
[forcePfx] string Should prefix and/or postfix be used for the clip urls
[urlPrefix] string Will be pasted in front of the id of the clip in the generated url. Should start with a valid protocol identifier.
[urlPostfix] string Will be pasted after the id of the clip in the generated url.

Subtitles

Subtitles are mostly used to present a transcript of spoken text over the video display. Nametags are technically the same thing. They are meant for object or person identifier labels. The VMS can output subtitle and nametags tracks in both srt and tt (timed text) w3c xml format.

Subtitle as SRT file

Request
/subtitle/{id}.srt

Parameter Type Description
Required parameters    
{id} int the id of the subtitle track. Can be found in the media-clip xml of the associated media-clip, xpath: //subtitles/subtitle@id

Example

[srt]
1
00:00:02,000 --> 00:00:07,250
You knew Bent had had a small blood clot in the spring and that he shouldn't burden himself too much.

2
00:00:07,500 --> 00:00:11,750
You failed to tell me out of self-interest. Look me in the eye and say you didn't also try to discredit me...

3
00:00:12,000 --> 00:00:14,750
...by telling the Ekspres I had prior knowledge of Bent's illness.

4
00:00:15,000 --> 00:00:17,750
I can guarantee Kruse won't sit on a ministerial chair in my government.

5
00:00:18,000 --> 00:00:22,750
You can't fire him in the midst of all this, he's your number two and your EU minister, it stinks.

Subtitle as W3C Timed Text XML

Request
/subtitle/{id}.xml

Parameter Type Description
Required parameters    
{id} int the id of the subtitle track. Can be found in the media-clip xml of the associated media-clip, xpath: //subtitles/subtitle@id

Example

[xml]
<?xml version="1.0"?>
<tt xmlns="http://www.w3.org/2006/10/ttaf1" xml:lang="en">
    <body>
        <div xml:id="subtitles">
            <p begin="00:00:02.00" end="00:00:07.25"><![CDATA[You knew Bent had had a small blood clot in the spring and that he shouldn't burden himself too much.]]></p>
            ...
        </div>
    </body>
</tt>

Vodcast and MRSS

VMS cliplists can be rendered as content feeds in iTunes vodcast format or MRSS format. Below examples are vodcast uri's. Replace vodcast with mrss to get the Yahoo mrss compatible version.

vodcast default

Uses the best widely compatible (MP4_IPOD) media asset for the video reference.

Request
/vodcast/{cliplist id}

Parameter Type Description
Required parameters    
{cliplist id} int the id of the cliplist

Vodcast source

Uses the source media asset for the video reference.

Request
/srcvodcast/{cliplistid}

Parameter Type Description
Required parameters    
{cliplistid} int the id of the cliplist

Vodcast low bitrate

Uses the lowest bitrate media asset for the video reference.

Request
/lqvodcast/{cliplist id}

Parameter Type Description
Required parameters    
{cliplist id} int the id of the cliplist
 

MRSS default

Uses the best widely compatible (MP4_IPOD) media asset for the video reference.

Request
/mrss/{cliplist id}

Parameter Type Description
Required parameters    
{cliplist id} int the id of the cliplist
 

MRSS dfp

Uses the best media asset for the video reference. And extended with several elements which are relevant for DFP.

Request
/dfpmrss/{cliplist id}

Parameter Type Description
Required parameters    
{cliplist id} int the id of the cliplist
 

Appendix

General response code table The response codes are present in the code attribute(xml) or in the top level code var (json(p)).

Code Description
200 OK
400 Bad Request : action or parameters are invalid
403 Permission denied: current user does not have sufficient rights to perform this api request
500 Service error / action could not be handled correctly

Private content API

The private content API provides several web interfaces to access data and control functionality within the VMS. To access the private content API authentication is needed and each action requires the proper permissions. In the next paragraphs the available entities and their requests within the private content API will be higlighted.

Note: Some data and functionality is public accessible, for more information see the chapter "Public content API".

5.1 API requests structure

All requests on the VMS API are structered as follows:
{publication-name}.bbvms.com/api/{entity-name}?{parameters}
example: http://example.bbvms.com/api/publication?action=get

Note: There's also a test environment available, request for this are structured as follows:
{publication-name}.test.bbvms.com/api/{entity-name}?{parameters}

Most results from API request are in XML-format, but for some entities the results can also be retrieved in Json-format. The structure for Json-format requests are:
{publication-name}.bbvms.com/json/{entity-name}/{paramers}
example: http://example.bbvms.com/json/mediaclip/4075164

Requests can be done with GET and POST methods. In the examples in this manual mainly the GET method is used.

5.2 Private publication controller

The private publication controller provides accessing publication (global) configurations and functionality to modify some of these configurations.

5.2.1 Get the publication config

Retrieve a publication configuration.

Note: In most cases the mainconfig.xml will contain sufficient information concerning configurations of the publication, needed for automated processes in which is made use of the VMS-API. It can be requested using the following request: http://{publicationname}.bbvms.com/mainconfig.xml.
The advice is to use that mainly instead of this request to retrieve the publication config.

Request
/api/publication?action=get

Result
The result is XML formatted and consists of several global publication configurations.

Example

[xml]
<publication id="29" publisherid="1" name="demo" status="active" baseurl="http://demo.bbvms.com"         baseuri="/demo/media" sourcepath="/data/content/video/demo/source">
    <statspublication>demo</statspublication>
    <defaultMediaAssetPath>http://mm.demo.bbvms.com</defaultMediaAssetPath>
    <streamingMediaAssetPath>rtmp://rtmp.demo.bbvms.com/cfx/st</streamingMediaAssetPath>
    <disablePositions>false</disablePositions>
    <logo>/publications/demo/yourLogo.png</logo>
    <fieldset name="auxiliary">
        <field type="float" name="latitude" itype="text" label="Latitude (N)" priority="" extendable=""             visible="" public=""/>
        <field type="float" name="longitude" itype="text" label="Longitude (E)" priority=""             extendable="" visible="" public=""/>
    </fieldset>
    <fieldset name="zoneconfig">
        <field name="label" label="Label" type="string" itype="string" allowoverrule="false" value="New             Zone"/>
        <field type="relation" name="clipId" itype="relation" contenttype="mediaclip" label="Mediaclip"             priority=""/>
        <field type="relation" name="cliplistId" itype="relation" contenttype="mediacliplist"             label="Cliplist" priority=""/>
        <field name="width" label="Width" type="string" itype="string" allowoverrule="true"             value="400"/>
        <field name="height" label="Height" type="string" itype="string" allowoverrule="true"             value="580"/>
        <field name="textColor" label="Text color" type="string" itype="color" allowoverrule="true"             value="000000"/>
        <field name="backgroundColor" label="Background color" type="string" itype="color"             allowoverrule="true" value="ffffff"/>
    </fieldset>        
</publication>

Header attributes

Attribute Type Description
id int The unique identifier of a publication within the VMS.
publisherid int The identifier to the related publisher.
name string The name of the publication.
status bool The status attribute represents whether a publication is public available "active" or not publicly available "inactive".
baseurl string The base url is the base url/target, used for all url's/requests related to the VMS-publication.
baseuri string The base uri is the base uri/target used within asset-paths.
sourcepath string The sourcepath is the base path to media sources.

Publication fields

Fieldname Type Description
statspublication string The unique identifier of a publication used for statistics logging.
defaultMediaAssetPath string The default media asset path is the base path, used to request video assets in case of progressive download.
streamingMediaAssetPath string The default media asset path is the base path, used to request assets in case of streaming media.
disablePositions bool A publication wide parameter to disable advertisements. By default set to false.
logo string Location of the logo as can be visbile in the upper right corner of the VMS-GUI.

Furthermore, the result can contain configurations regarding linked modules or custom metadata fields, as seen in the above resultset. Logically these configurations can differ by publication.

5.2.2 Retrieve usage statstics

Retrieve the usage statistics of a publication to provide the user with detailed insight on created and stored media over time.

Request
/api/publication?action=getUsageStats

Result
The result consists of information concerning the available mediatypes and the total amount of created and stored items per mediatype per month.

Example

[xml]
<usage type="publicationstats">
    <mediatypes>
        <mediatype>video</mediatype>
        <mediatype>text</mediatype>
        <mediatype>audio</mediatype>
        <mediatype>image</mediatype>
        <mediatype>interactive</mediatype>
        <mediatype>document</mediatype>
        <mediatype>mainroll</mediatype>
    </mediatypes>
    <date year="2009" month="04">
        <stats type="created" usetype="editorial" mediatype="video">14</stats>
        <stats type="stored" usetype="editorial" mediatype="video">0</stats>
        <stats type="created" usetype="editorial" mediatype="text">0</stats>
        <stats type="stored" usetype="editorial" mediatype="text">0</stats>
        <stats type="created" usetype="editorial" mediatype="audio">0</stats>
        <stats type="stored" usetype="editorial" mediatype="audio">0</stats>
        <stats type="created" usetype="editorial" mediatype="image">0</stats>
        <stats type="stored" usetype="editorial" mediatype="image">0</stats>
        <stats type="created" usetype="editorial" mediatype="interactive">0</stats>
        <stats type="stored" usetype="editorial" mediatype="interactive">0</stats>
        <stats type="created" usetype="editorial" mediatype="document">0</stats>
        <stats type="stored" usetype="editorial" mediatype="document">0</stats>
        <stats type="created" usetype="editorial" mediatype="mainroll">0</stats>
        <stats type="stored" usetype="editorial" mediatype="mainroll">0</stats>
        <stats type="created" usetype="commercial" mediatype="video">0</stats>
        <stats type="stored" usetype="commercial" mediatype="video">0</stats>
        <stats type="created" usetype="commercial" mediatype="text">0</stats>
        <stats type="stored" usetype="commercial" mediatype="text">0</stats>
        <stats type="created" usetype="commercial" mediatype="audio">0</stats>
        <stats type="stored" usetype="commercial" mediatype="audio">0</stats>
        <stats type="created" usetype="commercial" mediatype="image">0</stats>
        <stats type="stored" usetype="commercial" mediatype="image">0</stats>
        <stats type="created" usetype="commercial" mediatype="interactive">0</stats>
        <stats type="stored" usetype="commercial" mediatype="interactive">0</stats>
        <stats type="created" usetype="commercial" mediatype="document">0</stats>
        <stats type="stored" usetype="commercial" mediatype="document">0</stats>
        <stats type="created" usetype="commercial" mediatype="mainroll">0</stats>
        <stats type="stored" usetype="commercial" mediatype="mainroll">0</stats>
    </date>
    <date year="2009" month="05">
        <stats type="created" usetype="editorial" mediatype="video">47</stats>
        <stats type="stored" usetype="editorial" mediatype="video">14</stats>
        ...
</usage>

5.2.3 List all publications of a publisher

Get a list of all publications related to a publisher (enterprise). For this request permisions on a publisher context are needed.

Request
/api/publication?action=list

Result
The result consists of a publications container, containg several publication containers which are formatted as can be seen in the paragaph "Get the publication config".

Example

[xml]
<publications publisherid="12" count="97">
    <publication id="3" publisherid="12" name="bb" status="active" baseurl="http://bb.bbvms.com" baseuri="/bb/media" sourcepath="/data/content/video/source">
        <fieldset name="auxiliary" type="mediaclip">
            <field type="relation" name="timelineFallback" contenttype="mediaclip" contentsubtypes="video,audio" contentusetypes="editorial" itype="relation" label="Timeline fallback clip" priority="" extendable="false" visible="true" public="true"/>
        </fieldset>
        ...
    </publication>
    <publication id="122" publisherid="12" name="demo" status="active" baseurl="http://demo.bbvms.com" baseuri="/demo/media" sourcepath="/data/content/video/demo/source">
        <statsserver>http://demo.bbvms.com/stats/</statsserver>
        <statspublication>demo</statspublication>
        ...
    </publication>
</publications>

5.2.4 Sharing between publications

Media of multiple publications can be shared between each other. To use this functionality the appropriate permissions are needed. Please contact Blue Billywig support for futher help.

Note: Media can be shared in two ways, one; media can be imported to another publication so it's possible to change the metadata or two; when embedding media the mediaclipid of the parent publication is used.

5.2.4.1 Share with another publication

Add a share with another publication.

Request
/api/publication?action=addShare

Parameter Type Description
Required parameters    
targetotype string The type of entity the share with.
targetoid int The publicationid of the publication to share with.
publicationid int Publicationid of the current publication.

Result
The result will show whether the action was successful.

Example

/api/publication?action=addShare&targetotype=publication&targetoid=1&publicationid=4

[xml]
<response code="200" error="false" id="publication">share added from publication 4 to publication 1</response>

5.2.5 Remove a share

Remove an active share with another publication

Request
/api/publication?action=removeShare

Parameter Type Description
Required parameters    
targetotype string The type of entity the share with.
targetoid int The publicationid of the publication to share with.
publicationid int Publicationid of the current publication.

Result
The result will show whether the action was successful.

Example

/api/publication?action=removeShare&targetotype=publication&targetoid=1&publicationid=4

[xml]
<response code="200" error="false" id="publication">share removed from publication 4 to publication 1</response>

5.2.5.1 List the active shares

Retrieve a list of active shares for the current publication.

Request
/api/publication?action=getShared

Result
The result consists of a publications container, containing several publication containers which are formatted as can be seen in the paragaph "Get the publication config".

Example

[xml]
<publications permission="export">
    <publication id="88" publisherid="5" name="demo" status="active" baseurl="http://demo.bbvms.com" baseuri="/demo2/media" sourcepath="/data/content/video/demo2/source">
        <statsserver>http://demo.bbvms.com/Stats/</statsserver>
        <statspublication>demo</statspublication>
    </publication>
</publications>    

5.2.6 Manage publication configurations

Managing publication configurations can be done using some general purpose actions as described in the folowing paragraphs.

Warning: Please make sure you know what you're doing. Changing or removing of configuration parameters can make the publication stop functioning.

5.2.6.1 Set a configuration

Setting or changing a configuration parameter is done with the setField action, followed by a configuration parameter and the desired value.

Request
/api/publication?action=setField

Parameter Type Description
Required parameters    
fieldname string The parameter/configuration to bet set.
fieldvalue string The desired value of the configuration.
publicationid int Id of the current publication.

Result
The result will show whether the action was successful.

Example

/api/publication?action=setField&fieldname=disablePositions&publicationid=4&fieldvalue=true

[xml]
<response code="200" error="false">field disablePositions was set to false</response>

5.2.6.2 Remove a configuration

Removing a configuration parameter is done with the removeField action, followed by the to be removed configuration parameter.

Request
/api/publication?action=removeField

Parameter Type Description
Required parameters    
fieldname string The parameter/configuration to bet set.
fieldvalue string The desired value of the configuration.
publicationid int Id of the current publication.

Result
The result will show whether the action was successful.

Example

/api/publication?action=removeField&fieldname=someparameter&publicationid=4

[xml]        
<response code="200" error="false">field someparameter was removed</response>

5.3 Private Mediaclip controller

The private mediaclip controller provides access to mediaclip metadata and provides the user with several methods to modify the metadata.

5.3.1 Retrieving metadata of a Mediaclip

Besides the public API request, the private API also provides the ability to retrieve the metadata of a mediaclip. In contrast to the public API it's possible to access all metadata of a mediaclips and also mediaclips in XML-format, which are in the status 'draft'.

5.3.1.1 JSON/JONP

To retrieve metadata in JSON format, the request doesn't differ from one done trough the public API. Only an extra parameter is used to also retrieve items which are in 'draft' status.

Request
/json/mediaclip/{id}

Parameter Type Description
Required parameters    
{id} int The id of the mediaclip.
Optional parameters    
useSession bool Use the current session, needs to be set on: true if also 'draft' items need to be accessed.

Result
If the request was successful the metadata will be returned, otherwise an error message will be shown. For example if the mediaclip doesn't exist.

Example /json/mediaclip/1075163?useSession=true

[json]
{
    id: "1075163",
    type: "MediaClip",
    mediatype: "video",
    fitmode: null,
    usetype: "editorial",
    sourcetype: "on_demand",
    originalfilename: "Daft Punk - Around The World.mp4",
    length: "243",
    sourceid: "1383047813453445yt-http://www.youtube.com/watch?v=s9MszVE7aR4",
    title: "4:3 video - Daft Punk - Around The World",
    description: null,
    deeplink: null,
    gendeeplink: "",
    copyright: null,
    author: null,
    status: "draft",
    publicationid: "1",
    createddate: "2013-10-29T11:57:04Z",
    updateddate: "2013-11-19T10:22:01Z",
    publisheddate: "2013-10-29T12:17:59Z",
    date: {
        created: "Tue, 29 Oct 2013 12:57:04 +0100",
        updated: "Tue, 19 Nov 2013 11:22:01 +0100",
        published: "Tue, 29 Oct 2013 13:17:59 +0100"
    },
    src: "/media/2013/10/29/1075163.mp4",
    cat: null,
    thumbnails: [
    {
        src: "/media/2013/10/29/1383047828810293/1383047828810293_146.jpg",
        width: "1920",
        height: "1080",
        main: "false"
    }
    ],
    assets: [
        {
            mediatype: "MP4_IPOD",
            src: "/media/2013/10/29/asset-1383047828836737.mp4",
            length: "243",
            width: "480",
            height: "352",
            bandwidth: "600"
        },
        {
            mediatype: "MPEG2",
            src: "/media/2013/10/29/asset-1383047838818658.mpg",
            length: "243",
            width: "720",
            height: "576",
            bandwidth: "6000"
        },
        {
            mediatype: "MP4_TIMELINE",
            src: "/media/2013/10/29/asset-1383047918839779.mp4",
            length: "243",
            width: "464",
            height: "352",
            bandwidth: "50"
        }
        ],
    subtitles: null,
    nametags: null,
    exports: null,
    timelines: null
}

5.3.1.2 XML

Retrieving metadata in XML format.

Request
/api/mediaclip?action=get

Parameter Type Description
Required parameters    
id int The id of the mediaclip.

Result
If the request was successful the metadata will be given, otherwise an error message will be shown. For example if the mediaclip doesn't exists.

Example
/api/mediaclip?action=get&id=1079951

The result of a request which was successful:

[xml]
<media-clip mediatype="video" usetype="editorial" sourcetype="on_demand" id="1079951" userid="0" originalfilename="PlayerPlayout_1.mp4" sourceid="" status="draft" length="89" src="/bb/media/2010/05/25/1079951.mp4" url="http://bb.bbvms.com/mediaclip/1079951.xml" title="VMS Quick Tour - Player & Playout">
<date published="Tue, 25 May 2010 14:21:33 +0200" created="Tue, 25 May 2010 14:18:40 +0200" modified="Mon, 18 Oct 2010 16:59:49 +0200"/>
<fitmode>FIT_STRETCH</fitmode>
<description>
    Hoofdstuk 2 van de VMS Quick Tour Dit hoofdstuk van de Blue Billywig quicktour
    ...
</mediaclip>

The result of a request which failed:

[xml]
<response code="404" error="true">
    mediaclip does not exist
    <messages>
        <message time="Thu, 14 Nov 13 10:42:32 +0100" context="unavailable">media-clip 10799489 does not exist
        </message>
    </messages>
</response>

See chapter [[media_content_types]] for a full description of the formatted content.

5.3.1.3 Retrieve technical information of a mediaclip

Retrieve detailed information concerning the uploaded audio or video source file for a specified mediaclip.

Request
/api/mediaclip?action=get

Parameter Type Description
Required parameters    
id int The id of the mediaclip.

Result
If the request was successful the technical information will be shown in XML format. Otherwise an error message will be shown.

Example
/api/mediaclip?action=getTechXML&id=1079951

[xml]
<?xml version="1.0" encoding="UTF-8"?>
<Mediainfo version="0.7.35">
    <File>
        <track type="General">
            <Complete_name>/data/content/video/source/1339420920463769.mp3</Complete_name>
            <Format>MPEG Audio</Format>
            <File_size>6.94 MiB</File_size>
            <Duration>5mn 0s</Duration>
            <Overall_bit_rate>192 Kbps</Overall_bit_rate>
            <Album>The Ideal Crash</Album>
            <Track_name>The Ideal Crash</Track_name>
            <Track_name_Position>05</Track_name_Position>
            <Performer>dEUS</Performer>
            <Genre>Alternative Rock</Genre>
            <Recorded_date>1999</Recorded_date>
            <Cover>Yes</Cover>
            <Cover_MIME>image/jpeg</Cover_MIME>
        </track>
        <track type="Audio">
            <Format>MPEG Audio</Format>
            <Format_version>Version 1</Format_version>
            <Format_profile>Layer 3</Format_profile>
            <Mode>Joint stereo</Mode>
            <Mode_extension>MS Stereo</Mode_extension>
            <Duration>5mn 1s</Duration>
            <Bit_rate_mode>Constant</Bit_rate_mode>
            <Bit_rate>192 Kbps</Bit_rate>
            <Channel_s_>2 channels</Channel_s_>
            <Sampling_rate>44.1 KHz</Sampling_rate>
            <Stream_size>6.88 MiB (99%)</Stream_size>
        </track>
    </File>
</Mediainfo>

5.3.1.4 Retrieve the id of a mediaclip based on a source-id

If another Asset Management System or Content Management System is linked to the VMS API and this is using environment specific id's. It's possible to add those id's into the metadata of a mediaclip, by adding the id as source-id when creating a new mediaclip. When this source-id is added to a mediaclip, it can also be found by this source-id within the VMS.

Request
/api/mediaclip?action=getId

Parameter Type Description
Required parameters    
srcid string The source id as used in another system.

Result
If the request was successful the technical information will be shown in XML format. Otherwise an error message will be shown.

Example
/api/mediaclip?includejobs=true&action=getId&srcid=2358

[xml]
<?xml version="1.0"?>
<response code="200" error="false">1075174</response>

5.3.2 Creating and modifying a Mediaclip

Modifying and creating mediaclips can be done by using the put action.
At this moment the API is only able to handle mediaclip modifications/creation with (meta)data provided in XML format. The XML needs to be structured in the same way as it's retrieved by using the get action.

If a new mediaclip, including a video upload, is created, the video will be automatically be transcoded to several formats as configured for the publication. Depending on the length of the video, the mediaclip will be ready to be published within a few minutes after reception.

Note: to be sure the XML you produce is valid, we advise to use an XML parser component, like a Dom parser for example.

Request
/api/mediaclip?action=put

Parameter Type Description
Required parameters    
id int (optional) The id of the mediaclip. If not set, the system searches for an id attribute in the posted XML.
xml string The mediaclip XML with all fields/data set that need to be modfield or created. If the XML is set trough a querystring parameter it needs to be url-encoded.

To upload/ingest files the form field Filedata needs to be set and should contain a file.

Result
If the action was successful a code 200 message will be returned. The message will contain the id of the new mediaclip.
If the action was unsuccessful a code 400 or 500 message will be returned. The description will contain a short description of the error occurred.

Examples
To create a new mediaclip an id doesn't have to be set. The file for the mediaclip needs to be included trough the Filedata form element. If the action was successful the id of the new mediaclip will be returned.
In the following example the title, source-id and author will be set. All other metadata fields will be left blank.

/api/mediaclip?action=put&xml=%3Cmedia-clip%20title%3D%22New%20mediaclip%22%20sourceid%3D%222358%22%3E%0A%09%09%3Cauthor%3EBlue%20Billywig%3C%2Fauthor%3E%0A%09%3C%2Fmedia-clip%3E

[xml]
<media-clip title="New mediaclip" sourceid="2358">
    <author>Blue Billywig</author>
</media-clip>

Note: If an element is present in the provided XML, the VMS will look for channel nodes that provide credentials to upload the content and its metadata to an external location. For example: an export to Youtube.

[xml]
<export>
    <channel type="youtube" channel="http://uploads.gdata.youtube.com/feeds/users/default/uploads" date="Mon, 02 Aug 2010 19:13:30 +0200" category="Travel" youtubeid="VQAcqsRP2iY" vmsusername="rnw_1" vmsuserid="52" status="done"/>
</export>    

To modify a medicalip the id have to be set as query-string parameter or set as attribute of the media-clip element in within the XML.
In the following example the title is changed. All already filled metadata will not be changed, so only the title.

/api/mediaclip?action=put&xml=%3Cmedia-clip%20title%3D%22Changed%20mediaclip%22%20id%3D%221075174%22%3E%3C%2Fmedia-clip%3E

[xml]
<media-clip title="Changed mediaclip" id="1075174">
</media-clip>

To modify a custom metadata field a field element needs to be added to the auxiliary-fields container as shown in the example below.

/api/mediaclip?action=put&xml=%3Cmedia-clip%20id%3D%221075174%22%3E%0A%09%20%20%3Cauxiliary-fields%3E%0A%20%20%20%20%09%3Cfield%20name%3D%22transcript%22%3E%3C!%5BCDATA%5BKeep%20in%20mind%20some%20entities%20in%20XML%20need%20to%20be%20escaped%20or%20set%20inside%20of%20a%20CDATA%20section%2C%20like%20the%20%26%20(ampersand)%20for%20instance.%5D%5D%3E%3C%2Ffield%3E%0A%20%20%20%20%09%3C%2Fauxiliary-fields%3E%20%20%0A%09%3C%2Fmedia-clip%3E

[xml]
<media-clip id="1075174">
  <auxiliary-fields>
    <field name="transcript"><![CDATA[Keep in mind some entities in XML need to be escaped or set inside of a CDATA section, like the & (ampersand) for instance.]]></field>
    </auxiliary-fields>  
</media-clip>

Thumbnails will be created automatically while transcoding the media, but can also be added using the put action. A thumbnail can be directly included in the XML, using base64 encoding. If the "main" attribute is set to true, the thumbnail will be used as main thumbnail.

[xml]
<media-clip id="1075138">
    <thumbnails>
        <thumbnail main="true" capture="true"><data>iVBORw0KGgoAAAANSUhEUgAAAS8AAAA5CAYAAABnJq3qAAAAGXRFWHRTb2Z0d2FyZQBBZG9iZSBJbWFnZVJlYWR5ccllPAAAC0RJREFUeNrsXctu40YWrW54P5ovCBuYva0vCLUPxtIi21j6AlvZBMgAI2uABJjNyP4Cy7PNwnKQvdhf0Ox9gKa/IJovSO51DnuoUpEsUnwVdQ9AyOajHrdunbq3nm+W336zVdVjvvjPf0P95i8/
                                ...  
                                +roXe0FrIeqj+P9jwEvd/CQSC461C3zAqKBAIgDMRQacIa5uwHnwl690EglT8IcAAVl4jTRuRtHIAAAAASUVORK5CYII=
            </data>
        </thumbnail>
    </thumbnails>
</media-clip>

5.3.3 Change the status of a mediaclip

To only change the status of a mediaclip use the setStatus action.

Request
/api/mediaclip?action=setStatus

Parameter Type Description
Required parameters    
id int The id of the mediaclip.
status string The desired status for the mediaclip. Possible values are 'published' or 'draft'.

Note: It's also possible to change the status for multiple mediaclips by using the idJson instead of the id parameter. The id's need to be provided in JSON format.

Result
The result will give whether the action was successful or failed.

Example
api/mediaclip?action=setStatus&id=1075174&status=published

[xml]
<response code="200" error="false">mediaclip status was succesfully set to published</response>

5.3.4 Change the use type of a mediaclip

To only change the usetype of a mediaclip use the setUseType action.

Request
/api/mediaclip?action=setUseType

Parameter Type Description
Required parameters    
id int The id of the mediaclip.
usetype string The desired usetype for the mediaclip. Possible values are 'editorial' or 'commercial'.

Note: It's also possible to change the use type for multiple mediaclips by using the idJson instead of the id parameter. The id's need to be provided in JSON format.

Result
The result will show whether the action was completed succesfully. Example
api/mediaclip?action=setUseType&id=1075174&usetype=commercial

[xml]    
<?xml version="1.0"?>
<response code="200" error="false">mediaclip usetype was successfully set to commercial</response>

5.3.5 Copying a mediaclip

To make a copy of a mediaclip the action copy is used.

Request
/api/mediaclip?action=copy

Parameter Type Description
Required parameters    
id int The id of the mediaclip.
status string The desired status for the mediaclip. Possible values are 'published' or 'draft'.
Optional parameters    
mode string The default mode is 'metadata', whereby only the metadata will be copied and a reference to the original assets will be set. By setting the mode to 'data' a full copy will be made.

Result
The result will give whether the action was completed succesfully. If the action was completed successfully, the id of the new mediaclip is included in the result.

Example
/api/mediaclip?action=copy&id=1074614&status=draft

[xml]
<?xml version="1.0"?>    
<response code="200" error="false" id="1075176">Media-clip was copied</response>

5.3.6 Existing copies of mediaclip

To see whether there are copies of a mediaclip the action getCopies is used. This is for example useful to check for references before a mediaclip will be removed.

Request
/api/mediaclip?action=getCopies

Parameter Type Description
Required parameters    
id int The id of the mediaclip.

Example
/api/mediaclip?action=getCopies&id=1074614

[xml]    
<?xml version="1.0"?>
<media-clips><media-clip id="1075176" publicationid="1"/></media-clips>

If sharing is enabled between two or more publications, the publicationid can differ.

5.3.7 Deleting a mediaclip

Deleting a mediaclip is handled in a couple of stages. If a mediaclip is removed, it isn't removed permanently and can be restored to the status 'published' or 'draft'. To permanently remove a mediaclip it needs to be purged.

5.3.7.1 Remove a mediaclip

To remove and move a mediaclip to deleted clips within the VMS GUI, the remove action is used.

Request
/api/mediaclip?action=remove

Parameter Type Description
Required parameters    
id int The id of the mediaclip.

Result
The result will give whether the action was successful or failed.

Example
api/mediaclip?action=remove&id=1075174

[xml]    
<?xml version="1.0"?>
<response code="200" error="false">mediaclip was succesfully removed</response>

5.3.7.2 Purging a mediaclip

To delete a mediaclip permanently the purge action is used.

Request
/api/mediaclip?action=purge

Parameter Type Description
Required parameters    
id int The id of the mediaclip.
absolutelySureWhatIAmDoing bool This parameter is added to prevent thoughtless removal.

Result
The result will show whether the action was completed succesfully.

Example
api/mediaclip?action=purge&id=1075174&absolutelySureWhatIAmDoing=true

[xml]    
<?xml version="1.0"?>
<response code="200" error="false">specified media-clips are scheduled to be purged</response>

5.4 Private Mediacliplist controller

The private mediacliplist controller enables retrieval of mediacliplists, attached metadata and provides several methods to modify mediacliplists.

5.4.1 Retrieving Mediacliplists data

The Private Mediacliplist Controller provides the same functionality as the public API entrance, and adds the possibility to access items with the status 'draft'.

5.4.1.1 JSON/JONP

To retrieve the mediacliplist data in JSON format the search entrance is used.

Request
/json/search?cliplistid={cliplist id}

Parameter Type Description
Required parameters    
{cliplist id} int The id of the mediacliplist.

Result
If the request was successful the mediacliplist data will be returned, otherwise an error message will be shown. For example if the mediacliplist doesn't exist.

Example
/json/search?cliplistid=1360325204666333

[json]
{
    numfound: 19,
    offset: 0,
    id: "1360325204666333",
    title: "KPN",
    description: "KPN FAQ Video's",
    status: "published",
    publicationid: 1,
    mediatype: "video",
    usetype: "editorial",
    type: "MediaClipList",
    modifieddate: "2013-11-19T13:27:42Z",
    createddate: "2013-02-08T12:06:44Z",
    published_date: "2013-11-19T13:27:42Z",
    listtype_string: "dynamic",
    publication: [
    "1"
    ],
    score: 3.46143,
    count: 19,
    items: [
        {
        id: "1074662",
        title: "stap6",
        description: "Hoe stel ik de afstandsbediening voor Interactieve TV in?",
        status: "published",
        publicationid: 1,
        mediatype: "video",
        usetype: "editorial",
        sourcetype: "on_demand",

    ...

    ],
    facets: {
        _empty_: [ ]
    },
    facet_queries: [ ]
}

5.4.1.2 XML

For retrieving mediaclipst data in XML-format a couple of modes are available, which are described in the examples below.

Request
/api/mediacliplist?action=get

Parameter Type Description
Required parameters    
id int The id of the mediacliplist.
Optional parameters    
mode string If result have to consist of the mediacliplist and the listed items, the mode parameter needs to be used with the value 'details'
limit int Limit the number of items within the mediacliplist.
offset int Use an offset in combination with the limit parameter to iterate trough the mediacliplist items.

Result
If the request was successful the mediacliplist data will be given, otherwise an error message will be shown. For example if the mediacliplist doesn't exist.

Example
/api/mediacliplist?action=get&id=1360325204666333&mode=details&limit=2&offset=2

[xml]
    <media-clips id="1360325204666333" type="dynamic" mediatype="video" status="draft" title="KPN" numfound="19" count="2">
    <description>KPN FAQ Video's</description>
    <author/>
    <copyright>KPN</copyright>
    <deeplink url=""/>
    <date published="Tue, 19 Nov 2013 14:27:42 +0100" created="Fri, 08 Feb 2013 13:06:44 +0100" modified="Tue, 19 Nov 2013 14:45:49 +0100"/>
    <auxiliary-fields>
        <field name="language"/>
    </auxiliary-fields>
    <media-clip mediatype="video" usetype="editorial" sourcetype="on_demand" id="1074655" userid="35" originalfilename="14606_stap4oudeab_B.mp4" sourceid="1511927" status="published" length="18" src="/media/2012/07/11/1074655.mp4" url="http://bb.dev.bbvms.com/mediaclip/1074655.xml" title="stap4B">
        <date published="Wed, 11 Jul 2012 13:27:02 +0200" created="Wed, 11 Jul 2012 13:27:02 +0200" modified="Thu, 30 Aug 2012 12:07:08 +0200"/>
        <fitmode>FIT_HORIZONTAL</fitmode>
        <description>
        Hoe stel ik de afstandsbediening voor Interactieve TV in?
        </description>
    ...
    </media-clip>
</media-clips>

5.5 Creating and modifying mediacliplist

Modifying and creating mediacliplists can be done by using the put action.
Also for this entity only (meta)data provided in XML format will be handled.
The XML needs to be structured in the same way as it's retrieved by using the get action. * see [media_content_types] chapter for an in depth view.

Request
/api/mediacliplist?action=put

Parameter Type Description
Required parameters    
xml string The mediacliplist XML with all fields/data set which need to be modified or created. If the XML is set trough a querystring parameter it needs to be url-encoded.
Optional parameters    
id int The id of the mediacliplist.

Result
If the action is completed successfully the just created mediacliplist will be returned in XML format.

Examples
Create a new mediacliplist.
/api/mediacliplist?action=put&xml=%3Cmedia-clips%20title%3D%22New%20static%20cliplist%22%20status%3D%22draft%22%2F%3E

[xml]
<media-clips title="New static cliplist" status="draft"/>

Modify a static mediacliplist.
/api/mediacliplist?action=put&xml=%3Cmedia-clips%20title%3D%22Static-list-example%22%20status%3D%22published%22%20id%3D%221384872333655826%22%3E%0A%09%20%20%3Ccopyright%3E%3C%2Fcopyright%3E%0A%09%20%20%3Cmedia-clip%20id%3D%222247282%22%20rank%3D%221%22%2F%3E%0A%09%20%20%3Cmedia-clip%20id%3D%222081963%22%20rank%3D%222%22%2F%3E%0A%09%20%20%3Cauxiliary-fields%3E%0A%09%20%20%20%20%3Cfield%20name%3D%22language%22%3E%3C!%5BCDATA%5B%5D%5D%3E%3C%2Ffield%3E%0A%09%20%20%3C%2Fauxiliary-fields%3E%0A%09%3C%2Fmedia-clips%3E

[xml]
<media-clips title="Static-list-example" status="published" id="1384872333655826">
  <copyright></copyright>
  <media-clip id="2247282" rank="1"/>
  <media-clip id="2081963" rank="2"/>
  <auxiliary-fields>
    <field name="language"><![CDATA[]]></field>
  </auxiliary-fields>
</media-clips>put

5.6 Deleting a mediacliplist

To delete a mediacliplist the remove action is used. If a mediacliplist is deleted, it's removed permanently, there is no way to undo a remove actions.

Request
/api/mediacliplist?action=remove

Parameter Type Description
Required parameters    
id int The id of the mediacliplist.

Result
If the action is successful a success message will be returned.

Examples
/api/mediacliplist?action=remove&id=1384872185116103

[xml]
<?xml version="1.0"?>
<response code="200" error="false">mediacliplist was successfully removed</response>

5.7 Search engine

The VMS API search engine is built on and provides a mechanism for interaction with the Apache Solr search platform. Using a query based interface it's possible to search for mediaclips, mediacliplists, and creatives (commercials). Requests on the search engine have one mandatory parameter which query.
The search engine is also publicly accessible, but items that aren't publicly available will be filtered out of the result set. The result sets can be delivered in either XML or JSON format.

Requests
There are several ways to query the Search engine.

/search

/api/search

/json/search

Parameter Type Description
Required parameters    
query string The (Solr) search query.
Optional parameters    
sort string A field name to sort the result on. The order of the sorting needs to be specified also, use asc for ascending and desc for descending sorting.
limit string Limit the result set to a number of items.
offset string Use an offset in combination with the limit parameter to iterate trough the mediacliplist items.
facetquery string A valid Solr query by which the returned data should be faceted. Multiple facet queries can be specified by using [] after each facetquery parameter.
facetfield string Set a facet field to facet on. Multiple facet fields can be specified by using [] after each facetfield parameter.
facetprefix string Set a facet prefix to filter facet results by. Only one such filter can be specified per search request.
facetLimit string Limit the results for the facet(s).
filterbyusetype string Filter on a specific usetype. For more information on usetypes see paragraph "Use types" under the chapter "Entities and data types".
filterbytype string Filter on a specific mediatype. For more information on mediatypes see paragraph "Media types" under the chapter "Entities and data types".
cliplistid string Search for a specific mediaclipcliplist. See paragraph "Retrieving Mediacliplists data" for more information.
context string Used in situations where there sharing between publications is enabled. Possible values are 'shared' and 'all'. If 'shared' is used the search will only contain shared media from other publications. When 'all' is used, the result will contain shared items and from the current publication. If this parameter isn't set the result will only contain items from the current publication.

Result
If the search is completed successfully a search result will be returned. The result is in the same format as a Solr result.

Example
Search for all mediaclips in the current publication.

/json/search?query=type:mediaclip

[json]
{
    numfound: 358,
    offset: 0,
    count: 250,
    items: [
        {
        id: "1075121",
        title: "Funny Puppy Video / Just for Fun: Fitness Blender's Unofficial Mascot, Loki",
        gendeeplink_string: "http://bb.dev.bbvms.com/view/1075121.html?woef",
        description: "r",
        status: "draft",
        publicationid: 1,
        mediatype: "video",
        usetype: "editorial",
        sourcetype: "on_demand",
        type: "MediaClip",
        originalfilename: "Funny Puppy Video / Just for Fun: Fitness Blender's Unofficial Mascot, Loki.mp4",
        modifieddate: "2013-10-07T13:47:08Z",
        createddate: "2013-09-25T13:07:24Z",
        sourceid_string: "1380114439440889yt-http://www.youtube.com/watch?v=jxs41ZxUC78&feature=player_embedded",
        mainthumbnail_string: "/media/2013/09/25/1380114450341076/1380114450341076_122.jpg",
        length_int: 152,
        assets: "[{"mediatype":"MP4_IPOD","src":"\/media\/2013\/09\/25\/asset-1380114450542232.mp4","length":"152","width":"496","height":"288","bandwidth":"600"},{"mediatype":"MP4_HD","src":"\/media\/2013\/09\/25\/asset-1380114450587582.mp4","length":"152","width":"1280","height":"720","bandwidth":"2000"},{"mediatype":"MPEG2","src":"\/media\/2013\/09\/25\/asset-1380114600351458.mpg","length":"152","width":"720","height":"576","bandwidth":"6000"},{"mediatype":"MP4_MAIN","src":"\/media\/2013\/09\/25\/asset-1380114750396034.mp4","length":"152","width":"720","height":"400","bandwidth":"50"}]",
        thumbnails: "[{"src":"\/media\/2013\/09\/25\/1380114450341076\/1380114450341076_122.jpg","width":"1920","height":"1080","main":"false"}]",
        timeline_multistring: [
        "274"
        ],
        publication: [
        "1"
        ],
        score: 0.66065365
        },
        ...
    ],
    facets: {
    _empty_: [ ]
    },
    facet_queries: { }
}

5.7.1 Query language

The Search engine provides the user with a powerful query language. By default the given term(s) will be searched full text, however by specifying : it's possible to search within fields. Multiple terms can be separated by AND (capitals) or OR (capitals) as logical operators. Groups of search terms can be formed by using '(' and ')' characters: example (id:123 OR title:123) AND (status:published OR status:draft).

The following fields are indexed by default:

  • Id
  • originalfilename
  • cat (multiple values per item possible)
  • description
  • author
  • title
  • type (MediaClip or mediacliplist)

Note: To get a detailed view on all indexed fields for mediaclips, use the getSolr action on the Private Mediaclip Controller; /api/mediaclip?action=getSolr&id={id}. Some default fields are also indexed with the postfix Sort, which can be useful for facetting.

The VMS uses the Apache Solr search engine platform. For more specific information about the query language please visit: http://wiki.apache.org/solr/SolrQuerySyntax

5.7.2 Search facets

Search facets is a powerful feature that enables zooming in to facets of a search query result.

Example A facet search on the number of items with the status 'draft' or 'published' and the number of 'live' and 'on_demand' items.
/json/search?query=type:mediaclip&limit=0&facetfield[]=statusSort&facetfield[]=sourcetypeSort&facetLimit=10

[json]
{
    numfound: 358,
    offset: 0,
    count: 0,
    items: [ ],
    facets: {
        statusSort: [
            "draft",
            120,
            "published",
            238
        ],
        sourcetypeSort: [
            "live",
            16,
            "on_demand",
            342
        ]
    },
    facet_queries: { }
}

5.7.3 Examples

In this paragraph some common searches are listed. They are provided as examples of some everyday search usage scenarios.

Find all mediaclips which are publicly available.
/json/search?query=type:mediaclip AND status:published

Find all mediaclips which are publicly available and sort ascending on the title.
/json/search?query=type:mediaclip AND status:published&sort=title_str asc

Get the 10 most viewed mediaclips.
/json/search?query=type:mediaclip AND status:published&sort=views_int desc&limit=10

Get all the items of the author "jane doe" or "john doe".
/json/search?query=author:"jane doe" OR author:"john doe"

Get all the items where there the copyright field is filled.
/json/search?query=copyright:[* TO *]

Get all mediaclips where there the description is not set.
/json/search?query=type:mediaclip AND -description:[* TO *]

Get all mediacliplists which are created within in certain period.
/json/search?query=type:MediaClipList AND createddate:[2012-05-01T01:25:08Z TO 2013-07-01T23:25:08Z]

Get all mediaclips which are of the mediatype video.
/json/search?query=type:mediaclip&filterbyusetype=editorial&filterbytype=video
Or
/json/search?query=type:mediaclip AND usetype:editorial AND mediatype:video

Get all creatives (commercials).
/json/search?query=type:mediaclip&filterbyusetype=commercial

5.8 Private player controller (read only)

The private player controller can give insight information on the players configured to the publication.

5.8.1 Retrieve a list of players

To retrieve a list of the players the list action is used.

Request
/api/player?action=list

Result
The result represents a list of players in XML format.

Example
/api/player?action=list

[xml]
<players publicationid="91" count="1">
    <player id="48" name="Blue Billywig Standard v4.3.17 " updateddate="2013-11-19 09:41:36" publicationid="0" status="active" type="swf" src="/publications/__root__/player/flash/flexplayer.swf" html5src="/publications/__root__/player/html5/generic/">
        <fieldset name="config">
            <category name="Appearance" description="">
            <subcategory name="Size" description="">
                <field type="int" name="width" itype="text" label="Width" tooltip="Use a percentage for a responsive playout (eg 100%)." priority="mandatory" extendable="" visible="">720</field>
                <field type="int" name="height" itype="text" label="Height" tooltip="Use a percentage for a responsive playout (eg 100%)." priority="mandatory" extendable="" visible="">404</field>
                <field type="boolean" name="autoHeight" itype="checkbox" label="Calculated height" tooltip="Calculate the playout height based on the given width and mediaclip aspectratio (overrides default height)." priority="stress" extendable="" visible="">
                    <options>
                        <option label="false" selected="true">false</option>
                        <option label="true">true</option>
                    </options>
                </field>
            </subcategory>
            ...
</players>

5.8.2 Retrieve data of a specific player

To retrieve data of one player the get action is used.

Request
/api/player?action=get

Parameter Type Description
Required parameters    
id int The id of a player.

Result
The result represents the configuration of a player in XML format.

Example
/api/player?action=get&id=49

[xml]
<player id="49" name="thinplayer" updateddate="2011-05-18 12:35:46" publicationid="1" status="active" type="swf" src="/publications/bb/swf/thinplayer.swf" html5src=""/>

5.9 Private playout controller

The private playout controller provides access to playout configurations and functionality to modify it.

5.9.1 Retrieve all playout configurations

To retrieve the configuartions of all playouts within a publication the list action can be used.

Request
/api/playout?action=list

Result
The result represents the configurations playouts in XML format.

Example
/api/player?action=get&id=49

[xml]
<playouts publicationid="91" count="10">
    <playout id="799" name="artikel" status="active" publicationid="91" label="artikel" playerid="48" createddate="Thu, 01 Dec 2011 14:20:49 +0100" updateddate="Wed, 16 Oct 2013 09:50:39 +0200" main="false" publication="Blue Billywig" writeprotected="false">
        <player id="48" name="Blue Billywig Standard v4.3.17 " updateddate="2013-11-19 09:41:36" publicationid="0" status="active" type="swf" src="/publications/__root__/player/flash/flexplayer.swf" html5src="/publications/__root__/player/html5/generic/"/>
            <fieldset name="config" writeprotected="false">
                <field name="width">100%</field>
                <field name="height"/>
                <field name="autoHeight">true</field>
                <field name="alphaControlBar">60</field>
                <field name="skin_backgroundColor">4170a6</field>
                <field name="skin_foregroundColor">ffffff</field>
                <field name="skin_widgetColor">e5070f</field>
                <field name="controlBar">Autohide</field>
                <field name="timeDisplay">Hide</field>
                <field name="timeLine">Show</field>
                <field name="muteButton">Show</field>
                <field name="volume">Show</field>
                <field name="volumeOrientation">vertical</field>
                <field name="languageSelect">Hide</field>
                <field name="hdButton">Hide</field>
                <field name="fullScreen">Show</field>
                ...
                </fieldset>
    </playout>
</playouts>

5.9.2 Retrieve the configuration of a playout

To retrieve the configuration of a playout the get action can be used.

5.9.2.1 JSON/JSONP

Retrieve the playout configuration in JSON format.
This request is also public available.

Request
/json/playout/{playout name}

Parameter Type Description
Required parameters    
{playout name} string The name of the playout.
Optional parameters    
callback string The desired name of the callback (JSONP).

Result
The result will show whether the action was completed succesfully. On success the playout configuration will be shown.

Example
/json/playout/default?callback=playoutConfig

[json]
playoutConfig(
    {
        id: "625",
        main: "false",
        publicationid: "91",
        type: "Playout",
        name: "default",
        label: "default",
        publication: "bb",
        player: {
            id: "48",
            name: "Blue Billywig Standard v4.3.17 ",
            type: "swf",
            src: "/publications/__root__/player/flash/flexplayer.swf",
            html5src: "/publications/__root__/player/html5/generic/"
        },
        width: "574",
        height: "300",
        autoPlay: "true",
        autoMute: "false",
        autoLoop: "false",
        alphaControlBar: "60",
        skin_backgroundColor: "ffffff",
        skin_foregroundColor: "cc0000",
        skin_widgetColor: "ffffff",
        timeDisplay: "Show progress time",
        ...
    }
)

/json/playout/default?callback=playoutConfig

5.9.2.2 XML

Retrieve the playout configuration in XML format.

Request
/api/playout?action=get

Parameter Type Description
Required parameters    
id int The id of a playout.

Result
The result will give whether the action was completed successfully. On success the playout configuration will be shown.

Example
/api/playout?action=get&id=625

[xml]
<playout id="625" name="default" status="active" publicationid="91" label="default" playerid="48" createddate="Tue, 12 Jul 2011 15:37:33 +0200" updateddate="Tue, 04 Sep 2012 11:10:12 +0200" main="false" publication="bb" writeprotected="true">
    <player id="48" name="Blue Billywig Standard v4.3.17 " updateddate="2013-11-19 09:41:36" publicationid="0" status="active" type="swf" src="/publications/__root__/player/flash/flexplayer.swf" html5src="/publications/__root__/player/html5/generic/"/>
        <fieldset name="config" writeprotected="true">
            <field name="width">574</field>
            <field name="height">300</field>
            <field name="autoPlay">true</field>
            <field name="autoMute">false</field>
            <field name="autoLoop">false</field>
            <field name="alphaControlBar">60</field>
            <field name="skin_backgroundColor">ffffff</field>
            ...
        </fieldset>
        <positions>
            <position id="461" playoutid="625" type="preroll" name="default_preroll" system="msas">
                <systems>
                    <system type="vast" subtype="dart" priority="1" label="Dart for Publishers">
                        <fieldset name="systemconfig">
                            <field name="url">
                            http://ad.doubleclick.net/pfadx/example.com/video;sz=2x2;tile=1;ord=[random]
                            </field>
                        </fieldset>
                    </system>
                </systems>
                <media-types>
                    <media-type name="video"/>
                    <media-type name="image"/>
                </media-types>
            </position>
        </positions>
</playout>

5.10 Create or change a playout configuration

Creating or changing a playout configuration can be done by using the put action. Playout (configuration) creation/modification needs to be provided in XML format. The XML needs to be structured in the same way as it's retrieved by using the get action.

Request
/api/playout?action=put

Parameter Type Description
Required parameters    
xml string The playout configuration in XML format.
Optional parameters    
id int (optional) The id of the playout, necessary for modifications. If not set, the system searches for an id attribute in the posted XML.

Result
If the action was completed succesfully, the result will contain the just created/modfied playout configuration in XMl format. On error an error message will be given.

Example
Creation of a new playout.
/api/playout?action=put&id=xml=%3Cplayout%20name%3D%22new%20playout%22%20label%3D%22new_playout%22%20status%3D%22inactive%22%20playerid%3D%224%22%20writeprotected%3D%22false%22%3E%0A%20%20%3Cfieldset%20name%3D%22config%22%2F%3E%0A%3C%2Fplayout%3E

Supplied XML

[xml]
<playout name="new playout" label="new_playout" status="inactive" playerid="4" writeprotected="false">
          <fieldset name="config"/>
</playout>

Response

[xml]
<playout id="550" name="new playout" status="inactive" publicationid="1" label="new_playout" playerid="4" createddate="Thu, 21 Nov 2013 11:00:50 +0100" updateddate="Thu, 21 Nov 2013 11:00:50 +0100" main="false" publication="bb" writeprotected="false">
    <player id="4" name="Jorick Devplayer " updateddate="2013-06-19 17:16:00" publicationid="1" status="active" type="swf" src="/publications/bb/player/flash/flexplayer-jorick.swf" html5src="/publications/bb/player/html5/generic/"/>
        <fieldset name="config" writeprotected="false"/>
</playout>

5.10.1 Delete a playout

To de delete a playout the remove action is used.

Request
/api/playout?action=remove

Parameter Type Description
Required parameters    
id int The id of the playout.

Result
The result will show whether the action was completed succesfully.

Example
/api/playout?action=remove&id=550

[xml]
<response code="200" error="false">Playout was succesfully removed</response>

5.10.2 Set the main playout

Setting a playout as the main/default playout, for example to be used in VMS generated Video sitemaps (VSEO).

Request
/api/playout?action=setMain

Parameter Type Description
Required parameters    
id int (optional) The id of the playout.

Result
The result will give whether the action was completed succesfully.

Request
/api/playout?action=setMain&id=551

[xml]
<?xml version="1.0"?>
<response code="200" error="false">Playout was made default</response>

5.11 Managing subtitles

Subtitles are always related to a mediaclip and can be available in multiple languages. To enable subtitles the desired languages need to be configured by Blue Billywig in advance. Please contact support to get subtitles set up for your publication.

The VMS supports the SRT and W3C Timed Text Message (XML) as subtitle formats.

5.11.1 Retrieving a subtitles

To retrieve the subtitles for a mediaclip the get and getSrt actions are used. Retrieving the subtitles can be done by using a mediaclip-id and language-id or by determining the the subtitle-id in the mediaclip metadata. Below the section of the mediaclip-XML is shown:

[xml]
...
<subtitles>
    <subtitle id="155" name="" default="true" publicationid="1" createddate="Fri, 16 Mar 2012 11:48:11 +0100" updateddate="Fri, 16 Mar 2012 11:48:22 +0100" isocode="en" languageid="1" languagename="English" status="published"/>
    <subtitle id="154" name="" default="false" publicationid="1" createddate="Fri, 16 Mar 2012 11:48:07 +0100" updateddate="Fri, 16 Mar 2012 11:48:22 +0100" isocode="zh-Hans" languageid="5" languagename="中文" status="published"/>
</subtitles>
...

Request Below both requests and ways of retrieving are shown.

/api/subtitle/?action=get

Parameter Type Description
Required parameters    
id int The id of the subtitle.

/api/subtitle/?action=getSrt

Parameter Type Description
Required parameters    
mediaclipid int The id of the mediaclip.
languageid int The id of the preferred language.

Result
If the request was completed succesfully the subtitles are returned, otherwise an error message will be shown.

Example
Retrieve Subtitles in W3C Timed Text Message (XML) format.

/api/subtitle/?action=getSrt&id=155

[SRT]
1
00:00:00,000 --> 00:00:11,000
.ووجدت الدراسة ان اليوان مقوم بأقل من قيمته الحقيقية بنسبة تتراوح بين 2.5 بالمئة و27.5 بالمئة

2
00:00:11,000 --> 00:00:50,000
وخلصت الدراسة التي حررها الاقتصادي سايمون ايفينت وضمت 28 تحليلا للمسألة الى أن رفع قيمة اليوان بنسبة خمسة بالمئة فقط ستنهي الفائض التجاري الصيني مع بقية العالم لكنه لن يخفض العجز التجاري الامريكي مع الصين سوى بمقدار 61 مليار دولار 
.فقط

3
00:01:18,650 --> 00:01:39,650
قالت الدراسة انه نظرا الى أن العديد من الشركات الامريكية المصدرة تشتري قطع غيار ومكونات من الصين فان رفع قيمة اليوان سيزيد من تكلفتها مما يؤدي الى تضرر الصادرات الامريكية وهو ما قد يفقد الاقتصاد 555 الف و

4
00:01:42,000 --> 00:01:43,000
نحن نقدم أفضل نظام إدارة الفيديو.

5.12 Creating or modifying subtitles

Creating or changing subtitles can be done by using the put action. Subtitles can be supplied in W3C Timed Text Message or SRT format, so the xml or srt parameter is used.

Request
/api/subtitle?action=put

Parameter Type Description
Required parameters    
mediaclipid int The id of the mediaclip.
languageid int The id of the preferred language.
xml string The subtitles in W3C Timed Text Message (XML) format.
srt string The subtitles in SRT format.
status string The status of the subtitle, possible values are 'draft' or 'published'.

Result
If the action was completed succesfully, the result will contain metadata of the just created/modfied subtitle. On error an error message will be returned.

Example
/api/subtitle?action=put&mediaclipid=1075138&languageid=1&xml=%3C%3Fxml%20version%3D%221.0%22%3F%3E%09%0A%09%3Ctt%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2006%2F10%2Fttaf1%22%3E%0A%09%09%3Cbody%3E%0A%09%09%09%3Cdiv%20xml%3Aid%3D%22subtitles%22%3E%0A%09%09%09%09%3Cp%20begin%3D%2200%3A00%3A00%3A11%22%20end%3D%2200%3A00%3A00%3A51%22%3E%3C!%5BCDATA%5BLorem%20ipsum%20dolor%20sit%20amet%2C%20consectetuer%20adipiscing%20elit.%5D%5D%3E%3C%2Fp%3E%0A%09%09%09%3C%2Fdiv%3E%0A%09%09%3C%2Fbody%3E%0A%09%3C%2Ftt%3E

Supplied XML

[xml]
<?xml version="1.0"?>    
<tt xmlns="http://www.w3.org/2006/10/ttaf1">
    <body>
        <div xml:id="subtitles">
            <p begin="00:00:00:11" end="00:00:00:51"><![CDATA[Lorem ipsum dolor sit amet, consectetuer adipiscing elit.]]></p>
        </div>
    </body>
</tt>

Response

[xml]
<?xml version="1.0"?>
<subtitle id="183" name="" default="true" publicationid="1" createddate="Thu, 21 Nov 2013 14:13:10 +0100" updateddate="Thu, 21 Nov 2013 14:13:10 +0100" isocode="en" languageid="1" languagename="English" status="draft"/>

5.12.1 Change the status of subtitle

To only change the status of a subtitle the setStatus action is used.

Request /api/subtitle?action=setStatus

Parameter Type Description
Required parameters    
id int The id of the subtitle.
status string The status of the subtitle, possible values are 'draft' or 'published'.

Result
The result will show whether the action was completed succesfully.

Example /api/subtitle?action=setStatus&id=183&status=published

[xml]
<?xml version="1.0"?>
<response code="200" error="false">status has been set to published for Subtitle 183</response>

5.12.2 Deleting a subtitle

To delete a subtitle the action remove is used.

Request /api/subtitle?action=remove

Parameter Type Description
Required parameters    
id int The id of the subtitle.

Result
The result will show whether the action was completed successfully

Example /api/subtitle?action=remove&id=183

[xml]
<?xml version="1.0"?>
<response code="200" error="false">subtitle was succesfully removed</response>

5.13 Managing nametags

As subtitles, nametags are also related to a mediaclip and can be available in multiple languages. To enable nametags the desired languages need to be configured by Blue Billywig in advance.

Since the nametag functionality doesn't differ from the subtitle functionality, below the possible requests are listed and for further information take a look in the previous paragraph "Managing subtitles".

Requests
/api/nametag/?action=get
/api/nametag/?action=getSrt
/api/nametag?action=put
/api/nametag?action=setStatus
/api/nametag?action=remove

5.14 Languages overview (Read only)

Multiple languages can be configured for a publication. Please contact Blue Billywig to configure the desired languages for your publication.

5.14.1 Retrieve the configured languages

To retrieve a list of the configured languages the list action is used.

Request /api/language?action=list

Result
If it's configured a list of languages are shown in XML format.

The result will give whether the action was successful or failed.

Example /api/language?action=list

[xml]
<?xml version="1.0"?>
<languages publicationid="91" count="2">
    <language id="93" name="Nederlands" publicationid="91" createddate="Tue, 12 Jul 2011 17:16:00 +0200" updateddate="Tue, 12 Jul 2011 17:16:00 +0200" isocode="nl" default="true" status="published"/>
    <language id="94" name="English" publicationid="91" createddate="Tue, 12 Jul 2011 17:16:00 +0200" updateddate="Tue, 12 Jul 2011 17:16:00 +0200" isocode="en" default="false" status="published"/>
</languages>

5.15 Transcoding process overview

To check whether mediaclips are ready to published, it's possible to get insight into the transcoding queue.

5.15.1 Retrieve the current active transcoding jobs

If a mediaclip (video) is just added and there needs to be checked whether the transcoding jobs are finished before a mediaclip will be made publicly available, the get_mediaclip action can be used.

Request /api/status?action=get_mediaclip

Result
If there are active transcoding jobs a list of active jobs per mediaclip will be shown in XML format. If there are no active jobs the result wil contain zero.

Example /api/status?action=get_mediaclip

[xml]
<?xml version="1.0"?>    
<media-clips count="1">
    <media-clip mediatype="video" usetype="editorial" sourcetype="on_demand" id="1075188" userid="0" originalfilename="bigBuckBunnyRs.mp4" sourceid="" status="draft" length="60" src="/media/2013/11/21/1075188.mp4" url="http://bb.dev.bbvms.com/mediaclip/1075188.xml">
        <date created="Thu, 21 Nov 2013 15:48:03 +0100" modified="Thu, 21 Nov 2013 15:48:03 +0100"/>
        <stats>
            <results>
                <mediaclip>
                    <id descr="ID">1075188</id>
                    <totalViewsAllTime descr="Total views"/>
                    <viewtime/>
                </mediaclip>
            </results>
        </stats>
        <jobs>
            <job id="17216" name="" createddate="2013-11-21 15:48:03" updateddate="0000-00-00 00:00:00" starteddate="0000-00-00 00:00:00" finisheddate="0000-00-00 00:00:00" media-clipid="1075188" queuename="bb-snapshots" jobqid="2" totaltime="18" timeleft="18" status="new"/>
            <job id="17217" name="" createddate="2013-11-21 15:48:03" updateddate="0000-00-00 00:00:00" starteddate="0000-00-00 00:00:00" finisheddate="0000-00-00 00:00:00" media-clipid="1075188" queuename="h264-480x272-800" jobqid="10" totaltime="55" timeleft="55" status="new"/>
            <job id="17218" name="" createddate="2013-11-21 15:48:03" updateddate="0000-00-00 00:00:00" starteddate="0000-00-00 00:00:00" finisheddate="0000-00-00 00:00:00" media-clipid="1075188" queuename="h264-hd-720p" jobqid="14" totaltime="153" timeleft="180.5" status="new"/>
            <job id="17219" name="" createddate="2013-11-21 15:48:03" updateddate="0000-00-00 00:00:00" starteddate="0000-00-00 00:00:00" finisheddate="0000-00-00 00:00:00" media-clipid="1075188" queuename="mpeg2-pal" jobqid="15" totaltime="39" timeleft="143" status="new"/>
            <job id="17220" name="" createddate="2013-11-21 15:48:03" updateddate="0000-00-00 00:00:00" starteddate="0000-00-00 00:00:00" finisheddate="0000-00-00 00:00:00" media-clipid="1075188" queuename="h264-768x432-800-timeline" jobqid="45" totaltime="959" timeleft="1082.5" status="new"/>
            <job id="17221" name="" createddate="2013-11-21 15:48:03" updateddate="0000-00-00 00:00:00" starteddate="0000-00-00 00:00:00" finisheddate="0000-00-00 00:00:00" media-clipid="1075188" queuename="h264-768x432-1200" jobqid="167" totaltime="68" timeleft="671" status="new"/>
            <job id="17222" name="" createddate="2013-11-21 15:48:03" updateddate="0000-00-00 00:00:00" starteddate="0000-00-00 00:00:00" finisheddate="0000-00-00 00:00:00" media-clipid="1075188" queuename="h264-1920x1080-3000" jobqid="237" totaltime="229" timeleft="866" status="new"/>
        </jobs>
    </media-clip>
</media-clips>

5.15.2 Retrieve a list of recent transcoding jobs

To retrieve an overview of recently processes transcoding jobs the get_jobs action can be used.

Request /api/status?action=get_jobs

Result
A list of transcoding jobs will be shown, containing date/time information and to which mediaclip the job is related.

Example /api/status?action=get_jobs

[xml]
<jobs>
    <job id="4426" createddate="2009-04-15 12:28:46" queuename="sorenson" jobqid="5" timestarted="2009-04-15 12:28:57" timefinished="2009-04-15 12:29:03" mediaclipid="1071571" status="transcoded" publicationid="1" workername="localhost"/>
    <job id="4427" createddate="2009-04-15 12:28:46" queuename="bb-snapshots" jobqid="2" timestarted="2009-04-15 12:29:06" timefinished="2009-04-15 12:29:12" mediaclipid="1071571" status="transcoded" publicationid="1" workername="localhost"/>
    <job id="4428" createddate="2009-04-15 12:28:46" queuename="generic-h264-640x368-1000" jobqid="3" timestarted="2009-04-15 12:29:16" timefinished="2009-04-15 12:29:54" mediaclipid="1071571" status="transcoded" publicationid="1" workername="localhost"/>
    <job id="4429" createddate="2009-04-15 12:34:07" queuename="sorenson" jobqid="5" timestarted="2009-04-15 12:34:18" timefinished="2009-04-15 12:34:29" mediaclipid="1071572" status="transcoded" publicationid="1" workername="localhost"/>
    <job id="4430" createddate="2009-04-15 12:34:07" queuename="bb-snapshots" jobqid="2" timestarted="2009-04-15 12:34:37" timefinished="2009-04-15 12:34:50" mediaclipid="1071572" status="transcoded" publicationid="1" workername="localhost"/>
    ...
</jobs>

5.16 Analytics controller (Read only)

The analytics API interface will not be backwards compatible. If you've got special wishes for automated reports in addition to the standard Excel formatted reports, please contact Blue Billwig.
For further insight in your analytics, check out the "Audience tracking" and "Analytics" sections in the VMS Dashboard.