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.