developer documentation r17362
Videomixer API
The videomixer allows you to cut, stitch and mix video and audiotracks together. This API allows you to create video mashup tools and simple tools for post processing.
The videomixer works by sending an edit decision list to /services/mixersubmit. The EDL should be formatted as JSON, and only works with media already submitted earlier to the system. If you want to allow users to send in new files, it means you should work with the upload API to submit a new file and get a new media id.
Example request
POST /services/mixersubmit HTTP/1.1
Host: www.filemobile.com
Content-type: application/json
{
"version" : "1.0",
"title" : "My mashup",
"channel" : 1234, // A mediafactory channel id
"description" : "This is a mashup of your mom",
"tags" : [ "mom", "coffee" ],
"aspectRatio" : "4:3" // Only 4:3 and 16:9 are supported. If nothing is supplied, 4:3 is assumed
"metadata" : {
"yourimportantinfo" : "somevalue"
},
"clips" : [
{
"mid" : 123456, // This is a media-id from our system
"clipStart" : 0, // This is optional.. if left out, 0 is assumed
"clipDuration" : 600, // The number of frames we use for this clip, if left empty, the entire video is assumed
"startFrame" : 0, // Required, when the clip starts
"type" : "AV", // Using this property you can specify if you either want to use the videostream, audiostream or both (required!)
},
{
"mid" : 123457, // This is a media-id from our system
"startFrame" : 0, // Required, when the clip starts
"type" : "A" // Using this property you can specify if you either want to use the videostream, audiostream or both (required!)
}
]
}
Note: there are comments insterted in the JSON, but they are actually not allowed and should be removed
We'll get into the details of all the values later, but this EDL will generate a new video with a new audio track. The video is cut off after 600 frames.
Behaviour
The videomixer always works on 30fps. Every timeunit is actually measured in frames for this reason. Our reasoning was this would give more accurate results with syncing. This doesn't mean input files have to be 30fps, as these will be converted.
Every frame MUST have a videoframe, and an error will be thrown if this is not the case. Not every frame needs an audio track. If there's no audio track we'll just mix some silence in.
Every 'clip' needs to have a startFrame. You can optionally add in a clipDuration, which cuts off the clip after a certain number of frames. If clipDuration is not set, the entire length of the clip will be used.
If two video-clips are specified, and the second sits on top of the first video, the second video will overwrite the frames of the first. Therefore it's never really needed to specifiy clipDuration, because the next video will just take over on the specified startFrame.
If two audio-clips play on the same frame, the 2 audio tracks will be mixed together. It's therefore important to cut off the audio when needed. The more audio tracks overlap, the more separate channels are needed to mix all the tracks. This will degrade the quality of the audio. There is currently a limitation of 3 audiotracks playing at the same time. If there are more, the Mixer API will throw an error.
Advanced audio mixing
{
"version": "1.0",
"title" : "My mashup2",
"tags" : [ "mom", "coffee" ],
"clips" : [
{
"mid" : 123456, // This is a media-id from our system
"clipStart" : 0, // This is optional.. if left out, 0 is assumed
"clipDuration" : 600, // The number of frames we use for this clip, if left empty, the entire video is assumed
"startFrame" : 0, // Required, when the clip starts
"type" : "AV" // Using this property you can specify if you either want to use the videostream, audiostream or both (required!)
},
{
"mid" : 123457, // Background music
"startFrame" : 0,
"type" : "A"
},
{
"mid" : 123459, // Voiceover #1
"startFrame" : 60, // Starts at 60th frame (2nd second) (that sounds funny when you pronounce it)
"type" : "A",
"pan" : -1.0 // This guy will speak to us from the left-channel (values range from -1.0 for the left channel to 1.0 for the right channel)
},
{
"mid" : 123476, // Voiceover #2
"startFrame" : 60,
"type" : "A",
"pan" : 1.0 // This guy will speak to us from the right-channel
}
]
}
Note: there are comments insterted in the JSON, but they are actually not allowed and should be removed
Settings reference
| name | type | required | default | parent | description |
|---|---|---|---|---|---|
| version | string | yes | N/A | root | Must be 1.0. |
| title | string | yes | N/A | root | Title of newly created mix. |
| channel | integer | no | 0 | root | channelid for new mix. |
| description | string | no | empty | root | Description of the mix. This is generally user-defined. |
| tags | array of strings | no | [] | root | User-defined keywords associated with the mix. |
| aspectRatio | string | no | 4:3 | root | Aspect ratio of the mix. Only 4:3 and 16:9 are currently suppported. |
| metadata | object | no | {} | root | User-defined meta-data. See Meta data. |
| clips | array of objects | yes | N/A | root | The list of actual clips to mix. |
| clipStart | integer | no | 0 | clips | Startframe within the clip. Use this to cut off a part of the beginning of the file. |
| clipDuration | integer | no | -1 | clips | The number of frames to play this clip for. Use -1 to play the clip until the end. |
| startFrame | integer | yes | N/A | clips | When to start the clip within the mix. For example, specify 18000 to start the clip after 10 minutes. |
| type | string | yes | N/A | clips | A = audio, V = video, AV = audio + video. |
| pan | float | no | 1.0 | clips | panning (ranging from -1.0 for the left channel to 1.0 for the right channel). |