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.