Struct BlackFrameDetector 

pub struct BlackFrameDetector { /* private fields */ }

Detects black intervals in a video file and returns their start timestamps.

Uses FFmpeg’s blackdetect filter to identify frames or segments where the proportion of “black” pixels exceeds threshold. One Duration is returned per detected black interval (the start of that interval).

Examples

use ff_analysis::BlackFrameDetector;

let black_starts = BlackFrameDetector::new("video.mp4")
    .threshold(0.1)
    .run()?;

for ts in &black_starts {
    println!("Black interval starts at {:?}", ts);
}

Implementations

impl BlackFrameDetector

pub fn new(input: impl AsRef<Path>) -> Self

Creates a new detector for the given video file.

The default threshold is 0.1 (10% of pixels must be below the blackness cutoff for a frame to count as black).

Examples found in repository

examples/black_frames.rs (line 59)

fn main() {
    let mut args = std::env::args().skip(1);
    let mut input = None::<String>;
    let mut threshold = 0.1_f64;

    while let Some(flag) = args.next() {
        match flag.as_str() {
            "--input" | "-i" => input = Some(args.next().unwrap_or_default()),
            "--threshold" | "-t" => {
                let raw = args.next().unwrap_or_default();
                threshold = raw.parse().unwrap_or_else(|_| {
                    eprintln!("Invalid threshold: {raw}");
                    process::exit(1);
                });
            }
            other => {
                eprintln!("Unknown flag: {other}");
                process::exit(1);
            }
        }
    }

    let input = input.unwrap_or_else(|| {
        eprintln!("Usage: black_frames --input <video> [--threshold <0.0–1.0>]");
        process::exit(1);
    });

    println!("Detecting black frames in: {input}");
    println!("Threshold: {threshold:.2}");
    println!();

    let black_starts = BlackFrameDetector::new(&input)
        .threshold(threshold)
        .run()
        .unwrap_or_else(|e| {
            eprintln!("Error: {e}");
            process::exit(1);
        });

    if black_starts.is_empty() {
        println!("No black intervals detected.");
    } else {
        println!("Detected {} black interval(s):", black_starts.len());
        for (i, ts) in black_starts.iter().enumerate() {
            println!("  [{i:3}] {}", fmt_duration(*ts));
        }
    }
}

pub fn threshold(self, t: f64) -> Self

Sets the luminance threshold for black-pixel detection.

Must be in the range [0.0, 1.0]. Higher values make the detector more permissive (more frames qualify as black); lower values are stricter. Passing a value outside this range causes run to return AnalysisError::Failed.

Default: 0.1.

Examples found in repository

examples/black_frames.rs (line 60)

fn main() {
    let mut args = std::env::args().skip(1);
    let mut input = None::<String>;
    let mut threshold = 0.1_f64;

    while let Some(flag) = args.next() {
        match flag.as_str() {
            "--input" | "-i" => input = Some(args.next().unwrap_or_default()),
            "--threshold" | "-t" => {
                let raw = args.next().unwrap_or_default();
                threshold = raw.parse().unwrap_or_else(|_| {
                    eprintln!("Invalid threshold: {raw}");
                    process::exit(1);
                });
            }
            other => {
                eprintln!("Unknown flag: {other}");
                process::exit(1);
            }
        }
    }

    let input = input.unwrap_or_else(|| {
        eprintln!("Usage: black_frames --input <video> [--threshold <0.0–1.0>]");
        process::exit(1);
    });

    println!("Detecting black frames in: {input}");
    println!("Threshold: {threshold:.2}");
    println!();

    let black_starts = BlackFrameDetector::new(&input)
        .threshold(threshold)
        .run()
        .unwrap_or_else(|e| {
            eprintln!("Error: {e}");
            process::exit(1);
        });

    if black_starts.is_empty() {
        println!("No black intervals detected.");
    } else {
        println!("Detected {} black interval(s):", black_starts.len());
        for (i, ts) in black_starts.iter().enumerate() {
            println!("  [{i:3}] {}", fmt_duration(*ts));
        }
    }
}

pub fn run(self) -> Result<Vec<Duration>, AnalysisError>

Runs black-frame detection and returns the start Duration of each detected black interval.

Errors

• AnalysisError::Failed — threshold outside [0.0, 1.0], input file not found, or an internal filter-graph error.

Examples found in repository

examples/black_frames.rs (line 61)

fn main() {
    let mut args = std::env::args().skip(1);
    let mut input = None::<String>;
    let mut threshold = 0.1_f64;

    while let Some(flag) = args.next() {
        match flag.as_str() {
            "--input" | "-i" => input = Some(args.next().unwrap_or_default()),
            "--threshold" | "-t" => {
                let raw = args.next().unwrap_or_default();
                threshold = raw.parse().unwrap_or_else(|_| {
                    eprintln!("Invalid threshold: {raw}");
                    process::exit(1);
                });
            }
            other => {
                eprintln!("Unknown flag: {other}");
                process::exit(1);
            }
        }
    }

    let input = input.unwrap_or_else(|| {
        eprintln!("Usage: black_frames --input <video> [--threshold <0.0–1.0>]");
        process::exit(1);
    });

    println!("Detecting black frames in: {input}");
    println!("Threshold: {threshold:.2}");
    println!();

    let black_starts = BlackFrameDetector::new(&input)
        .threshold(threshold)
        .run()
        .unwrap_or_else(|e| {
            eprintln!("Error: {e}");
            process::exit(1);
        });

    if black_starts.is_empty() {
        println!("No black intervals detected.");
    } else {
        println!("Detected {} black interval(s):", black_starts.len());
        for (i, ts) in black_starts.iter().enumerate() {
            println!("  [{i:3}] {}", fmt_duration(*ts));
        }
    }
}