VideoSpeed - Cut, speed, and boomerang MP4 clips from the CLI

VideoSpeed cuts a time range from an MP4, changes that clip’s length (percent), and can append a reverse pass (boomerang). On a terminal, no arguments opens a text menu (edit, hello, self-management, Exit). Choosing edit walks through the prompts. Scripts pass --file / --start / --end. Encoding uses FFmpeg; duration probing uses OpenCV. The menu screen uses the default text-menu style: aligned number, verb, and note, and a rounded box along the bottom.

Package version SSOT: src/VideoSpeed/__init__.py (MAJOR_VERSION, MINOR_VERSION, PATCH_VERSION → 1.0.10). pyproject.toml copies that string. Console entrypoint: video-speed.

Features

• Recursive MP4 discovery under a chosen folder
• Interactive cut (start/end seconds) with invalid-range re-prompt
• Length/speed change (20–200%) with A/V tempo kept in sync
• Optional boomerang (forward then reverse)
• USB-safe intermediate files (staged next to the output) and final publish via shutil.move
• Text menu on a terminal (edit, hello, self-management, Exit): columns line up, and a three-row rounded input box sits on the bottom with a status line under it. 8 self-management opens version, about, and the pip lifecycle rows
• Product verbs help, version, about, hello, edit, list-mp4, self-install, version-check, self-update, and self-uninstall. help prints the same usage as --help. version prints the installed version. about and hello print a page and do not ask for a folder or a file. edit on a terminal asks for the folder, then the file. list-mp4 lists MP4 files and does not encode. version-check runs python -m pip index versions VideoSpeed. self-update runs python -m pip install --upgrade VideoSpeed. self-install runs python -m pip install VideoSpeed. self-uninstall runs python -m pip uninstall -y VideoSpeed and needs --force on the command line. Exit stays on the menu. ./build.sh verbs such as setup are not video-speed verbs
• --help / --version; no arguments in a terminal opens that menu
• Non-interactive job: --file, --start, --end, optional --percent / --boomerang, with or without edit. Any of those selectors with no product verb skips the menu
• Fail-closed when FFmpeg is missing from PATH, when prompts are needed without a terminal, or when --percent or --boomerang is passed without a job

Quick Installation

Prerequisites (system)

• FFmpeg on PATH (ffmpeg -version)
• A supported Python environment (see requires-python in pyproject.toml)

From PyPI (registry channel)

Package name SSOT: VideoSpeed (pyproject.toml [project].name). Maintainer verbs are on ./build.sh: help, version, setup, clean, build, test, test-install, upload, git, tag, release (all is the same chain as release). test runs tests/run.sh. test-install reads [project].name, removes that pip install when present, and installs this checkout. Empty ./build.sh prints help and does not upload.

pip install VideoSpeed

If the index is behind a local release, install from a checkout or wheel instead (below). Live index version is shown by the PyPI badge above.

From a git checkout (development)

git clone git@github.com:Wilgat/VideoSpeed.git
cd VideoSpeed
pip install -e .

This installs the console script video-speed and pulls Python deps (opencv-python-headless>=5.0.0.93, ChronicleLogger>=1.3.1).

Local pyenv install (testing)

./setup.sh
pyenv shell 3.14
video-speed --version

setup.sh runs pyenv shell 3.14 and installs this checkout with pip into that interpreter. Install CPython 3.14 first when it is missing (pyenv install 3.14). Run ./setup.sh again after source changes. In the shell where you want the command:

pyenv shell 3.14
video-speed --help

The console script is installed on the pyenv 3.14 prefix. ./setup.sh changes that interpreter only. It does not install FFmpeg and it does not use root.

From a local wheel / sdist

# after: python -m build   (or ./build.sh build)
pip install dist/VideoSpeed-1.0.10-py3-none-any.whl
# or
pip install dist/VideoSpeed-1.0.10.tar.gz

Verify

video-speed --version
# or
python -m VideoSpeed --version

Usage

Text menu (no arguments, in a terminal):

video-speed
# or
python -m VideoSpeed

The screen shows a numbered menu and a rounded input box along the bottom, as wide as the terminal, with one line to type on and a status line under the box. edit continues the prompts. hello (7) shows Hello.. self-management (8) opens version, about, version-check, self-update, self-uninstall, and self-install. Exit leaves.

The same actions are verbs. edit starts at the folder question. list-mp4 asks for the folder when it is omitted, prints the numbered list, and stops. version prints the installed version and does not call pip. version-check and self-update call pip.

video-speed help
video-speed version
video-speed about
video-speed hello
video-speed edit
video-speed edit --folder ./clips
video-speed edit --file clip.mp4 --start 1 --end 5 --percent 100
video-speed list-mp4
video-speed list-mp4 --folder ./clips
video-speed version-check
video-speed self-update
video-speed self-install
video-speed self-uninstall --force

1. Folder containing MP4s (Enter = current directory)
2. Choose a video by number
3. Cut start/end seconds
4. New length percent (default 100; allowed 20–200)
5. Optional boomerang (y/n)
6. Output is written next to the source with a descriptive name

Non-interactive job (scripts / CI):

video-speed --file clip.mp4 --start 1 --end 5 --percent 100
video-speed --file clip.mp4 --start 1 --end 5 --percent 50 --boomerang

Other:

video-speed --help
video-speed --version

Without a terminal and without a job, the program exits with an error instead of hanging on prompts. --percent or --boomerang alone does the same and names --file, --start, and --end. --folder checks the directory. It does not pick a file.

--json keeps that same choice, closes the text menu, and prints one JSON object on standard output. On a terminal with no job flags, the questions are written to the error stream. Progress is not mixed into the object.

Examples

# Install editable, then run interactive session in a folder of clips
cd /path/to/videos
video-speed

# Check identity without starting prompts
video-speed --version

# One-shot job (no prompts)
video-speed --file clip.mp4 --start 1.0 --end 5.0 --percent 100

Example output name shape:

clip_cut1.0-5.0s_100pct.mp4
clip_cut1.0-5.0s_50pct_BOOMERANG.mp4

Platform Compatibility

Related Projects

• VideoSpeed on GitHub
• VideoSpeed on PyPI

Contributing

Fork the repository, use a checkout install (pip install -e . or ./setup.sh), and open a pull request. Prefer small, tested changes. Do not strip defensive temp/publish behavior (cross-filesystem shutil.move) without an explicit redesign.

License

MIT License — see LICENSE.md.

Last Update

2026-10-02 — 1.0.10: front menu 8 is self-management. version prints the installed version. version-check and self-update call pip. help stays a verb and is not a numbered row.