📝 | Update README.md

README.md

@@ -1,2 +1,112 @@
-# Tunetti
+# Tunetti 🎵
 
+[![Quality Gate Status](https://sonarqube.huitsinnevada.fi/api/project_badges/measure?project=Tunetti&metric=alert_status&token=sqb_a08ffa8615e77ac20c6f7e0aa58a93e643a85666)](https://sonarqube.huitsinnevada.fi/dashboard?id=Tunetti)
+
+A desktop YouTube Music player built with Python and Qt6. Search, play, and manage your music library — all from a native GUI, no browser needed.
+
+> **Disclaimer:** This project is approximately 99% AI-generated code.
+
+---
+
+## Features
+
+- **YouTube Music search & playback** – Search songs, albums, and artists directly from the app.
+- **Rich Qt6 GUI** – Sleek, dark-themed interface with custom widgets (glassmorphism cards, animated nav buttons, smooth sidebar).
+- **Discord Rich Presence** – Shows what you're listening to on your Discord profile.
+- **Play history & statistics** – Every play is logged. View your most-played tracks, play counts by day, and listening trends.
+- **Favourites** – Mark songs as favourites and quickly access them.
+- **Audio visualizer** – Real-time FFT-based spectrum analyser that reacts to the current playback.
+- **Playback controls** – Play, pause, skip, seek, volume, mute, loop, and queue management.
+- **Configurable** – Settings stored in `~/.config/tunetti/config.json` (XDG-compliant). Volume, Discord RPC toggle, visualizer toggle, and more.
+- **Lightweight** – Downloads audio on-the-fly via yt-dlp; no permanent music library to store.
+
+---
+
+## Requirements
+
+- **Python 3.10+**
+- A **PulseAudio** or **PipeWire** audio system (Linux)
+- **FFmpeg** installed and available in `PATH`
+
+## Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/your-org/tunetti.git
+cd tunetti
+
+# Create and activate a virtual environment
+python -m venv .venv
+source .venv/bin/activate
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+> **Note:** `PySide6` provides the Qt6 bindings. On some distributions you may need to install system packages like `libegl1` or `libxkbcommon0` as well.
+
+## Usage
+
+```bash
+# Normal mode
+python main.py
+
+# Verbose/debug mode (shows yt-dlp and Qt FFmpeg internals)
+TUNETTI_VERBOSE=1 python main.py
+```
+
+On first launch, Tunetti creates `~/.config/tunetti/` and populates it with default settings.
+
+### Environment Variables
+
+| Variable | Description |
+|---|---|
+| `TUNETTI_VERBOSE` | Set to `1`, `true`, or `yes` to enable debug logging. |
+
+---
+
+## Project Structure
+
+```
+Tunetti/
+├── main.py                # Entry point & logging setup
+├── gui.py                 # All UI components (window, search, playback bar, visualizer, stats, settings)
+├── player.py              # Audio playback, download workers, queue management
+├── config.py              # XDG-compliant configuration loader & migrator
+├── music_db.py            # SQLite database layer (history, favourites, stats)
+├── discord_rpc.py         # Discord Rich Presence integration via pypresence
+├── requirements.txt       # Python dependencies
+├── sonar-project.properties  # SonarQube analysis config
+└── .gitea/
+    └── workflows/
+        └── sonar.yaml     # Gitea Actions CI pipeline
+```
+
+## Configuration
+
+Settings are persisted in `~/.config/tunetti/config.json` and include:
+
+| Key | Default | Description |
+|---|---|---|
+| `volume` | `50` | Playback volume (0–100) |
+| `max_history` | `5000` | Maximum history entries |
+| `discord_rpc_enabled` | `true` | Enable Discord Rich Presence |
+| `visualizer_enabled` | `true` | Enable the audio spectrum visualizer |
+| `db_path` | `~/.config/tunetti/music_history.db` | SQLite database location |
+
+## Dependencies
+
+| Package | Purpose |
+|---|---|
+| [yt-dlp](https://github.com/yt-dlp/yt-dlp) | YouTube audio download & search |
+| [ytmusicapi](https://github.com/sigma67/ytmusicapi) | YouTube Music search API |
+| [PySide6](https://pypi.org/project/PySide6/) | Qt6 GUI framework |
+| [pypresence](https://github.com/qwertyquerty/pypresence) | Discord Rich Presence |
+
+## CI / Quality
+
+The project uses SonarQube for static analysis, with a Gitea Actions workflow defined in `.gitea/workflows/sonar.yaml`.
+
+## License
+
+See [LICENSE](./LICENSE).