Cropping
A common operation during video transcoding is to crop the video to either
- remove unwanted material from the edges
- better fit the input video to the output aspect ratio
Hybrik gives you complete control over this cropping operation, and supports a number of key features to allow you to achieve precisely the effect you want. In order to perform the cropping operation correctly, you first need to understand how the transcoding pipeline functions. Here is the basic sequence of operations.
- Decode source video
- Perform source filter operations
- Transform to target specifications: size, frame rate, etc.
- Perform target filter operations
- Encode video
Because of this pipeline, there are two different places that you can apply a crop operation: the source side and the target side. Remember that the default behavior of Hybrik is always to preserve every pixel in the video. Therefore if you want your video to be cropped you need to explicitly tell Hybrik to do so.
Source vs Target Cropping
Let’s begin with a transcode that is converting a 16:9 source video into a 4:3 output video. Since the default behavior is to preserve every pixel, the source to target transform would look like this:
If we apply a crop to the left and right of the source image, we can make it better fit our 4:3 output. But, if we were to apply that same crop on the target side, it would be cropping the image after it has already been scaled to the output size. When would you use a target side crop? An example would be when you were taking 16:9 source and going out to a 16:9 target, but wanted to give the impression that it was a 2.4:1 shot. Then you could crop the 16:9 output to add a letterbox effect. Note that the source vs. target difference in cropping also applies to all video filters. Depending on the effect you wish to achieve, you might need to apply a filter in one location or another.
Source Cropping Example
In this example, we want to perform a transcode on some source material which is 2.4:1 aspect ratio and our output is a 16:9 aspect ratio. If we just do the default behavior, remember that Hybrik will letterbox the material. So, we want to specify that we are going to crop the source on the left and right sides. This uses the source_pipeline feature, which allows you to insert filters into the source side of the transcoding pipeline. Note that cropping can be specified in exact pixels or as a percentage of the overall picture. If you specify pixels, remember that the effect will be different depending on the resolution of your source.
...
{
"uid": "transcode_task",
"kind": "transcode",
"payload": {
"location": {
"storage_provider": "s3",
"path": "s3://path/to/output"
},
"source_pipeline": {
"filters": [
{
"video": [
{
"kind": "crop",
"payload": {
"top": 0,
"bottom": 0,
"left": "20%",
"right": "20%"
}
}
]
}
]
},
...
Target Cropping Example
In this example, let’s say that we want to crop 20 pixels off of the top and bottom of the output image (replaced with black) to give a letterboxing effect to the output.
{
"uid": "transcode_task",
"kind": "transcode",
"payload": {
"location": {
"storage_provider": "s3",
"path": "s3://path/to/output"
},
"targets": [
{
"file_pattern": "letterbox.mp4",
"existing_files": "replace",
"container": {
"kind": "mp4"
},
"video": {
"codec": "h264",
"width": 1280,
"height": 720,
"bitrate_kb": 1000,
"filters": [
{
"kind": "crop",
"payload": {
"left": 0,
"right": 0,
"top": 20,
"bottom": 20
}
}
]
},
"audio": [
{
"codec": "heaac_v2",
"channels": 2,
"sample_rate": 44100,
"bitrate_kb": 128
}
]
}
]
}
}
Automatic Padding and Cropping To Target Size
Instead of adding a specific cropping filter, there is also one additional way that you can crop video. As we said, Hybrik’s default behavior is to keep all pixels of the source video in the output, and to add padding (letterboxing or pillarboxing) as needed keep all pixels. You can tell Hybrik to instead crop the source video so that it perfectly matches the target resolution (adding or removing letterboxing as needed). You can do this using the parameter ar_pad_crop_ratio. If this parameter is set to 1 (the default), then the source is fully padded to match the target. If the parameter is set to 0, then the source is fully cropped to match the target. Here is the same example as the source cropping, only now fully cropped using the ar_pad_crop_ratio parameter.
{
"uid": "transcode_task",
"kind": "transcode",
"payload": {
"location": {
"storage_provider": "s3",
"path": "s3://path/to/output/"
},
"targets": [
{
"file_pattern": "{source_basename}_cropped.mp4",
"existing_files": "replace",
"container": {
"kind": "mp4"
},
"video": {
"codec": "h264",
"width": 1280,
"height": 720,
"bitrate_kb": 1000,
"ar_pad_crop_ratio": 0
},
"audio": [
{
"codec": "heaac_v2",
"channels": 2,
"sample_rate": 44100,
"bitrate_kb": 128
}
]
}
]
}
...
Automatic Removal of Letterboxing
Hybrik can also use an analyze task to detect if letterboxing is present, and it can remove the letterboxing if it exists. We also use overrides to pass in values from the analyze task.
First an analyze task is inserted:
{
"uid": "analyze_task",
"kind": "analyze",
"task": {
"retry_method": "fail"
},
"payload": {
"general_properties": {
"enabled": true
},
"deep_properties": {
"video": {
"black_borders": {
"enabled": true
}
}
}
}
},
Then in the transcode task, we apply the crop filter and override the height/width of our video with the results from the analyze task.
{
"uid": "transcode_task",
"kind": "transcode",
"task": {
"retry_method": "fail"
},
"payload": {
"source_pipeline": {
"filters": [
{
"video": [
{
"kind": "crop",
"payload": {
"top": "auto",
"bottom": "auto",
"left": "auto",
"right": "auto",
"use_source_dimensions": true
}
}
]
}
]
},
"location": {
"storage_provider": "s3",
"path": ""
},
"targets": [
{
"container": {
"kind": "mp4"
},
"existing_files": "replace",
"file_pattern": "{source_basename}_letterbox_removed{default_extension}",
"video": {
"codec": "h264",
"bitrate_mode": "cbr",
"profile": "high",
"level": "4.1",
"preset": "fast",
"bitrate_kb": "1500",
"par": "1",
"overrides": {
"height": "(source.video.height) - (analyzer.deep_properties.video.black_borders.top) - (analyzer.deep_properties.video.black_borders.bottom)",
"width": "round(source.video.width * source.video.par)"
}
},
Image Distortion
Sometimes your input and output aspect ratios are very similar but not quite exact. And a few lines of black along the borders of your output can be very annoying. Hybrik allows you to slightly change the aspect ratio of the source to exactly match the output of the target. This causes a slight squeeze or expansion of the video, but if kept to small numbers this is unnoticeable and greatly preferable to the black bars. The parameter ar_max_distortion allows you to set a maximum distortion that can be allowed. By default, Hybrik will perform up at a 5% distortion in order to have the source and target aspect ratios match.
Example Jobs
- Crop Filter example
- Auto-Crop filter to add letterboxing example
- Auto-Crop filter to remove letterboxing example