Flowbbler

A sleek, modern desktop client for ListenBrainz built with Rust and QML / Kirigami.

Flowbbler allows you to seamlessly explore your music listening habits, view your top charts (albums, artists, genres), and track your listens in real-time with a fast, lightweight native interface.

---

✨ Features

• Personal Dashboard: View your latest listens and listening statistics.
• Top Charts: Explore your top albums, artists, and favorite genres over custom time frames.
• ListenBrainz Integration: Secure login using your ListenBrainz token.
• Native Performance: Powered by a robust Rust backend and a smooth QtQuick/Kirigami frontend.
• Local Caching: Fast loading times thanks to an optimized local caching layer.

---

🖼️ Screenshots

Here is a glimpse of the application interface:

Login Screen

Home Dashboard

Top Albums

---

📁 Project Structure

flowbbler/
├── qml/                          # Frontend User Interface (QML/Kirigami)
│   ├── components/               # Reusable UI elements
│   │   ├── ArtistCard.qml
│   │   ├── CoverImage.qml
│   │   ├── LoadingSpinner.qml
│   │   ├── StatCard.qml
│   │   └── TrackCard.qml
│   ├── pages/                    # Main application views
│   │   ├── AlbumsPage.qml
│   │   ├── ArtistsPage.qml
│   │   ├── GenresPage.qml
│   │   ├── HomePage.qml
│   │   └── LoginPage.qml
│   └── main.qml                  # Application entry point window
├── screenshot/                   # Visual documentation & previews
│   ├── home.png
│   ├── login.png
│   └── topalbuns.png
├── src/                          # Backend Logic (Rust)
│   ├── api/                      # ListenBrainz API integration wrappers
│   │   ├── albums.rs
│   │   ├── artists.rs
│   │   ├── listens.rs
│   │   ├── mod.rs
│   │   └── stats.rs
│   ├── cache/                    # Local storage and state management
│   │   ├── mod.rs
│   │   └── store.rs
│   ├── main.rs                   # Core initialization & QML bindings
│   └── resources.qrc             # Qt Resource compilation manifest
├── build.rs                      # Custom build script configurations
├── Cargo.toml                    # Rust dependencies and package metadata
└── README.md                     # Project documentation

---

🛠️ Prerequisites

Before compiling the project, ensure you have the following dependencies installed on your system:

• Rust: Install via rustup (stable toolchain recommended).
• Qt 5 / Qt 6: Required for the QML frontend rendering engine.
• KDE Kirigami: The UI framework component library.

Arch Linux

sudo pacman -S kirigami

Ubuntu / Debian

sudo apt install qml-module-org-kde-kirigami2

---

🚀 Getting Started

Clone the repository

git clone https://github.com/yourusername/flowbbler.git
cd flowbbler

Build the application

cargo build --release

Run the application

cargo run --release

---

🔑 Configuration & Token

To fetch your personal data, you will need a ListenBrainz user token:

1. Go to your ListenBrainz settings.
2. Copy your unique profile token.
3. Launch Flowbbler and paste your token into the Login screen.

---

🤝 Contributing

Contributions are welcome!

1. Fork the project
2. Create your feature branch

git checkout -b feature/AmazingFeature

3. Commit your changes

git commit -m "Add some AmazingFeature"

4. Push to the branch

git push origin feature/AmazingFeature

5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.