# VidConverter - Universal Media Converter

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.7+](https://img.shields.io/badge/python-3.7+-blue.svg)](https://www.python.org/downloads/)
[![FFmpeg](https://img.shields.io/badge/FFmpeg-required-green.svg)](https://ffmpeg.org/)

A powerful, easy-to-use GUI and CLI application for converting videos and audio to any format using FFmpeg. Zero Python dependencies - uses only the standard library!

**Supports:** Windows, macOS, Linux

## Screenshots

GUI

<img width="1440" height="877" alt="image" src="https://github.com/user-attachments/assets/aa9e6535-a2eb-4fba-8c0f-0669d076529c" />


## Quick Start

```bash
# GUI mode (double-click or run)
python vidconverter.py

# CLI mode
python vidconverter.py input.mp4 -f MP4 -p "Balanced H.264"

# Batch processing
python vidconverter.py --batch *.mp4 -f MP4 -p "Balanced H.264"

### YouTube Download + Convert (new)

```bash
# Audio-only download (auto-converts to MP3)
python yt_fetch.py --audio "https://www.youtube.com/watch?v=VIDEO_ID"

# Download and convert with explicit format/profile
python yt_fetch.py --audio --format "Audio Only" --profile "MP3 Standard" "https://www.youtube.com/watch?v=VIDEO_ID"
```

# JSON batch processing (different formats/settings per file)

# YouTube fetcher (CLI)
# Default output folder: ./youtube_downloads
# Requires yt-dlp and FFmpeg

# Audio-only (auto MP3 conversion)
python yt_fetch.py --audio https://www.youtube.com/watch?v=VIDEO_ID

# Video-only (no default conversion)
python yt_fetch.py --video https://www.youtube.com/watch?v=VIDEO_ID

# Specify output directory
python yt_fetch.py --audio --outdir "D:/Media/YT" https://www.youtube.com/watch?v=VIDEO_ID
python vidconverter.py --batch-json examples/batch_example.json

# Create animated GIF from timestamp
python vidconverter.py video.mp4 -f GIF -p "Balanced" -s 5 -d 3
3. Executables will be created in the `dist` folder:
  - VidConverter.exe (GUI)
  - yt_fetch.exe (CLI for YouTube download + convert)

## Features

### Supported Output Formats
- **WebM** - VP9/VP8 codecs with Opus/Vorbis audio
- **MP4** - H.264/H.265 (HEVC) codecs with AAC audio

# Build the YouTube fetcher (console app)
pyinstaller --noconfirm --onefile --console --name "yt_fetch" yt_fetch.py
- **MKV** - Matroska container with multiple codec options

For best YouTube extraction coverage, yt-dlp may ask for a JavaScript runtime.
Installing Node.js and letting yt-dlp auto-detect it can improve format selection.
- **MOV** - QuickTime including ProRes for editing
- **FLV** - Flash video format
- **GIF** - Animated GIFs with optimized palettes
- **Audio Only** - Extract audio as MP3, AAC, FLAC, or WAV
- **Professional Audio** - AIFF, 24-bit WAV, 32-bit Float WAV for audio professionals
- **Image Sequences** - Export to TIFF or PNG frame sequences

### Pre-configured Quality Profiles

Each format includes optimized profiles:
- **High Quality** - Best quality, slower encoding
- **Balanced** - Good quality/speed compromise (Recommended)
- **Fast** - Quick encoding, smaller files
- **Specialized** - Format-specific options (ProRes, HEVC, VP8, etc.)

### Advanced Features
- **JSON batch processing** - Process multiple files with different settings from JSON (NEW!)
- **Live video preview** - See colored ASCII art preview during CLI conversion (NEW!)
- **Integrated file browser** - Built-in folder navigation with media file filtering
- **Smart file browsing** - Navigate folders, see file sizes, filter media files automatically
- **Cross-drive navigation** - Easy drive switching on Windows (Drives button)
- **Custom profile management** - Save, edit, and manage your own encoding presets
- **Settings persistence** - Remembers your last path, format, and profile (saved locally)
- **Custom output naming** - Full control over output filenames
- **Editable parameters** - Manually adjust codec, CRF, preset, bitrate
- **Real-time progress bar** - See conversion progress in real-time
- **Multiple input formats** - Supports all common video/audio formats
- **Smart defaults** - Auto-generates filenames based on input and format
- **Professional formats** - H.265 10-bit, AIFF, high bit-depth audio, image sequences

## Running the Application

VidConverter works in **two modes**: GUI (graphical) and CLI (command-line)

### GUI Mode (Graphical Interface)

#### Option 1: Run as Python Script (All Platforms)

**Prerequisites:**
1. **Python 3.7+** - Download from https://www.python.org/downloads/
2. **FFmpeg** - Install via:
   - **Windows:** Download from https://www.gyan.dev/ffmpeg/builds/
   - **macOS:** `brew install ffmpeg`
   - **Linux:** `apt install ffmpeg` or `dnf install ffmpeg`

**Run:**
```bash
python vidconverter.py
```

### CLI Mode (Command-Line Interface)

VidConverter includes a powerful CLI with ASCII art!

**Quick Examples:**
```bash
# Show available formats
python vidconverter.py --list-formats

# Show profiles for MP4
python vidconverter.py --list-profiles MP4

# Convert a video
python vidconverter.py video.mp4 -f MP4 -p "Balanced H.264"

# Extract audio
python vidconverter.py video.mp4 -f "Audio Only" -p "MP3 Standard"

# Create GIF
python vidconverter.py video.mp4 -f GIF -p "Balanced"

# Create GIF from specific timestamp (5 seconds, 3 second duration)
python vidconverter.py video.mp4 -f GIF -p "Balanced" -s 5 -d 3

# Create GIF with time range (HH:MM:SS format)
python vidconverter.py video.mp4 -f GIF -p "Balanced" -s 00:00:10 -e 00:00:15

# Convert with live color preview (NEW!)
python vidconverter.py video.mp4 -f MP4 -p "Balanced H.264" --preview

# Convert with fast preview updates (every 1 second)
python vidconverter.py video.mp4 -f MP4 -p "Balanced H.264" --preview --preview-interval 1.0

# Show the octopus mascot!
python vidconverter.py --show-octopus
```

#### Live Video Preview (CLI)

The CLI now supports live colored ASCII art video preview during conversion! This feature replaces the standard progress bar with a real-time display of the video being converted.

**Features:**
- 24-bit color ANSI art (full RGB)
- Automatic terminal size detection
- Configurable update interval
- Cross-platform support (Windows, Linux, macOS)
- Automatic fallback if terminal doesn't support colors

**Usage:**
```bash
# Enable preview with default settings (updates every 2 seconds)
python vidconverter.py input.mp4 -f MP4 -p "Balanced H.264" --preview

# Adjust update frequency (e.g., every 1 second for more frequent updates)
python vidconverter.py input.mp4 -f MP4 -p "Balanced H.264" --preview --preview-interval 1.0

# Faster updates (every 0.5 seconds) - may slow down conversion slightly
python vidconverter.py input.mp4 -f MP4 -p "Balanced H.264" --preview --preview-interval 0.5
```

**Note:** The preview updates at intervals to avoid impacting conversion performance. The actual conversion speed is not significantly affected.

#### JSON Batch Processing (CLI)

Process multiple files with different formats and settings using JSON job definitions. Perfect for automation and complex workflows!

**Features:**
- Different format/profile per file
- Per-job timestamp settings
- Validation before processing
- Stop-on-error or continue-on-error modes
- Detailed success/failure reporting

**Usage:**
```bash
# Process jobs from JSON file
python vidconverter.py --batch-json examples/batch_example.json

# Continue processing even if a job fails
python vidconverter.py --batch-json jobs.json --no-stop-on-error
```

**Example JSON:**
```json
{
  "jobs": [
    {
      "input": "video1.mp4",
      "format": "WebM",
      "profile": "Balanced VP9"
    },
    {
      "input": "video2.mkv",
      "format": "GIF",
      "profile": "Balanced",
      "start": "5",
      "duration": "3"
    }
  ]
}
```

**See [JSON_BATCH_GUIDE.md](JSON_BATCH_GUIDE.md) for complete documentation and examples.**

**Full CLI Documentation:** See [docs/CLI_GUIDE.md](docs/CLI_GUIDE.md) for complete command reference, examples, and batch processing scripts.

#### Option 2: Build Executable (Windows)

**Prerequisites:**
1. **Install Python** (if not already installed)
   - Download from https://www.python.org/downloads/
   - Make sure to check "Add Python to PATH" during installation

2. **Install FFmpeg** (optional for bundling)
   - Download from https://www.gyan.dev/ffmpeg/builds/ (get the full build)
   - Extract `ffmpeg.exe` and `ffprobe.exe` to this directory

**Build Steps:**
1. Open Command Prompt in this folder
2. Run: `build_exe.bat`
3. The executable will be created in the `dist` folder

### Alternative Manual Build

If you prefer to build manually:

```bash
# Install PyInstaller
pip install pyinstaller

# Build the executable
pyinstaller --noconfirm --onefile --windowed --name "VidConverter" vidconverter.py
```

**Note:** The executable will work on systems that don't have FFmpeg installed only if you:
- Bundle ffmpeg.exe and ffprobe.exe with the executable, OR
- Ensure FFmpeg is in the system PATH on the target machine

**Settings:** User preferences and custom profiles are saved in `settings.json` in the same folder as the executable, making the application fully portable.

## Using the Application

### File Selection

**Classic Browse Dialog:**
- Click **Browse** button to use the standard file picker

**Integrated Folder Browser (Always Visible):**
- Navigate folders in the left pane (double-click to enter)
- See media files with sizes in the right pane
- Use **Up** to go to parent folder
- Use **Home** to go to your home directory
- Use **Drives** to switch between drives (Windows)
- At drive roots (C:\, D:\, etc.), other drives appear at the top of the folder list
- Double-click a file or click **Select File**

### Conversion Process

1. Select your input file (using browse dialog or folder browser)
2. Select an **Output Format** (WebM, MP4, MKV, AVI, MOV, FLV, GIF, Audio, etc.)
3. Choose an **Encoding Profile** for your desired quality/speed balance
4. Adjust the **Output Filename** if needed (auto-generated by default)
5. (Optional) Modify **Advanced Settings** for fine-tuning
6. Click **Convert** and watch the real-time progress bar

### Custom Profiles

- Click **Save Custom** to save current codec settings as a reusable profile
- Custom profiles appear with a wrench icon prefix in the profile dropdown
- Click **Edit** to update a custom profile with current settings
- Click **Delete** to remove a custom profile
- All custom profiles are saved in `settings.json`

### Tips

- The app remembers your last browsed location, format, and profile
- Only media files are shown in folder browser (videos and audio)
- File sizes are displayed to help you choose files
- Settings are portable - stored in the same folder as the executable

## Format & Profile Guide

For detailed information about all supported formats, quality profiles, CRF values, and codec options, see [docs/FORMAT_GUIDE.md](docs/FORMAT_GUIDE.md).

## Common Use Cases

### Convert video to MP4
- Select **MP4** format
- Choose **Balanced H.264** profile
- Universal compatibility for all devices

### Extract audio from video
- Select **Audio Only** format
- Choose **MP3 Standard** or **FLAC Lossless**
- Perfect for music extraction

### Create animated GIF
- Select **GIF** format
- Choose quality based on file size needs
- Automatic palette optimization

### Professional video editing
- Select **MOV** format
- Choose **ProRes 422** or **ProRes Proxy**
- Large files but ideal for editing software

### Compress large videos
- Select **MP4** format
- Choose **Balanced H.265** profile
- Best compression ratio (HEVC)

## Adding to Windows Start Bar

1. Build the executable using the steps above
2. Navigate to the `dist` folder
3. Right-click `VidConverter.exe`
4. Select "Pin to taskbar"

Or create a shortcut and place it in:
`C:\Users\YourUsername\AppData\Roaming\Microsoft\Internet Explorer\Quick Launch\User Pinned\TaskBar`

**Note:** Keep `VidConverter.exe` and `settings.json` in the same folder for settings to persist.

## Troubleshooting

**"FFmpeg not found" error:**
- Make sure ffmpeg.exe and ffprobe.exe are either:
  - In the same folder as the executable, or
  - Added to your system PATH

**Conversion fails:**
- Check that the input file is a valid video file
- Try a different encoding profile
- Make sure you have write permissions in the output directory

## Contributing

We welcome contributions! Whether it's:
- Adding new format profiles
- Improving the UI/UX
- Fixing bugs
- Writing documentation
- Adding tests

Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Testing

VidConverter includes a comprehensive test suite with **48 tests** covering:
- All format conversions
- CLI functionality
- Batch processing
- Statistics tracking
- Queue management

```bash
# Run all 48 tests
python test_vidconverter.py

# Run specific test category
python -m unittest test_vidconverter.TestConversion
python -m unittest test_vidconverter.TestBatchQueue
python -m unittest test_vidconverter.TestConversionStats
```

See [TEST_GUIDE.md](TEST_GUIDE.md) for detailed testing documentation.

## Project Statistics

- **Lines of Code:** ~3,000
- **Test Coverage:** 48 automated tests
- **Supported Formats:** 9 major formats with 30+ profiles
- **Python Dependencies:** 0 (uses only standard library!)
- **Supported Platforms:** Windows, macOS, Linux

## Roadmap

- [ ] Video preview with visual trimming
- [ ] GPU-accelerated encoding (NVENC, QuickSync, VideoToolbox)
- [ ] Preset manager for social media platforms
- [ ] Drag-and-drop file support
- [ ] Dark mode theme
- [ ] Multi-language support

## License

MIT License - see [LICENSE](LICENSE) file for details.

Free to use, modify, and distribute. If you find it helpful, a star on GitHub would be appreciated! ⭐

## Acknowledgments

- Built with Python and Tkinter
- Powered by [FFmpeg](https://ffmpeg.org/)
- Inspired by the need for a simple, cross-platform video converter
