/sapi/mediaclip


/sapi/mediaclip is the endpoint for managing clip metadata. Media Clips are containers that combine:

  • File/stream references
  • Metadata
  • References to other entities (subtitles,timelines, audiotracks)

The /sapi/mediaclip is primarily intended for managing the Media Clip metadata with limited support for managing references to other entities and streams (which are manageable via their own endpoints).

1.0 | Object structure

The structure below is a JSON representation of the “Perfect cup” Media Clip that is used as the default clip for demo and configuration purposes in the Online Video Platform user interface.

Example clip metadata
{
id: "2575390",
type: "MediaClip",
mediatype: "video",
fitmode: "",
usetype: "editorial",
location: "",
sourcetype: "on_demand",
originalfilename: "The perfect cup.mp4",
length: 65,
sourceid: "",
title: "The perfect coffee",
description: "This video is about coffee, one of the most appreciated drinks in the world.",
deeplink: "",
gendeeplink: "",
copyright: "Blue Billywig",
author: "Billy",
status: "published",
publicationid: "325",
createddate: "2016-01-07T12:30:42Z",
updateddate: "2018-03-23T15:29:13Z",
publisheddate: "2016-01-07T12:39:27Z",
views: 7946,
createdBy: "support@bluebillywig.com",
updatedBy: "support@bluebillywig.com",
date:
{
created: "Thu, 07 Jan 2016 13:30:42 +0100",
updated: "Fri, 23 Mar 2018 16:29:13 +0100",
published: "Thu, 07 Jan 2016 13:39:27 +0100"
},
src: "/ovp/media/2016/01/07/1452171776257275.mp4",
cat:
[
"coffee",
"beverage",
"how to"
],
thumbnails:
[
{
src: "/ovp/media/2016/01/07/1452169859543171/2575390-1452169859543171_38.jpg",
width: "1920",
height: "1080",
main: false
},
{
src: "/ovp/media/2016/01/07/1452171780154429/2575390-1452171780154429_15.jpg",
width: "1920",
height: "1080",
main: true
},
 
 
 
 
 
 
 
 
],
assets:
[
{
mediatype: "MP4_MAIN",
id: "1452171780061519",
status: "active",
src: "/ovp/media/2016/01/07/asset-1452171780061519.mp4",
length: "65",
exactlength: "65040",
width: "1280",
height: "720",
bandwidth: "2000",
jobdefid: "2632"
},
{
mediatype: "MP4_MAIN",
id: "1452171780108853",
status: "active",
src: "/ovp/media/2016/01/07/asset-1452171780108853.mp4",
length: "65",
exactlength: "65040",
width: "768",
height: "432",
bandwidth: "1600",
jobdefid: "2633"
},
{
mediatype: "MP4_IPOD",
id: "1452171780198779",
status: "active",
src: "/ovp/media/2016/01/07/asset-1452171780198779.mp4",
length: "65",
exactlength: "65040",
width: "512",
height: "288",
bandwidth: "400",
jobdefid: "2637"
},
{
mediatype: "MP4_IPOD",
id: "1452171780246670",
status: "active",
src: "/ovp/media/2016/01/07/asset-1452171780246670.mp4",
length: "65",
exactlength: "65040",
width: "768",
height: "432",
bandwidth: "800",
jobdefid: "2639"
},
{
mediatype: "MP4_TIMELINE",
id: "1452171780311302",
status: "active",
src: "/ovp/media/2016/01/07/asset-1452171780311302.mp4",
length: "65",
exactlength: "65040",
width: "720",
height: "400",
bandwidth: "600",
jobdefid: "2640"
},
{
mediatype: "MP4_HD",
id: "1452171780368141",
status: "active",
src: "/ovp/media/2016/01/07/asset-1452171780368141.mp4",
length: "65",
exactlength: "65040",
width: "1920",
height: "1080",
bandwidth: "3000",
jobdefid: "2641"
},
{
mediatype: "MP4_MAIN",
id: "1452182303094440",
status: "active",
src: "/ovp/media/2016/01/07/asset-1452182303094440.mp4",
length: "65",
exactlength: "65040",
width: "1280",
height: "720",
bandwidth: "2000",
jobdefid: "2632",
language-id: "669",
language-name: "English",
language-isocode: "en",
isDefaultLanguage: false
},
{
mediatype: "MP4_MAIN",
id: "1452182303148309",
status: "active",
src: "/ovp/media/2016/01/07/asset-1452182303148309.mp4",
length: "65",
exactlength: "65040",
width: "768",
height: "432",
bandwidth: "1600",
jobdefid: "2633",
language-id: "669",
language-name: "English",
language-isocode: "en",
isDefaultLanguage: false
},
{
mediatype: "MP4_IPOD",
id: "1452182303201988",
status: "active",
src: "/ovp/media/2016/01/07/asset-1452182303201988.mp4",
length: "65",
exactlength: "65040",
width: "512",
height: "288",
bandwidth: "400",
jobdefid: "2637",
language-id: "669",
language-name: "English",
language-isocode: "en",
isDefaultLanguage: false
},
{
mediatype: "MP4_IPOD",
id: "1452182303250550",
status: "active",
src: "/ovp/media/2016/01/07/asset-1452182303250550.mp4",
length: "65",
exactlength: "65040",
width: "768",
height: "432",
bandwidth: "800",
jobdefid: "2639",
language-id: "669",
language-name: "English",
language-isocode: "en",
isDefaultLanguage: false
},
{
mediatype: "MP4_HD",
id: "1452182303302356",
status: "active",
src: "/ovp/media/2016/01/07/asset-1452182303302356.mp4",
length: "65",
exactlength: "65040",
width: "1920",
height: "1080",
bandwidth: "3000",
jobdefid: "2641",
language-id: "669",
language-name: "English",
language-isocode: "en",
isDefaultLanguage: false
}
],
hasJobs: true,
hasFailedJobs: false,
hasRunningJobs: false,
hasNewJobs: false,
transcodingFinished: true,
isYoutubeImport: false,
subtitles:
[
{
languageid: "669",
languagename: "English",
id: "6433",
name: "",
default: "false",
isocode: "en",
status: "published"
},
{
languageid: "670",
languagename: "Nederlands",
id: "6435",
name: "",
default: "true",
isocode: "nl",
status: "published"
}
],
nametags: null,
exports: null,
timelines: null,
audiotracks:
[
{
id: "7",
publicationid: "325",
type: "AudioTrack",
status: "published",
createddate: "2016-01-07T15:58:16Z",
updateddate: "2016-01-07T15:58:22Z",
languageid: 669,
mediaclipid: "2575390",
src: "/media/2016/01/07/d1b8c2e6a6205d4af2e686a04496e540/alt-audio.mp3",
exactlength: "65123 ",
isocode: "en",
name: "English",
IsDefaultLanguage: false
}
],
 
 
}

2.0 | Create/Update

PUT /sapi/mediaclip

Example payload
{
type: "MediaClip",
id:  "1234",
mediatype: "video",
fitmode: "",
usetype: "editorial",
sourcetype: "on_demand",
originalfilename: "The perfect cup.mp4",
thumbnails:
[
{
src: "/media/2018/08/01/1082435-1533119035067293/1082435-1533119035067293_11.jpg",
width: "1920",
height: "1080",
main: true
},
{
src: "/media/2018/08/01/1082435-1533119035067293/1082435-1533119035067293_14.jpg",
width: "1920",
height: "1080",
main: false
}
]
length: 65,
 
 
 
sourceid: "my-unique-sourceid",
title: "The perfect coffee",
description: "This video is about coffee, one of the most appreciated drinks in the world.",
deeplink: "",
copyright: "Blue Billywig",
author: "Billy",
status: "published",
}

If the id property is left out the above example JSON will register a new empty mediaclip with sourceid “my-unique-sourceid”. If the id property is left in an update of the clip with id “1234” is attempted. The response will contain the entire created or updated mediaclip object.

The easiest way to add a video or audio file to this newly created mediaclip object is to upload the file to the AWS S3 source bucket (s3://mm..bbvms.com/upload//SOURCEID.extension) For this to oocer, an ingest pattern and “assumed user id” must be set up. Contact support@bluebillywig.com to get this set up for you.

After a file is uploaded, it will automatically be attached to your new Media Clip.

3.0 | Object structure

Mediaclip is the main content type in the Blue Billywig Online Video Platform. It consists of a set standard properties:

PropertyDescription
Type(fixed) MediaClip. Read-only.
IdThe ID of the mediaclip. Read-only.
MediatypeAudio, video, image or document. Read-only.
FitmodeOnly used for video. Contains the fit mode for displaying the video content. Read/write.
UsetypeEditorial or commercial. Commercial is only used for creatives or logos. Read/write.
OriginalfilenameThe original filename of the attached audiovisual file. Read/write
LengthThe length in seconds. Read/write.
CreateddateThe time and date the mediaclip was created. Read-only.
UpdateddateThe last updated date and time for a mediaclip. Read-only.
PublisheddateThe date and time the mediaclip was first set to status published. Read-only.
SourceidAn external ID pointing to a source system of (part of) an ingested file name. Read-only (after initial ingest)
TitleThe clip title. Read/write.
DescriptionThe clip description text. Read/write.
DeeplinkThe “home url” of a clip. Read/write.
AssetsA list of stream files/versions/renditions. Mutable only on creation. After that manageable via /sapi/mediaasset endpoint.
ThumbnailsA list of images related to the mediaclip. Attributes: src (a file uri reference), main (true for the selected thumbnail and false for others), width (in pixels), height (in pixels).
StatusDraft or published. If a mediaclip has status published it will be publicly available.
transcodingFinishedWhen true transcoding is finished for this clip. Read-only.

4.0 | Retrieve

GET /sapi/mediaclip

Retrieves a list of mediaclips. By default a list of the 15 most recently created clips will be returned.

4.1 | Params

ParameterDescriptionExample
q(string) specify a query to select a subset?q=title:”my fantastic new title”
sort(string fieldname string direction) determine sorting field and direction (default is id desc)?sort=title asc
limit(integer) determine the number of mediaclips to return?limit=100
offset(integer) determine an offset to start the list?offset=100

4.2 | Result

An items container containing the requested MediaClip objects.

GET /sapi/mediaclip/ID

Retrieves a complete mediaclip object containing all references and metadata properties.

5.0 | Delete

DELETE /sapi/mediaclip/ID

Will cause a mediaclip to be moved to the “thrash can”.

5.1 | Params

ParameterDescription
purge=trueThe switch ?purge=true will permanently delete a mediaclip

 

Updated on July 9, 2020

Was this article helpful?

Related Articles