andrew-avinante/cdml-fade-detector

CDML fade detector

This checkpoint detects commercial-break boundaries in episodic video from the paired fade-to-black and fade-to-silence signal that often surrounds an act break. It emits a fade probability for every decoded video frame; CDML post-processing turns those scores into timestamped events or optional chapter markers.

It is a purpose-built PyTorch checkpoint, not a Transformers model or a general video classifier. Use it through the accompanying CDML codebase.

Model details

• Model file: fade_detector.pt
• Parameters: approximately 230,000
• Input window: 8 seconds (192 frames at 24 fps)
• Video input: 64×64 grayscale frames
• Audio input: log-RMS level plus 16 mel-band energy features, aligned to video frames
• Output: one fade logit/probability per frame

The model applies a shared four-stage CNN to each frame, combines the frame embedding with six luminance and motion statistics, projects the 17 audio energy features, and models the fused sequence with a two-layer bidirectional GRU. Scores from overlapping windows are smoothed and converted to fade events with hysteresis and a minimum-duration rule.

Intended use

Use this model to locate likely commercial-break boundaries in episodic video whose breaks use a paired black-and-silent transition. It is useful for local media organization, review workflows, and writing chapter markers to media you are authorized to process.

The model is not designed to recognize shows, advertisements, people, or video content. It should not be used as the sole basis for high-impact decisions.

Quick start

CDML requires Python 3.10 or later, PyTorch 2.4 or later, and ffmpeg plus ffprobe available on PATH. Install the CDML code and download this checkpoint:

pip install "git+https://github.com/andrew-avinante/commercial-detctor-ml.git" huggingface_hub

python - <<'PY'
from huggingface_hub import hf_hub_download

print(hf_hub_download(
    repo_id="andrew-avinante/cdml-fade-detector",
    filename="fade_detector.pt",
))
PY

Pass the printed path to CDML:

python -m cdml.infer --model /path/to/fade_detector.pt --video episode.mkv

To write predicted breaks as chapter markers without re-encoding the streams:

python -m cdml.mark_chapters episode.mkv --model /path/to/fade_detector.pt --dry-run

See the CDML README for installation options, inference output, and chapter-writing behavior.

Training data and provenance

The checkpoint was trained on 2,032 windows from 83 privately held episodes across four shows. Labels were derived from existing container chapter markers and were used to identify commercial-break fades. Positive windows contain chapter-marked break fades; hard negatives include non-break fades such as scene transitions; easy negatives are ordinary footage away from a fade.

The original video and audio, decoded training cache, shards, label exports, contact sheets, source paths, and source identifiers are not distributed. This is not a dataset release. Users who want to reproduce or adapt the method should build a local dataset only from media they have the right to process; the source repository documents that workflow.

Train/validation/test splits were grouped by episode, so clips from an episode did not cross split boundaries. The training configuration used 120 maximum epochs with early stopping on validation average precision, AdamW (learning rate 3e-4), batch size 16, five warmup epochs, cosine decay, and class weighting derived from the training labels.

Evaluation

The primary held-out test split was grouped by episode. Its threshold was chosen on the validation split, then the untouched test split was scored once.

Metric	CDML detector	Threshold baseline
Average precision	0.9823	0.7792
Frame F1	0.9654	0.7255
Event F1	0.9840	0.7782
Missed events	0 of 123	9 of 123

Leave-one-show-out results measure transfer to a show excluded from training:

Held-out show	Average precision	Event F1	Event recall
Show A (animated)	0.9709	0.9545	1.000
Show B (animated)	0.9634	0.9067	0.872
Show C (live action)	0.9449	0.9061	0.967
Show D (animated)	0.9313	0.7606	0.643

The results are aggregate measurements on the described private corpus, not a guarantee of accuracy for other shows, encodes, or break styles. The complete sanitized reports are available in the source repository: held-out evaluation and leave-one-show-out reports.

Limitations and risks

• Breaks without the paired black-and-silent transition may be missed.
• Scene transitions, end credits, and other dark or silent material can produce false positives.
• The model performed worst on a held-out show with unusually long break fades.
• Results may degrade for formats, frame rates, video encodes, sound mixes, or programme styles unlike the evaluation corpus.
• Review predictions before using --existing replace or making irreversible changes to media chapter metadata.

License

The checkpoint is released under Apache-2.0. That license applies to the checkpoint, code, and included documentation; it does not grant rights to the underlying commercial training media, which is not included.

Reproducibility and integrity

• CDML package version: 0.1.0
• Source revision: 3a483212cc27fe69f6aa2ffcb3346bd372426e48
• Checkpoint SHA-256: 4af08510774e7eae496a4e413bba54f915a1c13fe912fee70857a862c5def300

After downloading, verify the checkpoint with:

sha256sum fade_detector.pt

The output must match the SHA-256 value above. For a reproducible release, retain this card with the checkpoint and link the Hub revision to the matching tag or commit in the CDML source repository.

Citation

No paper accompanies this release. If you use the model, cite the model repository, its revision, and the accompanying CDML source repository.