Black Video Analysis
If you want to ensure that your video content has no extended periods of black video, then this is the analysis type you’ll want to use. You may also be interested in detecting silence in audio content, which you can learn more about here: Audio Silence Analysis
Our API Docs list all options, but here is a summary:
duration_sec- minimum:
1, maximum:3600, default:10 - Black video must exceed this duration for triggering detection.
- minimum:
black_level- The video signal level must be above this value for being detected as non-black.
- maximum:
1, default:0.1
black_pixel_ratio- Ratio of black vs. non black pixels so that a picture is classified as black. Value set at
1.0: all pixels must be black. Value set at0.0: no pixels must be black. - maximum:
1, default:0.98
- Ratio of black vs. non black pixels so that a picture is classified as black. Value set at
ire_range_mode- options:
auto,full,limited
- options:
Sample Usage
The sample json below is set to detect black video with black_level at 0.1 or lower (darker), and having a duration of 1 second or longer. You may want to test with the black_level value, as credits with a black background and a small amount of white text could trigger a false positive.
{
"uid": "analyze_task",
"kind": "analyze",
"payload": {
"general_properties": {
"enabled": true
},
"deep_properties": {
"video": {
"black": {
"enabled": true,
"black_level": 0.1,
"duration_sec": 1,
"black_pixel_ratio":0.98,
"ire_range_mode":"auto"
}
}
}
}
}
Analyzer Results
NOTE: In Hybrik version 1.217, we introduced a change to the structure of the analyzer results that have timed events. The new result version can be activated by setting "response_version": 2 in your analyzer's options. The default version will become version 2 in a future release. If you need the documentation for the legacy version of this tutorial, please visit the legacy link.
{
"uid": "analyze_task",
"kind": "analyze",
"payload": {
"options": {
"response_version": 2
},
...
}
Results from running this analysis on a file with black sections will be reported in the job summary json, in the “analyzer / deep_properties” section of the job result:
{
"deep_properties": {
"video": {
"black": {
"leading_sec":4.79,
"trailing_sec":4.9,
"max_sec":10.0,
"total_sec":19.69,
"events": [
{
"begin":-.012,
"end":4.78,
"duration":4.79
},
{
"begin":85.6,
"end":95.6,
"duration":10.0
},
{
"begin":273.65,
"end":278.55,
"duration":4.9
}
],
"settings": {
"duration_sec":1,
"black_level":0.1,
"black_pixel_ratio":0.98,
"ire_range_mode":"auto"
}
}
}
}
}
Here are the explanations for each result parameter:
| Parameter Name | Type | Description |
|---|---|---|
| leading_sec | number | This is the duration in seconds of black at the start of the video. This will only report black that exceeds the “duration_sec” in settings. |
| trailing_sec | number | This is the duration in seconds of black at the end of the video. This will only report black that exceeds the “duration_sec” in settings. This value will appear even if the event array is capped before it reaches the end of the media. |
| max_sec | number | This is the duration in seconds of the detected black video listed in “events” with the longest duration. |
| total_sec | number | This is the sum of all detected black video durations listed in “events” in seconds. |
| events | array | “black” has turned from an array to an object to support the additional parameters, and this array is where the previous contents of the “black” array will go. |
| max_events_exceeeded | boolean | This parameter will be true if the size of the “events” array exceeds the maximum value for reporting. 100 events |
| settings | object | This contains all of the parameters that were used to configure the black detection analyzer. |
QC Task
These analysis results can be used in a QC condition, for example “does this video have less than 5 seconds of black at the start and end” which would look like this:
"tests": [
{
"conditions": [
{
"condition": "deep_properties.video.black.leading_sec <= 5",
"message_pass": "PASS: There is less than 5 seconds of black at the start of this video. Actual value: {deep_properties.video.black.leading_sec}",
"message_fail": "FAIL: There is more than 5 seconds of black at the start of this video. Actual value: {deep_properties.video.black.leading_sec}"
},
{
"condition": "deep_properties.video.black.trailing_sec <= 5",
"message_pass": "PASS: There is less than 5 seconds of black at the end of this video. Actual value: {deep_properties.video.black.trailing_sec}",
"message_fail": "FAIL: There is more than 5 seconds of black at the end of this video. Actual value: {deep_properties.video.black.trailing_sec}"
}
]
}