Skip to main content

Black 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.
  • 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 at 0.0: no pixels must be black.
    • maximum: 1, default: 0.98
  • ire_range_mode
    • options: auto, full, limited

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.

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 NameTypeDescription
leading_secnumberThis 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_secnumberThis 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_secnumberThis is the duration in seconds of the detected black video listed in "events" with the longest duration.
total_secnumberThis is the sum of all detected black video durations listed in "events" in seconds.
eventsarray"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_exceeededbooleanThis parameter will be true if the size of the “events” array exceeds the maximum value for reporting. 100 events
settingsobjectThis 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}"
    }
  ]
}

Example Job​