A fast and efficient video trimming toolkit with both a web interface and command-line tool for MP4 video processing. Features visual trimming with drag-to-scrub sliders and automatic audio extraction.

Documentation: https://nipunbatra.github.io/video-toolkit/

Features

Prerequisites

Installing ffmpeg

Platform Command
macOS brew install ffmpeg
Ubuntu/Debian sudo apt update && sudo apt install ffmpeg
Fedora/CentOS sudo dnf install ffmpeg
Windows Download from ffmpeg.org or use winget install FFmpeg

Installation

Step 1: Download and make executable in one step

curl -O https://raw.githubusercontent.com/nipunbatra/video-toolkit/main/trim-convert.sh && chmod +x trim-convert.sh

Step 2: Verify the script works

./trim-convert.sh --help

Manual Install

Step 1: Clone this repository

git clone https://github.com/nipunbatra/video-toolkit.git
cd video-toolkit

Step 2: Make the script executable

chmod +x trim-convert.sh

Note: The chmod +x command grants execute permission to the script file. This is required for shell scripts to run.

Step 3: Test the installation

./trim-convert.sh --help

System-wide Installation (Optional)

Step 1: Copy script to system directory

sudo cp trim-convert.sh /usr/local/bin/trim-convert

Note: The sudo command requires administrator privileges to copy files to system directories like /usr/local/bin/.

Step 2: Test system-wide access

trim-convert --help

Now you can use trim-convert from any directory.

Gradio Web Interface

For an interactive video trimming experience, use the web interface:

Video Trimmer Interface

Quick Start

# Install dependencies
pip install -r requirements.txt

# Launch the web interface
./run_demo.sh

Features

The web interface automatically converts times and calls the command-line script for processing.

Google Drive Setup (Optional)

To enable Google Drive integration:

  1. Create OAuth credentials: Follow instructions in SIMPLE_GOOGLE_SETUP.md
  2. Download oauth_credentials.json and place in this directory
  3. Run the app - it will open your browser for one-time authentication
  4. Done! Browse your entire Google Drive and upload results back

Note: Google Drive integration is completely optional - the app works perfectly without it.

File Permissions

Understanding Script Permissions

Shell scripts require execute permission to run. When you download a script, it typically doesn’t have execute permission by default for security reasons.

Setting Execute Permission

chmod +x trim-convert.sh

Verifying Permissions

Check if the script has execute permission:

ls -l trim-convert.sh

Look for x in the permissions (e.g., -rwxr-xr-x). The x indicates execute permission.

Common Permission Issues

Command Line Usage

./trim-convert.sh [options] input.mp4

Options

Option Description
-s, --start TIME Start time (format: HH:MM:SS or seconds)
-e, --end TIME End time (format: HH:MM:SS or seconds)
-o, --output PREFIX Output file prefix (default: “trimmed”)
-h, --help Show help message

Examples

Basic Trimming

# Trim from 1m30s to 5m45s
./trim-convert.sh -s 00:01:30 -e 00:05:45 video.mp4

# Trim from start to 10 minutes
./trim-convert.sh -e 00:10:00 video.mp4

# Trim from 2 minutes to the end
./trim-convert.sh -s 00:02:00 video.mp4

Advanced Usage

# Custom output name
./trim-convert.sh -o my_clip -s 00:01:30 -e 00:05:45 video.mp4

# Process entire file (extract audio only)
./trim-convert.sh video.mp4

# Using seconds instead of HH:MM:SS format
./trim-convert.sh -s 90 -e 345 video.mp4

# Batch processing multiple files
for file in *.mp4; do
    ./trim-convert.sh -s 00:00:10 -e 00:01:00 "$file"
done

Time Format Options

How It Works

  1. The script analyzes the input video to determine if it can use stream copying (no re-encoding) based on keyframe positioning
  2. It attempts to use the fastest method possible while maintaining quality
  3. If stream copying would result in imprecise cuts, it falls back to re-encoding
  4. The audio track is extracted as a separate AAC file

Output

Technical Details

Demo Videos

This repository includes sample copyright-free videos for testing:

File Description Source License
demo/sample-10s.mp4 10-second test pattern Generated with ffmpeg Public Domain
demo/sample-30s.mp4 30-second test pattern Generated with ffmpeg Public Domain

All demo videos are verified to be free to use, modify, and distribute.

Performance Notes

Troubleshooting

Common Issues

Problem Solution
“ffmpeg not found” Install ffmpeg using your package manager
“Permission denied” Run chmod +x trim-convert.sh to make script executable
“Invalid time format” Use HH:MM:SS or seconds format
“No keyframes found” Video will be re-encoded (slower but precise)
“Command not found” Check if script is in current directory or PATH
“Operation not permitted” Use sudo for system-wide installation

Performance Tips

Requirements

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📖 Documentation Website

This repository has an auto-generated documentation website at: https://nipunbatra.github.io/video-toolkit

How Documentation Works

Making Documentation Changes

  1. Edit this file: README.md (you’re reading it now!)
  2. Commit and push: git add . && git commit -m "Update docs" && git push
  3. Done: Website updates automatically in ~2 minutes

⚠️ Important: Never edit files in the docs/ folder - they’re auto-generated!