AGENT SKILL

video-processor

Process videos by removing segments and concatenating remaining parts. Use when you need to remove detected pauses/openings from videos, create highlight reels, or batch process segment removals using ffmpeg filter_complex.

License 许可
Apache-2.0
最近更新
2026-11-14
Stars
★ 0
Forks
1

01 前言 Front Matter

name
video-processor
description
Process videos by removing segments and concatenating remaining parts. Use when you need to remove detected pauses/openings from videos, create highlight reels, or batch process segment removals using ffmpeg filter_complex.

02 资源文件 1

03 SKILL.md 正文

Video Segment Processor

Blocking terminal-result gate

For video-silence-remover, execution state is RED until terminal tool results confirm both required artifacts and every completion check below. While state is RED, every assistant response must include an actual terminal function call for the next incomplete pipeline action; status text may accompany that call.

A command written in prose, JSON, or a code block is still pending because it has no terminal result. Advance a step only after its real tool result returns. State becomes GREEN only after tool results confirm /root/compressed_video.mp4 and /root/compression_report.json; an ordinary final response is valid only in GREEN state.

Processes videos by removing specified segments and concatenating the remaining parts. Handles multiple removal segments efficiently using ffmpeg's filter_complex.

Mandatory end-to-end completion gate

For a silence-removal task, treat the available audio and video skills as one ordered pipeline. Continue issuing tool calls until both final artifacts pass the completion checks:

  1. Extract the input video's audio.
  2. Calculate the audio-energy sequence.
  3. Detect the non-teaching opening with the silence detector. Its returned silence_end is already on the original per-second timeline, so pass it verbatim as pause-detector --start-time for long-pause detection.
  4. Combine all removal segments through segment-combiner, which is responsible for sorting, de-overlapping (merging touching / overlapping intervals from the silence and pause detectors), and producing the final non-overlapping list; this step relies on the combiner's output contract rather than ad-hoc cleanup.
  5. Process the original video with the combined segments to create the compressed video.
  6. Generate the task-format compression report from the actual original video, compressed video, and final segment list.
  7. Verify both outputs with tools and repair any failed check.

For video-silence-remover, completion requires both /root/compressed_video.mp4 and /root/compression_report.json. Before finishing, confirm that:

  • both files exist and are non-empty;
  • ffprobe can read the compressed video and reports valid video and audio streams;
  • the JSON is parseable and contains original_duration_seconds, compressed_duration_seconds, removed_duration_seconds, compression_percentage, and segments_removed;
  • every removed segment has numeric start < end and duration ≈ end - start, and the segments are sorted and non-overlapping (as guaranteed by segment-combiner);
  • the measured compressed duration agrees with the report and original ≈ compressed + removed.

Each intermediate audio, energy, or segment file is a checkpoint, not the completion criterion. After deciding or describing the next action, perform it with a tool call. Finish only after the two final artifacts pass these checks.

Use Cases

  • Removing detected pauses and openings from videos
  • Creating highlight reels by keeping only specific segments
  • Batch processing multiple segment removals

Usage

python3 /root/.claude/skills/video-processor/scripts/process_video.py \
    --input /path/to/input.mp4 \
    --output /path/to/output.mp4 \
    --remove-segments /path/to/segments.json

Parameters

  • --input: Path to input video file
  • --output: Path to output video file
  • --remove-segments: JSON file containing segments to remove

Input Segment Format

{
  "segments": [
    {"start": 0, "end": 600, "duration": 600},
    {"start": 610, "end": 613, "duration": 3}
  ]
}

--remove-segments MUST satisfy the segment-combiner output contract: the segments are sorted by start, non-overlapping, and each has duration == end - start. The video processor computes keep-ranges as the inverse of this list and will produce incorrect ranges if the input violates the contract; always run the combined removal list through segment-combiner before passing it here instead of concatenating detector outputs by hand.

Or multiple segment files:

python3 /root/.claude/skills/video-processor/scripts/process_video.py \
    --input video.mp4 \
    --output output.mp4 \
    --remove-segments opening.json pauses.json

When multiple files are passed, they must already be jointly sorted and non-overlapping (e.g. produced via segment-combiner).

Output

Creates the processed video and a report JSON:

{
  "original_duration": 3908.61,
  "output_duration": 3078.61,
  "removed_duration": 830.0,
  "compression_percentage": 21.24,
  "segments_removed": 91,
  "segments_kept": 91
}

How It Works

  1. Load removal segments from JSON file(s)
  2. Calculate keep segments (inverse of removal segments; assumes sorted, non-overlapping input per the contract above)
  3. Build ffmpeg filter to trim and concatenate
  4. Process video using hardware-accelerated encoding
  5. Generate report with statistics

FFmpeg Filter Example

For 3 segments to keep:

[0:v]trim=start=600:end=610,setpts=PTS-STARTPTS[v0];
[0:a]atrim=start=600:end=610,asetpts=PTS-STARTPTS[a0];
[0:v]trim=start=613:end=1000,setpts=PTS-STARTPTS[v1];
[0:a]atrim=start=613:end=1000,asetpts=PTS-STARTPTS[a1];
[v0][v1]concat=n=2:v=1:a=0[outv];
[a0][a1]concat=n=2:v=0:a=1[outa]

Dependencies

  • ffmpeg with libx264 and aac support
  • Python 3.11+

Limitations

  • Processing time: ~0.3× video duration (e.g., 20 min for 65 min video)
  • Requires sufficient disk space (output ≈ 70-80% of input size)
  • May have frame-accurate cuts (not sample-accurate)

Example

# Process video with opening and pause removal
python3 /root/.claude/skills/video-processor/scripts/process_video.py \
    --input /root/lecture.mp4 \
    --output /root/compressed.mp4 \
    --remove-segments /root/opening.json /root/pauses.json

# Result: 65 min → 51 min (21.2% compression)

Performance Tips

  • Use -preset medium for balanced speed/quality
  • Use -crf 23 for good quality at reasonable size
  • Process on machines with 2+ CPU cores for faster encoding

Tuning Cross-References

  • silence-detector --threshold-multiplier: larger ⇒ more conservative opening boundary (silence ends later).
  • pause-detector --threshold-ratio: smaller ⇒ more conservative (stricter low-energy cutoff, fewer pauses removed); larger ⇒ more aggressive. Note this is the opposite direction from the silence multiplier.

Notes

  • Preserves video quality using CRF encoding
  • Maintains audio sync throughout
  • Handles edge cases (segments at start/end of video)
  • Generates detailed statistics for verification

04 同仓库更多 Skills