---
updatedAt: 2025-06-18T15:28:55.000Z
agentTools:
  projectIndex: https://api.encoding.com/llms.txt
---

# Black Frame Detection

<a name="edit-black-detection"></a>Detect video intervals that are (almost) completely black. Can be useful to detect chapter transitions, commercials, or invalid recordings. Output lines contains the time for the start, end and duration of the detected black interval expressed in seconds.

> 🚧 Note
>
> Maximum number of “black” segments to clip out is limited to 150.

```xml
<?xml version="1.0"?>
<query>
    <userid>&lt;UserID&gt;</userid> {/* required */}
    <userkey>&lt;UserKey&gt;</userkey> {/* required */}
    <action>&lt;Action&gt;</action> {/* required */}
    <source>&lt;SourceFile&gt;</source> {/* required */}
    <format>
        <output>&lt;output&gt;</output> {/* required */}
        <cut_black>
            <enable>&lt;yes|no&gt;</enable>
            <black_min_duration>&lt;Duration&gt;</black_min_duration>
            <pixel_black>&lt;PixelThreshold&gt;</pixel_black>
            <picture_black_ratio>&lt;PictureThreshold&gt;</picture_black_ratio>
            <trim>&lt;yes|no&gt;</trim>
            <pixel_black_mv>&lt;PixelMillivoltsThreshold&gt;</pixel_black_mv>
            <silence_check>&lt;yes|no&gt;</silence_check>
            <silence_threshold>&lt;SilenceThreshold&gt;</silence_threshold>
        </cut_black>
        {/* format parameters */}
    </format>
</query>
```

```json
{
    "query": {
        "userid": "<UserID>", // required
        "userkey": "<UserKey>", // required
        "action": "<Action>", // required
        "source": "<SourceFile>", // required
        "format": {
            "output": "<output>", // required
            "cut_black": {
                "enable": "<yes|no>",
                "black_min_duration": "<Duration>",
                "pixel_black": "<PixelThreshold>",
                "picture_black_ratio": "<PictureThreshold>",
                "trim": "<yes|no>",
                "pixel_black_mv": "<PixelMillivoltsThreshold>",
                "silence_check": "<yes|no>",
                "silence_threshold": "<SilenceThreshold>"
            }
            // format parameters
        }
    }
}
```

| Parameter                 | Description                                                 | Allowed Values                                                                                                                                                                                                | Default Value |
| :------------------------ | :---------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------ |
| **enable**                | Enable black frame detection and clipping.                  | yes, no                                                                                                                                                                                                       | no            |
| **black\_min\_duration**  | Specify the shortest black frame duration in seconds.       | Positive float number                                                                                                                                                                                         | 2.0           |
| **pixel\_black**          | Threshold for classification pixels as black.               | Positive float number less than 1.<br/><br/>0 – Pixel must be absolutely black to be classified as black.<br/><br/>0.99 – The lightest pixels would be classified as black.                                   | 0.00          |
| **picture\_black\_ratio** | Threshold for classification frame as black.                | Positive float number less or equals to 1.<br/><br/>1 – Frame must have only “black” pixels to be classified as “black” frame.<br/><br/>0 – Frame can have no black pixels to be classified as “black” frame. | 1             |
| **trim**                  | Trim black frames only from start and end of the video      | yes, no                                                                                                                                                                                                       | no            |
| **pixel\_black\_mv**      | Threshold for classification pixels as black in millivolts. | Float number between 0.00 and 714.00 inclusive                                                                                                                                                                | 0             |
| **silence\_check**        | Detect black frames only if audio recognized as silent      | yes, no                                                                                                                                                                                                       | no            |
| **silence\_threshold**    | Noise tolerance in dB                                       | Integer number                                                                                                                                                                                                | -60           |