Hybrik JSON Tutorial
Hybrik uses JSON files to describe media operations. JSON stands for JavaScript Object Notation, and these text-based files are an open-standard way of storing and passing structured data in a human-readable form. Files of this type use the .json extension. You do not need to know JavaScript or any programming in order to understand JSON files. For example, let’s say that we wanted to describe a car with JSON notation. That description might look like this:
{
"car": {
"year": 1965,
"make": "Ford",
"model": "Mustang",
"style": "convertible",
"color": "dark blue with white top",
"horsepower": 210
}
}
This has described a “car” object with a number of properties such as “year”, “make”, “model”, etc. Each sub-element can be a string, number, boolean, array, or another object. This allows you to create complex structures with many components.
Hybrik JSON
Every media processing operation in Hybrik can be defined with a JSON file. This file may be submitted to Hybrik via the user interface or programmatically via the API. The results of media operations are also provided by Hybrik in the form of a JSON file. So, in order to be proficient with Hybrik you will need to understand how Hybrik uses JSON to define an operation. A media processing operation might be as simple as a single transcode, or it may be a complex workflow involving many different files being assembled and creating many different outputs to various formats – each with a different set of quality assurance requirements, delivery locations, and completion notifications. All of these operations can be defined within the Hybrik JSON structure. The basic structure of a Job JSON looks like this:
- Job Info
- Name
- Priority
- Etc
- Task Element Info
- Task 1
- Task 2
- Etc.
- Connection Info
- Task 1 is connected to Task 2
- Task 2 is connected to Task 3 on success, but Task 4 on failure
- Etc.
The Task Element Info is contained within an elements array, and the Connection Info is contained in a connections array. The elements array defines the source data and all the various tasks to be executed. The connections array defines the sequence in which the various task will be executed. For example, you could define 3 different tasks: a transcode, a copy, and a notification. The connections array is going to define whether the copy happens before or after the transcode, and whether the notification happens if the transcode succeeds or only when the copy fails. By using the elements and connections arrays, you can construct even very complex media workflows.
Task Elements Array
Each element has some basic parameters, such as a unique identifier (uid) and an indicator of what type of element it is (kind). It also has a payload object that holds all the information about the particular element. Here is an element that defines a source file:
{
"uid": "source_file",
"kind": "source",
"payload": {
"kind": "asset_url",
"payload": {
"storage_provider": "s3",
"url": "s3://hybrik-examples/public/sources/sample1.mp4"
}
}
}
You will often see a replication of the kind plus payload structure throughout the Hybrik JSON. The kind tells the type of object and the payload carries the information about that object. For example, an asset_url is defining a type of asset that can be accessed by a URL. The payload for this object gives the specifics on the storage provider and the URL. If the asset had been on an FTP site, for example, then the storage_provider would be different, and the payload could include login information.
Here is an element that defines a specific transcode task:
{
"uid": "transcode_task",
"kind": "transcode",
"payload": {
"location": {
"storage_provider": "s3",
"path": "s3://my_bucket/output_folder"
},
"targets": [
{
"file_pattern": "%s.mp4",
"container": {
"kind": "mp4"
},
"video": {
"codec": "h264",
"width": 1280,
"height": 720,
"frame_rate": 29.97,
"bitrate_kb": 1200
},
"audio": [
{
"codec": "heaac_v2",
"channels": 2,
"sample_rate": 44100,
"bitrate_kb": 128
}
]
}
]
}
}
You can see that this object defines the location where the output file will be placed, the name for the output file, and the various parameters for the encode, including the container, video and audio components. Some of the components in this structure are defined by arrays using the [ ] notation. You use an array when there are potentially multiple elements in the object. For example, targets is an array, because you can specify more than one output for the transcode task. Likewise, audio is an array, since each output can have one or more audio tracks (e.g. stereo, surround, etc.). Here is an example transcode element that defines two target outputs – one SD and one HD.
{
"uid": "transcode_task",
"kind": "transcode",
"payload": {
"location": {
"storage_provider": "s3",
"path": "s3://my_bucket/output_folder"
},
"targets": [
{
"file_pattern": "{source_basename}_SD.mp4",
"existing_files": "replace",
"container": {
"kind": "mp4"
},
"video": {
"codec": "h264",
"width": 720,
"height": 480,
"frame_rate": "30000/1001",
"bitrate_kb": 600
},
"audio": [
{
"codec": "heaac_v2",
"channels": 2,
"sample_rate": 44100,
"bitrate_kb": 128
}
]
},
{
"file_pattern": "{source_basename}_HD.mp4",
"existing_files": "replace",
"container": {
"kind": "mp4"
},
"video": {
"codec": "h264",
"width": 1920,
"height": 1080,
"frame_rate": "30000/1001",
"bitrate_kb": 3600
},
"audio": [
{
"codec": "heaac_v2",
"channels": 2,
"sample_rate": 44100,
"bitrate_kb": 128
}
]
}
]
}
}
Task Connections Array
The connections array allows you to define the order of operations in a media workflow. Each task is uniquely identified by its uid, and each connection is defined by a from and a to location. After the completion of one task you may want to trigger more than one follow on task to execute simultaneously, or you may want more than one task to complete before executing a particular follow on task. For this reason, both the from and to items are defined by arrays. Additionally, you can specify what task is supposed to get executed when the previous task succeeds, and what task will get executed when the previous task has an error. Let’s look at a few examples. This first example connects the source_file element to the transcode_task element. The transcode is connected to the success path of the source, meaning that it will only execute if the source can be read successfully.
{
"connections": [
{
"from": [
{
"element": "source_file"
}
],
"to": {
"success": [
{
"element": "transcode_task"
}
]
}
}
]
}
If we wanted the source to trigger both a transcode and a copy operation the connections array might look like this:
{
"connections": [
{
"from": [
{
"element": "source_file"
}
],
"to": {
"success": [
{
"element": "transcode_task"
},
{
"element": "copy_task"
}
]
}
}
]
}
And finally, if we wanted to specify a particular notification task (such as a REST call) on an error in accessing the source file, but a different notification task on the success of the transcode operation, then the connections array would look like:
{
"connections": [
{
"from": [
{
"element": "source_file"
}
],
"to": {
"success": [
{
"element": "transcode_task"
},
{
"element": "copy_task"
}
]
,
"error": [
{
"element": "notification_on_source_error"
}
]
}
},
{
"from": [
{
"element": "transcode_task"
}
],
"to": {
"success": [
{
"element": "notification_on_transcode_success"
}
]
}
}
]
}
JSON File Editing
You can edit JSON files in any text editor, or you can use a custom JSON editor. The benefit of a JSON editor is that it will let you easily find errors. JSON is a very precise format, and it will cause an error if you leave a , in the wrong place. Using a JSON editor will also allow you to more easily modify and create your own JSON files. There are many free and paid JSON editors. Here is a list of some of tools available:
http://www.butleranalytics.com/15-json-editors-free-online-windows-mac-browser/
A JSON editor allows you to view the JSON in an object view, which is very convenient for collapsing, expanding, and restructuring your JSON hierarchy
The best way to become familiar with the Hybrik JSON file structure is to look at our examples. These files will allow you to see the basics of how Hybrik uses JSON to manage every aspect of the media processing operation. Every job in Hybrik is defined using JSON, and you can use the Export Job JSON menu item in the Job View in Hybrik to export any job as a JSON file. Once a job is complete, Hybrik also uses JSON to provide you with a complete detailed summary of the results of the job. You can access this by using the Export Job Summary menu item in the Job View.
Here is a link to some example JSON files. We encourage you to download these files and use them to begin your exploration of the the Hybrik JSON structure.