README_DOCS.md

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

• Web Interface: Interactive Gradio demo with drag-to-trim sliders
• Google Drive Integration: Load videos from and upload results to Google Drive
• Command Line: Fast bash script for automated processing
• Smart Trimming: Visual video scrubbing to find exact cut points
• Audio Extraction: Automatic AAC extraction with built-in player
• Minimal Processing: Stream copying when possible for speed
• Cross-Platform: Works on macOS, Linux, and Windows WSL

Prerequisites

• ffmpeg (version 4.0 or higher) - The core dependency for video processing
• Bash shell - Available on macOS, Linux, and Windows WSL

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

Quick Install (Recommended)

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:

Quick Start

# Install dependencies
pip install -r requirements.txt

# Launch the web interface
./run_demo.sh

Features

• Video Upload: Drag & drop MP4/MOV/AVI files or load from Google Drive
• Google Drive Integration: Browse your entire Google Drive to pick videos
• Visual Trimming: Scrub sliders to find exact start/end points
• Live Preview: Video seeks to slider position for precise editing
• Audio Playback: Built-in player for extracted audio
• Download: Get both trimmed video and AAC audio files
• Google Drive Upload: Upload trimmed files back to any folder in your Google Drive

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

• "Permission denied": Script lacks execute permission - run chmod +x
• "Operation not permitted": Need sudo for system directories
• "Command not found": Script not in current directory or PATH

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

• HH:MM:SS: 00:01:30 (1 minute 30 seconds)
• MM:SS: 01:30 (1 minute 30 seconds)
• Seconds: 90 (90 seconds)
• Decimal seconds: 90.5 (90.5 seconds)

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

• PREFIX.mp4: The trimmed video file
• PREFIX.aac: The extracted audio file

Technical Details

• Uses ffmpeg's stream copying (-c copy) when possible to avoid quality loss
• Falls back to high-quality, fast encoding when necessary (-c:v libx264 -preset ultrafast -crf 17)
• Handles keyframe detection for optimal cutting points
• Works with both relative (seconds) and absolute (HH:MM:SS) time formats

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

• Stream copying: Fastest method, preserves original quality
• Re-encoding: Used when precision is required, high-quality preset
• Memory usage: Minimal - processes videos without loading entire file into memory
• Supported formats: MP4, AVI, MOV, MKV (output always MP4)

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

• Use stream copying when possible by aligning cuts with keyframes
• For bulk processing, consider processing multiple files in parallel
• Use SSD storage for better I/O performance with large files

Requirements

• ffmpeg (version 4.0 or higher)
• Bash shell (version 4.0 or higher recommended)
• Available disk space equal to at least 2x the size of your largest video file

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

• Single source: Edit only this README.md file
• Auto-build: GitHub Actions automatically updates the website
• No manual work: Never touch the docs/ folder
• Live updates: Changes appear on the website when you push to main

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!