vidtoolz

Make videos using python. A plugin-based CLI toolset for editing, authering videos, built with python.

Overview

vidtoolz is a collection of command-line tools designed to make videos and edit videos easier. The project takes a plugin-based approach, allowing users to extend its functionality by creating custom plugins.

After installing vidtoolz, install any of the following plugins.

Default Plugins

vidtoolz comes with several built-in plugins for common video operations:

VidToolz Plugins

To get help, just type vidtoolz or its shortcut vid to access the cli.

vidtoolz --help 

or

vid --help

This will show all the plugins installed.

usage: vid [-h]
           {plugins,install,trim,addtext,chapters,beats,greenscreen,shorts,repaudio,addsound,concat}
           ...

Video Tools for editing videos using python

positional arguments:
 plugins              Get all listed plugins
 install              Install plugins in the same environemnt as vidtoolz
 trim                 Trim video using ffmpeg
 addtext              Add text to a video file
 chapters             Write formated youtube chapters with text inputs
 beats                Get beats from a mp3 song
 greenscreen          Apply greenscreen video on top of a video
 shorts               Create shorts from long form videos
 repaudio             Replace audio for a video file
 addsound             Add sound to a video
 concat               Concat videos using ffmpeg 

optional arguments:
  -h, --help            show this help message and exit

To install a plugin, just type

vid install vidtoolz-trim

Features

• A simple and intuitive CLI interface
• Extensive plugin support for customizing and extending the toolset
• Integration with popular Python libraries and frameworks
• Support for multiple Python versions (>=3.9)
• Comprehensive testing suite with integration tests for all default plugins
• FFmpeg-based operations for better performance

Testing

vidtoolz includes a comprehensive test suite that covers all default plugins:

# Run all tests
python -m pytest tests/

# Run specific tests
python -m pytest tests/test_vidtoolz.py::test_info_plugin -v
python -m pytest tests/test_vidtoolz.py::test_reverse_plugin -v
python -m pytest tests/test_vidtoolz.py::test_speed_plugin -v

The tests use the provided test data (tests/test_data/) and verify:

• Output file creation and validation
• Proper error handling
• Argument parsing and validation
• Performance characteristics

Speed Plugin

The speed plugin allows you to change video playback speed with flexible audio handling options:

# 2x speed with adjusted audio (default)
vidtoolz speed input.mp4 output.mp4 2.0

# Half speed with muted audio
vidtoolz speed input.mp4 output.mp4 0.5 -a mute

# 1.5x speed keeping original audio
vidtoolz speed input.mp4 output.mp4 1.5 -a keep

# Auto-generated output filename
vidtoolz speed input.mp4 1.8

Audio Modes:

• adjust (default): Adjust audio speed to match video speed
• mute: Remove audio from the output video
• keep: Keep original audio unchanged (video only speed change)

Reverse Plugin Enhancement

The reverse plugin now uses FFmpeg by default for much faster performance:

# Fast FFmpeg-based reversal (default)
vidtoolz reverse input.mp4 output.mp4

# Original MoviePy-based reversal (slower but may work better for some files)
vidtoolz reverse input.mp4 output.mp4 --use-moviepy

The FFmpeg version typically completes in seconds vs minutes for the MoviePy version.

Requirements

• Python 3.9 or later
• The pluggy library for plugin management

Installation

pip install vidtoolz

Developing your plugin

You'll need to have cookiecutter installed.

pipx install cookiecutter

Regular pip will work OK too.

Usage

Run cookiecutter gh:sukhbinder/vidtoolz-plugin and then answer the prompts. Here's an example run:

cookiecutter gh:sukhbinder/vidtoolz-plugin

This will show this. Fill this and the template is ready. Just add your code.

plugin_name []: vidtoolz plugin template demo
description []: Demonstrating https://github.com/sukhbinder/vidtoolz-plugin
hyphenated [vidtoolz-plugin-template-demo]:
underscored [vidtoolz_plugin_template_demo]:
github_username []: sukhbinder
author_name []: Sukhbinder Singh

Development

To contribute to this tool, first checkout the code. Then create a new virtual environment:

# To clone
git clone https://github.com/sukhbinder/vidtoolz.git

# And create a new virtual environment
cd vidtoolz
python -m venv venv
source venv/bin/activate

# In windows
venv\Scripts\activate

Now install the dependencies and test dependencies:

pip install -e '.[test]'

To run the tests:

python -m pytest