🕯️  E m b e r

The cozy floating desktop music companion that refuses to get in your way.

Slim as a ribbon  ·  Warm as lamplight  ·  Endlessly yours

🚀 Pre-built binaries ready for instant download:

• 🪟 Windows Desktop: Download standalone Ember.exe — double-click and play, no Python or setup required.
• 📱 Android Mobile: Download Ember.apk — install directly on your smartphone for on-the-go music streaming.

Compact Desk Ribbon Tucks neatly above your code, terminal, or browser without stealing focus

Expanded Studio Panel Full queue management, live lyrics, vinyl mechanics & theme selection

---

☕   The Essence

Most music applications demand half your screen, nag you with notifications, and swallow hundreds of megabytes of RAM.

Ember is built on an entirely different philosophy: quiet presence.

• 🌙 Floats seamlessly over your code editor, document, or game window.
• 🕯️ Warm organic palette designed specifically for late-night creative flow and tired eyes.
• ⚡ Zero-latency playback that streams directly from the cloud without storing gigabytes of bloat.
• 🎧 Never steals keyboard focus — control everything with gentle global hotkeys or native Windows media keys.

---

✨   The Experience

Feature	The Vibe & Craft
📦 Standalone Windows Binary	Single portable Ember.exe with zero installation or Python prerequisites. Clean windowed launch with no console flicker.
📁 Dedicated Playlists Tab	Create, view, queue, and manage custom playlists. Remove individual tracks or delete playlists with cascade cleanup.
🔗 Universal Link Importer	Paste YouTube or Spotify playlist links directly. Playback starts immediately with an optional one-click [Save Playlist] prompt.
💾 1-Click Offline Exporter	Save streaming tracks to your local library (.m4a / .flac) complete with high-res artwork and embedded ID3/MP4 metadata.
📊 Dynamic Waveform Visualizer	Interactive audio seekbar rendered with animated amplitude bars tuned to playback progression.
🌙 Smart Sleep Timer	Drift off with 15m, 30m, 45m, or 60m timers featuring a cosine-eased gentle volume fade-out to zero before pausing.
🎧 Audio Device Switcher	Hot-swap playback between Headphones, USB DAC, Bluetooth earbuds, and Speakers directly from preferences.
⚡ Persistent LRU Cache	Local byte-stream cache (500MB cap) eliminating repeat network calls and enabling instant replay.
🪟 Native Windows SMTC	Full Windows 10/11 lock screen controls, system volume overlays, and physical hardware media keys.
🎮 Discord RPC & Scrobbling	Real-time Discord Rich Presence with elapsed timers plus ListenBrainz / Last.fm scrobble engine.
🔍 Search & Paste	Instant search across YouTube Music guest API with 350ms debouncing and link detection.
🎤 Live Lyrics Tab	Sing along with synchronized and plain lyrics quietly fetched from LRCLIB.
🔀 Smart Shuffle & Repeat	Non-destructive upcoming queue shuffle plus 3-way cycleable repeat modes (off ➔ all ➔ one).
⚡ Variable Speed	Dial playback rate smoothly between 0.75x, 1.0x, 1.25x, and 1.5x with native pitch preservation.
🪟 Desktop Glass Opacity	Dial window translucency between 60% and 100% to let your desktop wallpaper bleed gently through.
🎛️ Hand-Crafted Instruments	Rotating vinyl disc with specular sheen, spring-damper equalizer bars, and circular volume dial.
🎨 Dynamic Palette Switcher	Swap instantly between five hand-curated themes (Amber, Emerald, Amethyst, Solar, Rose).
⌨️ Universal Hotkeys	Global key chords for every common action, fully customizable with conflict detection.

---

🎨   Handcrafted Theme Palettes

Ember ships with 5 unified color stories inspired by natural stones and ambient warmth:

  🕯️ Amber     │ Deep espresso base, roasted coffee, and luminous golden amber light
  🌿 Emerald   │ Forest moss, midnight pine, and radiant emerald glow
  🔮 Amethyst  │ Velvet twilight, dark slate, and deep mystical violet luminescence
  ☀️ Solar     │ Sun-baked terracotta, warm earth, and bright solar radiance
  🌸 Rose      │ Smoky plum, evening rouge, and delicate soft blush accents

Every widget, vinyl reflection, text label, and progress slider re-skins instantly at runtime without restarting the application.

---

🚀   Quickstart

🌟 Option 1: Pre-built Releases (Recommended for Users)

Zero setup required — grab the binary for your platform and enjoy:

• 🪟 Windows Desktop: Download Ember.exe (or Ember-v1.0.0-windows-x64.zip) from GitHub Releases. Double-click to run silently on your desktop.
• 📱 Android Mobile: Download Ember.apk from GitHub Releases. Tap to install on your Android device (Android 5.0+).

🛠️ Option 2: Run Desktop from Source (Python)

# 1. Clone the repository
git clone https://github.com/AIwolfie/Ember.git
cd Ember

# 2. Automated setup
install.bat

# 3. Launch
launch.bat

(Prefer live diagnostic console logs while developing? Run launch_debug.bat instead.)

📱 Option 3: Run Mobile from Source (Flutter)

# 1. Navigate to the flutter project
cd ember_flutter

# 2. Fetch dependencies
flutter pub get

# 3. Launch on connected Android device or emulator
flutter run

📦 Option 4: Build Your Own Standalone .exe (Windows)

Want to compile the desktop .exe yourself? A 1-click build script is included:

build_exe.bat

This automatically compiles ember.spec using PyInstaller and outputs the portable binary to dist/Ember.exe.

📱 Option 5: Build Your Own Android APK (Mobile)

To package your own release APK:

cd ember_flutter
flutter pub get
flutter build apk --release

The optimized release APK will be generated at build/app/outputs/flutter-apk/app-release.apk. For per-ABI split APKs (~25MB each):

flutter build apk --split-per-abi

---

⌨️   Default Hotkeys Cheatsheet

Control your soundtrack from inside any application, IDE, or full-screen game:

Shortcut	Action	Scope
Ctrl + Alt + Space	Play  /  Pause	Global
Ctrl + Alt + →	Next Track	Global
Ctrl + Alt + ←	Previous Track (or restart current)	Global
Ctrl + Alt + E	Toggle Expanded Panel	Global
Ctrl + Alt + ↑	Expand Ribbon to Panel	In-App
Ctrl + Alt + ↓	Collapse Panel to Ribbon	In-App
Ctrl + Alt + F	Jump to & Focus Search Field	In-App

💡 Tip: All key combinations can be freely re-mapped in the ⚙ Preferences dialog.

---

🏛️   Architecture & Engineering

Ember/
├── ember/
│   ├── app.py             → Application lifecycle, rotating logs, hotkey hooks
│   ├── cache.py           → Persistent LRU audio byte-stream disk cache (500MB cap)
│   ├── catalog.py         → YouTube Music guest API with exponential backoff
│   ├── config.py          → Palette tokens, geometry constants, design tunables
│   ├── discord_rpc.py     → Discord Rich Presence integration
│   ├── exporter.py        → 1-click offline FLAC / M4A exporter & ID3 tagger
│   ├── icons.py           → FontAwesome 6 vector icons with dynamic tinting
│   ├── importer.py        → Universal YouTube & Spotify playlist importer
│   ├── jobs.py            → Asynchronous QRunnable workers with isolated thread pools
│   ├── lyrics.py          → LRCLIB lyrics resolution & timestamp parser
│   ├── models.py          → Song dataclass & serialization contracts
│   ├── panel.py           → Floating surface, ribbon, tabs, playlists & waveform
│   ├── player.py          → PlaybackCore, queue manager & auto-recovery engine
│   ├── scrobbler.py       → ListenBrainz & Last.fm scrobble engine
│   ├── settings_dialog.py → Preferences modal, hotkey binder & device switcher
│   ├── smtc.py            → Native Windows System Media Transport Controls
│   ├── storage.py         → SQLite engine for playlists, favorites & history
│   ├── stream.py          → Direct audio stream extraction with yt-dlp
│   ├── theme.py           → Dynamic Qt stylesheets compiled with string.Template
│   ├── toast.py           → Non-intrusive floating desktop notification toast
│   ├── tray.py            → System tray icon & single-instance lock guard
│   └── utils.py           → Formatters, clock helpers, and text elision
├── tests/                 → Automated pytest suite (89 tests passing)
├── build_exe.bat          → 1-click standalone Windows .exe compiler
├── ember.ico              → Official multi-resolution Ember application icon
├── ember.spec             → PyInstaller standalone release specification
├── install.bat            → Automated Windows environment installer
├── launch.bat             → Clean silent application launcher
├── launch_debug.bat       → Diagnostic console launcher
├── requirements.txt       → Pinned dependency specifications
├── CREDITS.md             → Full project attribution
└── LICENSE                → MIT License

---

📱 App Deployments & OTA Updates

Ember uses a seamless CI/CD pipeline allowing instant Over-The-Air (OTA) patching via Shorebird, meaning users never have to manually reinstall APKs to get your latest dart code!

Whenever you push to the main branch, the pipeline will perfectly choose the deployment strategy based on exactly one thing: the version in ember_flutter/pubspec.yaml.

1. Pushing Silent OTA Patches (No Version Bump) If you make a bug fix or UI change to the Flutter code and want to silently push it to all users immediately:

• DO NOT change the version in pubspec.yaml! Leave it exactly as is.
• Commit and push to main.
• Result: The CI pipeline will automatically run shorebird patch. All users around the world will instantly download this patch in the background and the app will notify them to restart!

2. Publishing a New Base APK Release (Version Bump) If you add complex new native Android packages or major features and need to completely replace the APK:

• BUMP the version: in pubspec.yaml (e.g., from 1.0.1+2 to 1.0.2+3).
• Commit and push to main.
• Result: The CI pipeline will build a brand new Base Release containing the Shorebird SDK, push it as a new GitHub Release tag, and users will see an "Update Available 🚀" prompt inside their app asking them to download the new APK!

Contributing & Pull Requests

When you push to any branch other than main (like a PR), the secondary branch_build.yml Action runs. It securely compiles a standard preview APK and commits it to the root folder as Android_APK/Preview_Build.apk, allowing PR reviewers to easily download and test your code without compiling!

---

🧪   Verification & Testing

Ember features a comprehensive automated test suite covering models, themes, database integrity, playlists, and resilience:

py -3 -m pytest tests/ -v

(All 89 tests passing across all subsystems.)

---

🤝   Attribution & Credits

Ember is built with care, craft, and love for music:

• Mayank Malaviya (@AIwolfie · aiwolfie.online) — Original creator, lead architect, and maintainer of Ember.
• Muhammad Taezeem Tariq Matta (@taezeem14) — Contributor — development improvements and project upgrades.
• Kenil Ribadiya (kenilribadiya.in) — Contributor — Mobile App Architect & Android Flutter Implementation.

For full details, see CREDITS.md.

---

Distributed under the MIT License

_{Crafted for late nights, cold tea, and warm code. Enjoy the sound. 🎵}