Ghost Kitty Audio Converter

Universal batch audio converter with a cyberpunk-themed interface and unlimited dynamic themes.

Features  •  Quick Start  •  Usage  •  Formats  •  Shortcuts  •  Contributing

---

Features

Unlimited Dynamic Themes

• Procedural HSV colour generation produces infinite unique cyberpunk themes
• 12+ hand-tuned presets (Vaporwave, Synthwave Sunset, Neon Tokyo, and more)
• Live theme switching — no restart required
• All UI elements recolour instantly

Universal Audio Conversion

• Input: MP3, WAV, FLAC, OGG, OPUS, AAC, M4A, WMA, AIFF, APE, WV, WebM, CAF, AMR, AC3, DTS, and video containers (MP4, AVI, MKV, MOV, etc.)
• Output: MP3, WAV, FLAC, OGG, OPUS, AAC, M4A, WMA, AIFF, ALAC, MP4, AVI
• Four quality tiers per format with descriptive labels (e.g. "320 kbps VBR-0")
• Batch processing with unlimited queue size

Modern GUI

• Clean dark interface with Segoe UI typography
• File details at a glance — duration, bitrate, size, codec — via ffprobe
• Right-click context menu with file info dialog
• Keyboard shortcuts for every action
• Hover tooltips throughout
• Status bar showing FFmpeg version and active theme

Robust Engine

• Version-agnostic FFmpeg discovery (PATH, WinGet, Chocolatey, Scoop, common paths)
• Threaded conversion with real-time progress
• Per-file error reporting in the queue
• Structured logging to ghostkitty_converter.log
• Modular codebase: config.py, audio_converter.py, gui_components.py, main.py

---

Quick Start

Prerequisites

Requirement	Version
Python	3.9 or later
FFmpeg	Any recent release

Install FFmpeg

Windows

winget install FFmpeg

or download from ffmpeg.org, extract to C:\ffmpeg\, and add C:\ffmpeg\bin to your PATH.

Linux

# Debian / Ubuntu
sudo apt update && sudo apt install ffmpeg

# Fedora
sudo dnf install ffmpeg

# Arch
sudo pacman -S ffmpeg

macOS

brew install ffmpeg

Run

# Clone
git clone https://github.com/MAAPS-Studio/ghost-kitty-audio-converter.git
cd ghost-kitty-audio-converter/GHOST\ KITTY\ AUDIO\ CONVERTER

# Launch (no pip install needed — stdlib only)
python main.py

On Windows you can also double-click launch.bat.

---

Usage

1. Add files — click Add Files or Add Folder (or press Ctrl+O / Ctrl+Shift+O).
2. Choose format & quality — pick the target format and quality tier from the dropdowns.
3. Set output folder — defaults to ~/Downloads/GhostKitty_Output.
4. Convert — hit Start Conversion or press F5.
5. Monitor — watch per-file status and the progress bar update in real time.
6. Switch themes — click Random Theme or press Ctrl+T at any time.

---

Supported Formats

Input

Audio	Video (audio extraction)
MP3, WAV, FLAC, OGG, OPUS, AAC, M4A, WMA, AIFF, APE, WV, WebM, CAF, AMR, AC3, DTS	MP4, AVI, MKV, MOV, WMV, 3GP, WebM, FLV

Output

Format	Codec	Quality Range
MP3	libmp3lame	128 – 320 kbps
WAV	PCM s16le	22 kHz – 96 kHz
FLAC	FLAC	Level 0 – 12
OGG	Vorbis	96 – 500 kbps
OPUS	libopus	64 – 256 kbps
AAC / M4A	AAC	96 – 320 kbps
WMA	WMAv2	default
AIFF	PCM s16be	22 kHz – 96 kHz
ALAC	ALAC	lossless

---

Keyboard Shortcuts

Shortcut	Action
Ctrl+O	Add files
Ctrl+Shift+O	Add folder
Ctrl+A	Select all in queue
Delete	Remove selected
Ctrl+T	Random theme
F5	Start conversion
Escape	Stop conversion

---

Project Structure

GHOST KITTY AUDIO CONVERTER/
├── main.py               # Application entry point & GUI
├── config.py             # Constants, format tables, shortcuts
├── audio_converter.py    # FFmpeg discovery, probing, conversion engine
├── gui_components.py     # Theme engine, tooltips, styled widgets
├── launch.bat            # Windows launcher
└── requirements.txt      # Dependency notes

---

Troubleshooting

Problem	Solution
"FFmpeg not found"	Install FFmpeg and ensure it's on your PATH (ffmpeg -version)
Conversion fails	Check ghostkitty_converter.log for the FFmpeg error
GUI looks wrong	Ensure Python 3.9+ with tkinter (included by default)
Slow conversions	Try a lower quality setting, or verify CPU is not thermal-throttling

---

Contributing

Pull requests and issues are welcome. See CONTRIBUTING.md for guidelines.

---

License

MIT

---

Ghost Kitty Audio Converter — built by MAAPS Studio