/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": "4471615",
"type": "MediaClip",
"mediatype": "video",
"fitmode": "",
"usetype": "editorial",
"location": "",
"sourcetype": "on_demand",
"originalfilename": "perfectcoffee.mp4",
"length": 30,
"sourceid": "",
"title": "The perfect coffee",
"description": "\"This video is about coffee, one of the most appreciated drinks in the world.\"",
"deeplink": "",
"gendeeplink": null,
"copyright": "Blue Billywig",
"author": "Billy",
"status": "published",
"publicationid": "325",
"createddate": "2021-11-29T14:20:37Z",
"updateddate": "2021-12-01T16:02:40Z",
"publisheddate": "2021-11-29T14:20:37Z",
"views": 7946,
"width": 1920,
"height": 1080,
"dar": "16:9",
"originalWidth": 1920,
"originalHeight": 1080,
"createdBy": "support@bluebillywig.com",
"updatedBy": "support@bluebillywig.com",
"date": {
"created": "Mon, 29 Nov 2021 15:20:37 +0100",
"updated": "Wed, 01 Dec 2021 17:02:40 +0100",
"published": "Mon, 29 Nov 2021 15:20:37 +0100"
},
"src": "/yourcompanyname/media/2021/11/29/4471615.mp4",
"cat": null,
"thumbnails": [
{
"src": "/yourcompanyname/media/2021/12/01/4471615-1638374527283123.jpg",
"width": "1920",
"height": "1080",
"main": true
},
{
"src": "/yourcompanyname/media/2021/12/01/4471615-1638374527877789.jpg",
"width": "1920",
"height": "1080",
"main": false
}
],
"assets": [
{
"mediatype": "MP4_MAIN",
"id": "1638195639053212",
"status": "active",
"src": "/yourcompanyname/media/2021/11/29/asset-4471615-1638195592823702.mp4",
"length": "30",
"exactlength": "30656",
"width": "1280",
"height": "720",
"bandwidth": "2000",
"mimetype": "video/mp4; codecs=\"avc1.4d481f, mp4a.40.2\""
},
{
"mediatype": "MP4_MAIN",
"id": "1638195647908785",
"status": "active",
"src": "/yourcompanyname/media/2021/11/29/asset-4471615-1638195593447920.mp4",
"length": "30",
"exactlength": "30656",
"width": "768",
"height": "432",
"bandwidth": "1600",
"mimetype": "video/mp4; codecs=\"avc1.4d481e, mp4a.40.2\""
},
{
"mediatype": "MP4_IPOD",
"id": "1638196141113211",
"status": "active",
"src": "/yourcompanyname/media/2021/11/29/asset-4471615-1638195593297721.mp4",
"length": "30",
"exactlength": "30656",
"width": "512",
"height": "288",
"bandwidth": "400",
"mimetype": "video/mp4; codecs=\"avc1.42c015, mp4a.40.2\""
},
{
"mediatype": "MP4_IPOD",
"id": "1638195645310660",
"status": "active",
"src": "/yourcompanyname/media/2021/11/29/asset-4471615-1638195543584388.mp4",
"length": "30",
"exactlength": "30656",
"width": "768",
"height": "432",
"bandwidth": "800",
"mimetype": "video/mp4; codecs=\"avc1.42c01e, mp4a.40.2\""
},
{
"mediatype": "MP4_HD",
"id": "1638775644375364",
"status": "active",
"src": "/yourcompanyname/media/2021/11/29/asset-4471615-1638195593736415.mp4",
"length": "30",
"exactlength": "30656",
"width": "1920",
"height": "1080",
"bandwidth": "3000",
"mimetype": "video/mp4; codecs=\"avc1.4d4828, mp4a.40.2\""
}
],
"hasJobs": false,
"subtitles": null,
"transcript": null,
"nametags": null,
"exports": null,
"timelines": null,
"adunits": null,
"audiotracks": null,
"isPrefetch": true,
"replacesrc": "/yourcompanyname/media/2021/11/29/4471615.mp4",
"s3Info": "{\"ResponseMetadata\": {\"RequestId\": \"QEMH92J5KSVVR17X\", \"HostId\": \"9qFbkjxZZhQ2AoyI0w7MJMJbyeMm/yIl4AkYvaFtX7QlAJh7AzhUaVE7602y4B85Z27HqoRvwQw=\", \"HTTPStatusCode\": 200, \"HTTPHeaders\": {\"x-amz-id-2\": \"9qFbkjxZZhQ2AoyI0w7MJMJbyeMm/yIl4AkYvaFtX7QlAJh7AzhUaVE7602y4B85Z27HqoRvwQw=\", \"x-amz-request-id\": \"QEMH92J5KSVVR17X\", \"date\": \"Mon, 29 Nov 2021 14:19:52 GMT\", \"last-modified\": \"Mon, 29 Nov 2021 14:19:42 GMT\", \"etag\": \"\\\"90bd06850bdc1d4d95268a639042313f-4\\\"\", \"x-amz-meta-uploadidentifier\": \"99fa37bc6bdfb84ab7c7f98f9bc5c2ca\", \"x-amz-meta-qqfilename\": \"sample-mp4-1.mp4\", \"content-disposition\": \"attachment; filename=sample-mp4-1.mp4\", \"accept-ranges\": \"bytes\", \"content-type\": \"video/mp4\", \"server\": \"AmazonS3\", \"content-length\": \"17840930\"}, \"RetryAttempts\": 0}, \"AcceptRanges\": \"bytes\", \"LastModified\": \"2021-11-29T14:19:42+00:00\", \"ContentLength\": 17840930, \"ETag\": \"\\\"90bd06850bdc1d4d954d6a639042313f-4\\\"\", \"ContentDisposition\": \"attachment; filename=sample-mp4-1.mp4\", \"ContentType\": \"video/mp4\", \"Metadata\": {\"uploadidentifier\": \"99fa37bc6bdfb84ab7c7f98f9bc5c2ca\", \"qqfilename\": \"sample-mp4-1.mp4\"}, \"publication\": \"screencaptures\", \"format\": {\"filename\": \"https://s3.eu-west-1.amazonaws.com/mm.screencaptures.bbvms.com/upload/screencaptures/2021/11/29/99fa37bc6bdfb8a61b7c7f98f9bc5c2ca/99fa37bc6bdfb84ab7c7f98f9bc7yyca.mp4\", \"nb_streams\": 2, \"nb_programs\": 0, \"format_name\": \"mov,mp4,m4a,3gp,3g2,mj2\", \"format_long_name\": \"QuickTime / MOV\", \"start_time\": \"0:00:00.000000\", \"duration\": \"0:00:30.526667\", \"size\": \"17.014437 Mibyte\", \"bit_rate\": \"4.675500 Mbit/s\", \"probe_score\": 100, \"tags\": {\"major_brand\": \"mp42\", \"minor_version\": \"0\", \"compatible_brands\": \"mp42mp41isomavc1\", \"track\": \"0\", \"artist\": \"Test Artist Metadata\", \"album\": \"\", \"comment\": \"\", \"date\": \"0\", \"genre\": \"\", \"title\": \"sample-mp4-1.mp4\", \"creation_time\": \"2015-08-07T09:13:36.000000Z\"}}, \"bucket\": \"mm.screencaptures.bbvms.com\", \"key\": \"upload/screencaptures/2021/11/29/46fa34d66bdfb84ab7c7f98f9bc5c2ca/99fa37bc6bdfb84ab4d69sf98f9bc5c2ca.mp4\"}",
"playoutoverride": null
}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. For this to occur, an ingest pattern and “assumed user id” must be set up. Contact support@bluebillywig.com.
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:
| Property | Description |
| type | (fixed) MediaClip. Read-only. |
| id | The ID of the mediaclip. Read-only. |
| mediatype | Audio, video, image or document. Read-only. |
| fitmode | Only used for video. Contains the fit mode setting to override the playout fitmode configuration. Read/write. |
| usetype | Editorial or commercial. Commercial is only used for creatives or logos. Read/write. |
| originalfilename | The original filename of the attached audiovisual file. Read/write |
| length | The length in seconds. Read/write. |
| createddate | The time and date the mediaclip was created. Read-only. |
| updateddate | The last updated date and time for a mediaclip. Read-only. |
| publisheddate | The date and time the mediaclip was first set to status published. Read-only. |
| sourceid | An external ID pointing to a source system of (part of) an ingested file name. Read-only (after initial ingest) |
| title | The clip title. Read/write. |
| description | The clip description text. Read/write. |
| deeplink | The “home url” of a clip. Read/write. |
| assets | A list of stream files/versions/renditions. Mutable only on creation. After that manageable via /sapi/mediaasset endpoint (learn more about the sapi/mediaasset endpoint) |
| thumbnails | A 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). |
| status | Draft or published. If a mediaclip has status published it will be publicly available. |
| transcodingFinished | When true transcoding is finished for this clip. Read-only. |
| views | All time views |
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
| Parameter | Description | Example |
| q | (string) specify a query to select a subset | ?q=title:”my fantastic new title” ?q=createddate:[2018-12-31T22:59:59Z TO 2019-12-31T22:59:29Z] |
| 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 “trash can”.
5.1 | Params
| Parameter | Description |
| purge=true | The switch ?purge=true will permanently delete a mediaclip |