Stitching Tutorial
Hybrik allows for much more complex transcoding operations than simply converting one file to another. One important capability is the ability to stitch multiple input files into a single output file. These input files do not need to even have the same frame rate, size, or format – Hybrik takes care of the details. The stitching utilizes a concept in Hybrik known as the complex asset (or asset_complex). The stitching of multiple files together is just one of the advanced capabilities that are available when you understand a complex asset type. Other capabilities include:
- Combining audio and video tracks from different sources
- Merging still frames or segmented videos into a single input
- Remapping and re-assigning audio tracks
- Multiplexing discrete subtitle and closed-captioning sources into finished output files
In this tutorial, we will only cover how to stitch multiple input files into a single source. Please see our other tutorials for more information on other use cases. You should already be familiar with Hybrik’s JSON structure before going further. If not, please take a few minutes to read the Hybrik JSON Tutorial before continuing.
The Complex Asset
When you are simply converting one file to another, you will typically use the asset_url designator in the JSON. This says that you have a single file, and it can be found with a URL. An example looks like this:
{
"uid": "source_file",
"kind": "source",
"payload": {
"kind": "asset_url",
"payload": {
"storage_provider": "s3",
"url": "s3://my_bucket/my_folder/my_file.mp4"
}
}
}
When you want to do more complex operations like stitching, you need to use the asset_complex designator. Here is an example that stitches two separate files into a single file. In our example, both files are in the same S3 folder and are called file1.mp4 and file2.mov:
{
"uid": "source_file",
"kind": "source",
"payload": {
"kind": "asset_complex",
"payload": {
"location": {
"storage_provider": "s3",
"path": "s3://my_bucket/my_folder"
},
"asset_versions": [
{
"asset_components": [
{
"kind": "name",
"name": "file1.mp4"
}
]
},
{
"asset_components": [
{
"kind": "name",
"name": "file2.mov"
}
]
}
]
}
}
}
Asset Versions and Asset Components
Complex assets contain asset_versions arrays, each of which defines one of the source clips to be stitched. Each asset_version has an asset_components array, where the source media for the clip is defined; this contains references to one or more source components (such as audio, video, and caption source assets) that will be combined together into a source clip. In the example above, each asset_version has only one component.
You will also notice that each element in the asset_components array contains an object with a kind value. In our previous example, we used name as the value for kind. Other values include list, template, image_sequence, binary_sequence, and asset_sequence. These are used when you have sources of different types. For example, if you had an asset that consisted of thousands of .png files, called animation0001.png, animation0002.png, etc. that you wanted to transcode into a single output, you could specify it in this way:
{
"uid": "source_file",
"kind": "source",
"payload": {
"kind": "asset_complex",
"payload": {
"asset_versions": [
{
"location": {
"storage_provider": "s3",
"path": "s3://my_bucket/my_folder"
},
"asset_components": [
{
"kind": "image_sequence",
"image_sequence": {
"base": "animation%04d.png"
}
}
]
}
]
}
}
}
Trim and Stitch
When stitching multiple files together, you may often find that you do not want an entire file but rather pieces of it. For example, suppose you want to take a 30 second trailer and insert it into the beginning of another file. You can use the trim designator on a source within in your complex asset. If you have not already read the Trimming Tutorial, you should take a moment to look at it now. The trim object allows you to specify a particular segment of a video, defined by an inpoint and an outpoint (or an inpoint and a duration). These inpoints and outpoints may be defined in seconds, timecode, or frames.
Here is our first stitching example again, except this time we are using only the first 30 seconds of the first file:
{
"uid": "source_file",
"kind": "source",
"payload": {
"kind": "asset_complex",
"payload": {
"location": {
"storage_provider": "s3",
"path": "s3://my_bucket/my_folder"
},
"asset_versions": [
{
"asset_components": [
{
"kind": "name",
"name": "file1.mp4",
"trim": {
"inpoint_sec": 0,
"outpoint_sec": 30
}
}
]
},
{
"asset_components": [
{
"kind": "name",
"name": "file2.mov"
}
]
}
]
}
}
}
And now suppose that instead of inserting the 30 seconds into the second file, we actually want to replace the first 30 seconds of our second file with the 30 secondes from our first file. The JSON would look like this:
{
"uid": "source_file",
"kind": "source",
"payload": {
"kind": "asset_complex",
"payload": {
"location": {
"storage_provider": "s3",
"path": "s3://my_bucket/my_folder"
},
"asset_versions": [
{
"asset_components": [
{
"kind": "name",
"name": "file1.mp4",
"trim": {
"inpoint_sec": 0,
"outpoint_sec": 30
}
}
]
},
{
"asset_components": [
{
"kind": "name",
"name": "file2.mov",
"trim": {
"inpoint_sec": 30
}
}
]
}
]
}
}
}
Stitching Sample JSON
Here is an example that stitches 5 seconds of bars and tone into the beginning of a movie.