video_helper.cli module

Video Helper — command-line interface.

The package’s single command line: a thin dispatch over the pure functions in video_helper.main, exposing the whole toolkit as subcommands of one video-helper entry point. Built with click, which is a core dependency — the CLI is not an optional surface.

Subcommands

• validate — probe a video file / URL for validity (boolean)

• dimensions — dump width/height/duration/frame_rate/has_sound as JSON

• duration — print the duration in seconds of a video

• convert — re-encode / resize / drop audio

• chunk — extract a [start, end] slice

• black — synthesize a silent solid-black clip

• compress — two-pass compress to a target file size

• image-loop — loop a still image into a silent clip

• concat — concatenate several videos head-to-tail

• overlay — overlay a still image on a video (watermark / cursor)

• extract-audio — dump the audio track of a video

• mux-audio — mux a separate audio track onto a video

• burn-subs — burn .srt / .vtt / .ass into the frames

• srt2vtt — SRT → WebVTT with color-preserving CSS

• extract-frames— stream frames to disk (one PNG per sampled frame)

• extract-flow — dense optical flow: HSV-visualization video or raw .npy

Design notes

• Flags are spelled --input / --output / … rather than in the more idiomatic click positional style: the HTTP and MCP surfaces name their parameters the same way, so one vocabulary covers all of them.

• A library exception is caught by main() (the console-script entry point) and printed as one clean Error: ... line + exit 1, instead of a raw Python traceback.

Usage Example

>>> #   video-helper validate       --input clip.mp4
>>> #   video-helper dimensions     --input clip.mp4
>>> #   video-helper duration       --input clip.mp4
>>> #   video-helper convert        --input in.mov --output out.mp4 --width 640 --height 480
>>> #   video-helper chunk          --input in.mp4 --start 10 --end 20 --output cut.mp4
>>> #   video-helper black          --duration 3 --width 1920 --height 1080 --output buffer.mp4
>>> #   video-helper image-loop     --image title.png --duration 4 --output title.mp4
>>> #   video-helper concat         --inputs a.mp4 b.mp4 c.mp4 --output final.mp4
>>> #   video-helper overlay        --input clip.mp4 --image logo.png --output marked.mp4
>>> #   video-helper extract-audio  --input clip.mp4 --output audio.wav
>>> #   video-helper mux-audio      --input silent.mp4 --audio voice.wav --output final.mp4
>>> #   video-helper burn-subs      --input clip.mp4 --subs subs.srt --output captioned.mp4
>>> #   video-helper srt2vtt        --input subs.srt
>>> #   video-helper extract-frames --input clip.mp4 --output-dir frames/ --frame-step 5
>>> #   video-helper extract-flow   --input clip.mp4 --output clip-flow.mp4 --method dis

Author

Warith Harchaoui, Ph.D. — https://linkedin.com/in/warith-harchaoui/

video_helper.cli.main()

Console entry point (video-helper).

Click’s own dispatch only special-cases ClickException/Abort (and a broken pipe); a plain library exception (e.g. from video_converter()) would otherwise propagate as a raw Python traceback instead of a clean CLI error. This wraps the whole invocation and translates that last case into a one-line stderr message + exit 1 — click’s own control flow (usage errors, --help, an explicit sys.exit(1) in a subcommand) already raises SystemExit, a BaseException this does not catch, so it passes through untouched.

Return type:

None