Cross-platform video file management and organization tool for Linux, macOS, Windows (Git Bash), and WSL.
| Change | State |
|---|---|
| 93% smaller main script (6,590 → 465 lines) | ✅ Shipped |
| 12 independent modules for maintainability | ✅ Shipped |
| All core functionality preserved from previous versions | ✅ Shipped |
| Improved tab completion for all commands | ✅ Shipped |
| Subtitle generation (OpenAI Whisper backend, GPU, parallel jobs, skip-existing, dry-run) | ✅ Shipped |
| 158-test automated suite (full integration coverage) | ✅ Shipped |
Read about the modularization journey →
- Setup Instructions
- Features
- Usage
- Command Reference
- Configuration
- Environment Requirements
- Documentation
- Architectural Decisions
- Development Log
- License
- Support
git clone https://github.com/emaag/vmgr.git
cd vmgr
./install.shManual setup:
chmod +x video-manager-ultimate.sh
./video-manager-ultimate.sh- File Renaming — bracket notation formatting (
[Studio] filename.mp4) - Directory Flattening — move files from subdirectories to top level
- Duplicate Detection — SHA-256 hash-based with detailed reports
- File Organization — automatic sorting by subfolder names with undo functionality
- Batch Processing — multi-directory operations with accumulated statistics
- Image Conversion — convert PNG/WebP/HEIC to JPG (requires ImageMagick)
- Subtitle Generation — OpenAI Whisper backend; GPU acceleration, parallel jobs, skip-existing, dry-run, size/date filters, interactive editing. Requires
pip install openai-whisper(or whisper.cpp)
- Multi-Drive Catalog — index and search media across drives; UI exists but scanning is a stub.
- Organize files by matching subfolder names
- Exclude patterns (e.g., "full" folders)
- Undo/rollback with operation logging
- Progress tracking
- Configurable default paths
- Command-line and interactive modes
- Interactive menu system
- Command-line interface for automation
- Color-coded output
- Real-time progress indicators
- Comprehensive logging
- Dry run mode
- Dry run preview mode
- Conflict resolution
- Error handling and recovery
- Path validation
- Operation logging and undo support
# Check version
./video-manager-ultimate.sh --version
# Preview changes (dry run)
./video-manager-ultimate.sh --dry-run rename /path/to/videos
# Apply changes
./video-manager-ultimate.sh rename /path/to/videos
# Launch interactive menu
./video-manager-ultimate.sh# Rename with bracket notation
./video-manager-ultimate.sh rename /path
# Flatten directory structure
./video-manager-ultimate.sh flatten /path
# Find duplicates
./video-manager-ultimate.sh duplicates /path
# Batch processing
./video-manager-ultimate.sh batch# Basic subtitle generation
./video-manager-ultimate.sh subtitles /path
# Advanced options
./video-manager-ultimate.sh --model medium --format srt --language en subtitles /path
# GPU-accelerated with parallel processing
./video-manager-ultimate.sh --gpu --parallel 4 subtitles /path
# Enable speaker diarization
./video-manager-ultimate.sh --speaker-diarization --model large subtitles /path# Organize files by subfolder names
./video-manager-ultimate.sh --organize-target /folders --organize-search /search --organize
# Undo last operation
./video-manager-ultimate.sh --undo-organize
# List undo operations
./video-manager-ultimate.sh --list-undo# New collection setup (flatten + rename + detect duplicates)
./video-manager-ultimate.sh workflow-new /path
# Deep clean (dash removal + spacing + bracket notation)
./video-manager-ultimate.sh workflow-clean /pathAccess settings through the interactive menu: Main Menu → Settings → Organize Settings
Or use command-line flags:
--organize-target <path> # Set default target folder
--organize-search <path> # Set default search path
--dry-run # Preview without changes
--verbose / --quiet # Output verbosity| Requirement | Notes |
|---|---|
| Bash | 4.0+ |
| SHA-256 utility | sha256sum or shasum |
| Standard Unix utilities | find, sed, awk, grep |
| Component | Purpose |
|---|---|
Whisper (pip install -U openai-whisper or whisper.cpp) |
Subtitle generation |
| ffprobe | Video metadata |
| pyannote-audio | Speaker diarization |
| Platform | Notes |
|---|---|
| Linux | Native support |
| macOS | Requires Bash 4.0+ |
| WSL | Windows Subsystem for Linux |
| Git Bash | Windows |
Supported path formats: Unix (/home/user/Videos), WSL (/mnt/c/Users/user/Videos), Windows (C:\Users\user\Videos, auto-converted).
Supported video formats: mp4, mkv, avi, mov, wmv, flv, webm, m4v, mpg, mpeg, 3gp.
- README.md — this file (overview and quick reference)
- INSTALLATION-GUIDE.md — setup instructions and troubleshooting
- VIDEO-MANAGER-BASH-GUIDE.md — complete feature documentation
- QUICK-REFERENCE.md — command cheat sheet
- ADVANCED-FEATURES-v1.2.md — advanced configuration guide
- SUBTITLE-FEATURE-GUIDE.md — subtitle generation guide
- Modular design — 12 independent modules.
- Clean separation — Foundation, Core Features, Advanced Features.
- Maintainable — each module focused on a single responsibility.
- Extensible — easy to add new features.
- CI/CD — automated testing on Ubuntu and macOS via GitHub Actions.
Logs
- Location:
~/.video-manager-logs/ - Format: timestamped with operation details
- Access: via menu (Utilities → View Logs) or direct file access
Undo operations
- Automatic logging of organize operations
- Undo log location:
~/.video-manager-logs/undo-history/ - Access via menu or CLI:
--undo-organize,--list-undo
Version history — click to expand
- File organization by subfolder names
- Undo/rollback functionality
- Progress bar for operations
- Command-line flags for organization
- Configurable default paths
- Auto-edit mode for subtitles
- Whisper-based subtitle generation
- GPU acceleration
- Parallel processing
- Speaker diarization
- Multiple output formats
- Initial release
- Bracket notation renaming
- Directory flattening
- Duplicate detection
- Batch processing
Created for personal video management. Free to use and modify.
Built-in help:
./video-manager-ultimate.sh --helpInteractive menu: Utilities → System Information for diagnostics.