videobeaux/docs/programs/utilities/qwikchop.md

qwikchop

Description

Rapidly slices videos into precise segments based on timecodes or cut lists, optimized for speed and batch operations.

Purpose

qwikchop is built for extremely fast segment extraction, allowing you to cut a video into many pieces without re-encoding.
It supports:

• cut lists,
• recursive directory processing,
• black-frame trimming,
• segment cleanup rules,
  making it ideal for large workflows like commercial removal, archive splitting, and automated editing pipelines.

How It Works

1. Piece Definition
   The pieces argument defines cut points—either explicit timecodes or references to external lists.
2. Recursive Mode
   If recurse is enabled, the tool processes all media files inside a directory tree.
3. Black Frame Detection
   • trim_black_front removes silent/black leader.
   • black_scan, black_thresh, and black_pict tune detection sensitivity.
4. Padding Controls
   • edge_pad_pre and edge_pad_post adjust segment timing to avoid cutting too close to transitions.
5. Minimum Edit Length
   min_edit prevents creation of fragment edits that are too short to be meaningful.
6. Output
   Segments are exported into the destination directory with predictable sequential naming.

Program Template

videobeaux -P qwikchop \
  -i input.mp4 \
  -o output.mp4 \
  --pieces VALUE \
  --recurse VALUE \
  --keep_temp VALUE \
  --trim_black_front VALUE \
  --black_scan VALUE \
  --black_thresh VALUE \
  --black_pict VALUE \
  --edge_pad_pre VALUE \
  --edge_pad_post VALUE \
  --min_edit VALUE

Arguments

• pieces — Defines segment boundaries; may be timecodes or an external list.
• recurse — Enables directory recursion for batch processing.
• keep_temp — When true, preserves intermediate working files.
• trim_black_front — Removes black/silent leader at beginning.
• black_scan — Duration scanned for determining black-frame presence.
• black_thresh — Threshold used to classify frames as black.
• black_pict — Pictorial threshold for more advanced black-frame evaluation.
• edge_pad_pre — Time (seconds) added before segment boundaries.
• edge_pad_post — Time (seconds) added after segment boundaries.
• min_edit — Minimum allowed edit duration; prevents overly short segments.

Real World Example

videobeaux -P qwikchop \
  -i myvideo.mp4 \
  -o qwikchop_styled.mp4 \
  --pieces EXAMPLE \
  --recurse false \
  --keep_temp false \
  --trim_black_front true \
  --black_scan 0.5 \
  --black_thresh 0.10 \
  --black_pict 0.10 \
  --edge_pad_pre 0.25 \
  --edge_pad_post 0.25 \
  --min_edit 1.0

Technical Notes

• Segmenting is performed without re-encoding, making it extremely fast.
• Black trimming uses FFmpeg’s blackdetect logic; thresholds may require tuning based on source material.
• edge_pad_pre and edge_pad_post are helpful for avoiding letterboxing artifacts or abrupt audio cuts.
• Very small values for min_edit may create unusable micro-clips.

Recommended Usage

• Cutting commercials or interstitials from broadcast recordings.
• Building structured archives from long-form footage.
• Automatically splitting lecture or surveillance videos into events.
• Preparing clips for machine-learning datasets.

Quality Tips

• Increase edge_pad_pre/post slightly to avoid accidental content clipping.
• Adjust black_thresh based on the luminance characteristics of your footage.
• Use recursive mode (recurse=true) when processing large folder trees.
• Keep min_edit above 0.5–1.0 seconds for stable outputs.