♻ | New project structure

README.md

@@ -1,26 +1,84 @@
-# Transmutate
+# Transmutate (Python GUI)
 
-Transmutate is a pure KDE desktop tool for converting images, videos, and audio files. It uses **KDialog** for all interactive prompts and leverages **FFmpeg** and **ImageMagick** under the hood to perform the actual transcoding.
+A modern Python/CustomTkinter rewrite of the original `transmutate.sh` bash script.
+Convert images, videos, and audio using ffmpeg + ImageMagick with a modern, cross-platform GUI.
+
+## Requirements
+
+- Python 3.8+
+- customtkinter (`pip install customtkinter`)
+- Pillow (for animated image detection)
+- ffmpeg (must be in PATH)
+- magick / ImageMagick (optional, provides better WebP/GIF handling)
 
 ## Usage
 
 ```bash
-./transmutate.sh <path/to/image|video|audio>
+cd rewrite
+python transmutate.py <path/to/file>
 ```
 
+The GUI opens automatically and detects the media type of the file.
+
 ## Features
 
-- Select output format, quality, and audio/subtitle tracks via KDE dialogs
-- Convert **images** to PNG, JPG, WebP, AVIF, GIF, or video formats (MP4, MKV, WebM, AVI, MOV)
-- Convert **videos** to MP4, MKV, WebM, AVI, MOV, GIF, or animated WebP
-- Convert **audio** to MP3, FLAC, WAV, OGG, M4A, or AAC
-- Animated GIFs and WebPs can be converted to full video formats
-- GIF/WebP animation options (looping)
-- If multiple audio or subtitle tracks exist, choose which to include
-- Handles filename conflicts by prompting to overwrite or auto-renaming
+### Supported Conversions
 
-## Requirements
+| Source → Target | Options |
+|-----------------|---------|
+| Image → Image   | PNG, JPG, WebP, AVIF, GIF (animated), MP4, MKV, WebM, AVI, MOV (animated) |
+| Image → Video   | MP4, MKV, WebM, AVI, MOV |
+| Image → Audio   | MP3, FLAC, WAV, OGG, M4A, AAC |
+| Video → Image   | PNG, JPG, WebP, AVIF |
+| Video → Video   | MP4, MKV, WebM, AVI, MOV, GIF, WebP (animated) |
+| Video → Audio   | MP3, FLAC, WAV, OGG, M4A, AAC |
+| Audio → Image   | PNG, JPG, WebP, AVIF |
+| Audio → Video   | MP4, MKV, WebM, AVI, MOV |
+| Audio → Audio   | MP3, FLAC, WAV, OGG, M4A, AAC |
 
-- **KDE / KDialog**
-- **FFmpeg**
-- **ImageMagick** (`magick` CLI) — optional, used for better GIF and WebP conversion
+### Per-Conversion Options
+
+- **Quality slider** (0-100, or 0-51 for video CRF) — smooth CustomTkinter slider
+- **Audio quality** slider (for video output)
+- **Audio track selection** (when multiple tracks exist)
+- **Subtitle track selection** (when multiple tracks exist)
+- **Loop toggle** (for GIF/WebP output)
+- **Output path** — same directory as source, auto-renamed on conflict
+
+### Conversion Modes
+
+- **Image → Image**: Direct ffmpeg conversion with quality control
+- **Image → Video**: Animated images are re-encoded with CRF
+- **Image → Audio**: Single frame extracted to audio
+- **Video → Image**: Single frame extraction
+- **Video → Video**: Full conversion with CRF and audio quality control
+- **Video → GIF**: Palettegen-based GIF with quality-dependent dithering
+- **Video → WebP**: Animated WebP output
+- **Audio → Audio**: Format conversion with quality control
+- **Audio → Image**: First frame extracted as image
+- **Audio → Video**: Single frame rendered as video
+
+## Architecture
+
+```
+rewrite/
+├── transmutate.py          # Entry point (CLI → GUI)
+├── transmutate_app/        # Package
+│   ├── __init__.py
+│   ├── gui.py              # CustomTkinter GUI application
+│   └── engine/             # Conversion engine
+│       ├── __init__.py
+│       └── ffmpeg_engine.py  # Command building + execution
+```
+
+## Compared to Bash Version
+
+| Feature | Bash (kdialog) | Python (CustomTkinter) |
+|---------|---------------|------------------|
+| Dependencies | bash, ffmpeg, kdialog | python3, customtkinter, ffmpeg |
+| GUI | Multiple sequential popups | Single unified CustomTkinter window |
+| Stream selection | kdialog checklist | CustomTkinter checkboxes |
+| Quality input | kdialog inputbox | CustomTkinter slider |
+| File overwrite | kdialog yes/no | CustomTkinter dialog + auto-rename |
+| Animated detection | ffprobe | Pillow + ffprobe |
+| Code organization | Single monolithic script | Modular package |