v0.6.0-alpha

cumu v0.6.0-alpha — Album Covers, Smarter Discover & a Faster App

⚠️ This is an alpha release. cumu is still under active development. Expect bugs, back up your data folder before updating, and please report problems in the issues.

---

🖼️ Automatic Album Covers

• Albums without a cover now get one automatically. cumu first uses the artwork embedded in your audio files, then looks the album up in the Cover Art Archive (MusicBrainz).
• Covers are downloaded once and served by cumu itself. Your devices never contact an outside service, and covers keep working offline. Existing covers are never replaced.
• Own cover folder. Covers are stored in their own folder (admin setting, default data/covers) instead of your music folder. Older covers in the music folder still work and are moved over when you set the folder.
• Part of the library scan. A scan now adds missing covers after the metadata lookup. It continues after a restart and pauses for 30 minutes after repeated network errors. The first scan of a new installation no longer blocks the app while covers are added.
• Admin controls:
  • Server Config: cover folder, automatic covers and online search on/off.
  • Scan Library: cover status, "load missing covers" and "retry".
  • Albums: "find cover" and "remove cover" per album.
• Existing installations: covers stay off until an admin picks the cover folder in a one-time notice, which can start the cover scan right away. New installations get covers from the start.
• Upload fix: embedded artwork is saved once per album instead of once per song.

🔎 Smarter, Typo-Tolerant Search

• Typos no longer matter. "the weekend" finds The Weeknd, "metalica" finds Metallica, "blindng lights" finds Blinding Lights. Accents, punctuation and a missing "The" are ignored too ("beyonce" → Beyoncé, "acdc" → AC/DC).
• Ranked results with a top result. Exact matches beat prefixes, prefixes beat partial and fuzzy matches. The best match is shown big at the top; for an artist, their most popular songs appear right next to it.
• No more song floods. Searching for an artist shows the artist first, not 20 of their songs. The song list stays short with a Show all button.
• Search across several fields works too, e.g. "blinding lights weeknd" or "rammstein sonne".

🎧 Discover Improvements

• New Most Played Albums section: the albums you listened to most in the last 3 months. With too little listening history yet, it shows Recently Added Albums instead.
• Every genre has its own colour. Each of the 100 genres has a distinct colour, and custom genres get a stable colour derived from their name.
• Podcasts in the search fixed. They now show as normal-sized cards side by side.
• Long names stay inside their tiles. Titles, artist and album names end with "…"; on phones they get up to two lines first.

❤️ Favourites Everywhere

• Favourites are now stored on the server and shared between the web app and the Android app. Existing favourites in the web app are uploaded once automatically.
• Changes in one app show up in the other right away.

📱 Android App

• Much faster home and library. Both show the last state immediately and update quietly in the background. The start page now needs one small request instead of five full-library downloads.
• Library: albums of the last 3 months, all playlists (pinned ones first) and a new Lieblingssongs entry and screen.
• Heart button in the player and "Zu Lieblingssongs" in the song menu.
• Home: "Deine Top-Alben" once there is enough listening history.
• Still works with older servers (up to v0.5.x) using the previous requests.

⚡ Server Performance

• New database indexes for songs, play history and playlists: album/artist counts and history lookups no longer scan whole tables.
• /api/home delivers the whole start page in one answer, new /api/library/overview, favourites API (GET/PUT/DELETE /api/favorites), and a faster /api/artists.
• The service worker no longer caches admin API answers.

⬆️ Updating

• Docker / NAS: Watchtower updates automatically, or use "Update installieren" in the admin panel.
• Linux / LXC / .deb: sudo cumu-update
• Android: install the new cumu_0.6.0-alpha.apk from this release for the faster library and favourites.

After updating, reload the web app once (the offline cache is refreshed automatically). On existing installations, open the admin panel and choose a cover folder to turn on automatic covers.

What's Changed

• feat(covers): automatic album covers from embedded artwork and MusicBrainz by @Wolfiku in #7
• App: much faster home & library, albums of the last 3 months, shared favourites by @Wolfiku in #8

Full Changelog: v0.5.0-alpha...v0.6.0-alpha

v0.5.0-alpha

cumu v0.5.0-alpha — Native Android App & Login Protection

📱 New: Native Android App

A real Android app (Kotlin, Jetpack Compose, Media3) instead of the old web view. Download cumu_0.5.0-alpha.apk below and install it on your phone (allow "install unknown apps" for your browser or file manager once).

• Real streaming. Songs start instantly and can be seeked (HTTP Range). FLAC and ALAC play natively.
• Background playback. Music keeps playing with the screen off, with controls in the notification, on the lock screen, and via Bluetooth/headset buttons. Unplugging headphones pauses.
• Works offline. The app keeps the library from your last visit: home, library, playlists, albums, artists and search all work without a connection. Downloaded songs play offline; others are dimmed. A bar at the bottom shows when you are offline.
• Downloads. Save songs, albums or playlists to the phone. The library shows next to every playlist and album whether it is downloaded.
• Home screen with quick picks, recommended new songs, "Neu für dich" album, mixes (random, top hits, per genre), new albums and your artists.
• Search with search history, top result and filters (songs, albums, artists, playlists).
• Artist pages with picture, popular songs, albums and all songs.
• Playlists: create, add songs (new picker sheet), remove songs, delete.
• Login with server address, user name and password. Admins enter the admin code once; the phone remembers it for 30 days. Only tokens are stored, never the password.
• Black-and-white design with the cumu cow as app icon, plus animations throughout.

Works with every server from v0.4.3 on, no server changes needed. Requires Android 8.0 or newer.

🔐 Brute-Force Protection for Logins

• Failed logins are limited. After 5 failed attempts for an account from the same IP, that account is locked for this IP for 1 minute, doubling with every further failure (max. 15 minutes). After 20 failures from one IP within 15 minutes the whole IP is blocked.
• Covers the web login, the app login, the admin code in the first-time setup and "change password". Wrong admin codes count as failures.
• Locked requests get 429 Too Many Requests with the waiting time, which the login forms show. Locks appear in Admin → Logs.
• Response times no longer reveal whether a user name exists.
• Behind a reverse proxy (nginx, Caddy, Traefik, Nginx Proxy Manager …) set the new TRUST_PROXY setting (e.g. TRUST_PROXY=1), so the limit counts the real client IP instead of the proxy's.

⬆️ Updating

• Docker / NAS: Watchtower updates automatically, or use "Update installieren" in the admin panel.
• Linux / LXC / .deb: sudo cumu-update
• Android: install the new APK over the old one.

Full Changelog: v0.4.6-alpha...v0.5.0-alpha

v0.4.6-alpha

cumu v0.4.6-alpha — Update or Reinstall, Remembered Admin Code

🔁 Installer: Update or Fresh Install

When cumu is already installed (Docker container or Linux service), the installer now asks what to do:

1) Aktualisieren        — Benutzer, Einstellungen, Bibliothek und Admin-Code bleiben
2) Komplett neu installieren — Datenbank, Benutzer und Einstellungen werden gelöscht
                               (deine Musikdateien bleiben erhalten)
3) Abbrechen

• Update reuses the data folder, music folder and port of the existing installation and asks no further questions.
• Fresh install must be confirmed by typing ja, and a new admin code is created. Music files are never deleted.
• Without a terminal it updates. To skip the question, use --update or --reinstall.
• The terminal check now also works reliably with curl … | bash.

🔐 Admin Code Only Every 30 Days

• After you enter the admin code once on a device (also in the first-time setup), that device remembers it for 30 days. Until then, username and password are enough.
• After 30 days, or on a new device or browser, the code is asked for again.
• Changing ADMIN_LOGIN_CODE ends the 30 days on all devices immediately.
• The mobile app already stores the code itself; nothing changes there.

🧹 Shorter Folder Info in Setup

• The first-time setup no longer lists every folder that is shared with the Docker container. On Synology every shared folder is a separate mount, so the list could be 20 lines long.
• Where shared folders are still mentioned, only the top-level ones are shown, at most three (e.g. /volume1).

⬆️ Updating

Run the installer and choose 1) Aktualisieren:

curl -fsSL https://raw.githubusercontent.com/Wolfiku/cumu/main/scripts/install.sh | bash

Admins enter the admin code once after the update; after that, the 30 days apply.

Full Changelog: v0.4.5-alpha...v0.4.6-alpha

v0.4.5-alpha

cumu v0.4.5-alpha — Any Music Path & Live Scan Progress

📁 Any Music Path Works

• No more /app/…. A path entered without a leading slash (e.g. volume1/music) used to be read from the program folder, which is /app in Docker. It is now read from the root: /volume1/music.
• NAS paths work in Docker. The installer now shares your NAS drives with the container under the same path (Synology/Asustor /volume1…, QNAP /share, Unraid/TrueNAS /mnt). So you can enter the real NAS path, such as /volume1/music, directly in cumu. docker-compose.nas.yml does the same.
• The folder you choose is the folder that gets scanned. Before, the library scan always read MUSIC_PATH from the .env or container, whatever was entered in the settings. Once you save a folder in the setup wizard or in the settings, cumu uses it for scanning, uploads and streaming. Existing installations keep their current behaviour until the folder is saved once.
• The setup wizard pre-fills the music folder chosen in the installer.

✅ Live Path Check

In the setup wizard and in Admin → Server Config, the music folder is checked right after you type it. Nothing is changed by the check.

• Green check: the folder exists and contains audio files (with count).
• Amber "!": it can be saved, but something looks off (empty, does not exist yet, read-only).
• Red "!": it cannot be saved (a file instead of a folder, no read permission, or not shared with the Docker container).
• Hover over or focus the icon for an explanation and the exact path that was checked. A short note below the field shows it on touch devices too.
• Fixed: saving an invalid path showed "Configuration saved!" anyway.

📊 Scan Shows What It Is Doing

• New first step "Ordner durchsuchen". It shows live how many audio files were found and which folder is being searched, with a moving progress bar.
• The server stays responsive while it searches. On large NAS libraries, searching used to block the server, and nothing was shown for minutes.
• Clear steps: "Schritt 1/3 · Ordner durchsuchen", "Schritt 2/3 · Dateien einlesen" (with the current file), "Schritt 3/3 · Lieder erkennen" (with the current song).
• The scan summary now names the folder and the number of files found. If nothing was found, it suggests checking the music folder.

⬆️ Updating

• NAS installed with v0.4.4-alpha: run the installer again (your data and admin code are kept), then open Admin → Server Config and save the music folder once, e.g. /volume1/music.

curl -fsSL https://raw.githubusercontent.com/Wolfiku/cumu/main/scripts/install.sh | bash

• Other Docker installs: Watchtower updates automatically, or use "Update installieren" in the admin panel.
• Linux / LXC / .deb: sudo cumu-update

Full Changelog: v0.4.4-alpha...v0.4.5-alpha

v0.4.4-alpha

🗄️ NAS Support (Synology, QNAP, Unraid, TrueNAS SCALE, Asustor)

• The one-line installer now works on NAS systems. It detects the NAS and installs cumu plus Watchtower as Docker containers, instead of failing with "Cannot detect OS".
• Sensible defaults per NAS. The installer suggests suitable folders for data and music (e.g. Synology /volume1/docker/cumu and /volume1/music, Unraid /mnt/user/appdata/cumu). Press Enter to accept or type your own.
• No compose plugin needed. Containers are started with plain docker run, so it also works where Docker Compose is missing (e.g. Unraid).
• Admin code shown at the end. It is stored in <data folder>/cumu.env and kept on re-install.
• Other systems: NAS devices without a supported package manager but with Docker (e.g. TerraMaster, UGREEN) are installed as containers automatically. On any Linux you can force this with --docker; folders can be set with --data-dir and --music-path.
• New docker-compose.nas.yml for NAS container UIs (Container Manager, Container Station, Portainer, TrueNAS Apps), with the matching paths for each NAS in its header.

Install on a NAS

1. Install and start your NAS's Docker package (Synology: Container Manager, QNAP: Container Station, Unraid: enable Docker, TrueNAS SCALE: set up Apps, Asustor: Docker-CE).
2. Enable SSH, log in and become root: sudo -i
3. Run:

curl -fsSL https://raw.githubusercontent.com/Wolfiku/cumu/main/scripts/install.sh | bash

Not supported: TrueNAS CORE (FreeBSD) and 32-bit ARM NAS models (the image is built for x86_64 and arm64).

🛠️ Installer Fixes

• Clearer root check. It now uses id -u and says which user the script is actually running as. It also explains the common mistake sudo curl … | bash (only curl runs as root, not bash).
• Better OS detection. Derivatives such as Raspberry Pi OS, KDE neon, EndeavourOS or Amazon Linux are recognised via ID_LIKE, with fallbacks to /usr/lib/os-release, release files and the installed package manager.
• Installer no longer stops before the summary on systems without hostname -I. Before, it could exit silently before showing the URL and admin code.
• The cumu logo in the installer is now white.

⬆️ Updating

• Docker / NAS: Watchtower updates automatically, or use "Update installieren" in the admin panel.
• Linux / LXC / .deb: sudo cumu-update

Full Changelog: v0.4.3...v0.4.4-alpha

v0.4.3-alpha

cumu v0.4.3 — Admin Login Code & Instant Updates

This is a security release. Admin accounts are now protected by a second factor, and urgent updates can be installed right away, even while a library scan is running.

---

🔐 Admin Login Code (important — please read)

• Every admin login needs a code. Admins (and creators) must enter ADMIN_LOGIN_CODE from the server's .env in addition to their password: in the web app, the mobile app and during first-time setup. Normal users are not affected.
• Generated automatically. If the code is missing, the server creates one on startup and writes it to the .env:
  • Linux / LXC / .deb: /opt/cumu/.env (or your install directory)
  • Docker: data/.env inside the data volume, so it survives Watchtower updates. You can also set ADMIN_LOGIN_CODE yourself in the .env next to your docker-compose.yml.
  • The server log says where the code was saved.
• All admins are logged out once after this update and have to log in again with the code. Admin logins also end whenever the code is changed.
• AUTO_LOGIN was removed. It logged in an admin without any password. If it is still set, it is ignored and a warning is logged.

Where do I find my code?

# Docker
docker exec cumu cat /app/data/.env
# Linux / LXC / .deb
sudo grep ADMIN_LOGIN_CODE /opt/cumu/.env

⚡ Instant Updates

• Update during a library scan: while a scan runs (including the full-screen first scan), admins on desktop get an "Update installieren" button in the bottom right corner. The page reloads when cumu is back, and the scan continues where it stopped.
• Docker updates now really start immediately. "Update now" in the admin panel used to only say that Watchtower updates on its own (every 5 minutes). cumu now tells Watchtower to update right away through its HTTP API.
  • Existing Docker installations: add the new WATCHTOWER_* lines from docker-compose.yml once, then run docker compose up -d. Without them, automatic updates keep working as before.
• Linux / LXC: the update button now reports when cumu-update fails (it needs root; run sudo cumu-update) or when cumu is already up to date, instead of always saying "Update started".

🧹 Fixes

• The admin panel shows the real version instead of v0.2.0.

---

Installation Options

Option 1: One-Line Installer (Recommended for Linux / LXC)

curl -fsSL https://raw.githubusercontent.com/Wolfiku/cumu/main/scripts/install.sh | bash

The installer prints the admin login code at the end.

Option 2: Docker Compose

git clone https://github.com/Wolfiku/cumu.git
cd cumu
docker compose up -d

Option 3: Debian / Ubuntu Package (.deb)

dpkg -i cumu_0.4.3_all.deb

---

Full Documentation

See INSTALL.md for full deployment instructions.

What's Changed

• Add mobile shell with bottom tab bar, mini player, and touch UI by @Wolfiku in #3
• Show library scan progress and make metadata lookup safe by @Wolfiku in #4
• Require admin login code from .env for every admin login by @Wolfiku in #5
• release: v0.4.3 — instant updates during library scan by @Wolfiku in #6

Full Changelog: 0.3.1...v0.4.3

v0.4.0-alpha

cumu v0.4.0-alpha — Mobile Overhaul & Reliable Song Recognition

The biggest changes in this release are a reworked mobile experience and a rebuilt song recognition. This is an alpha: please report anything that looks off.

---

📱 Mobile Improvements

• New phone layout with a three-tab bottom bar (home / library / profile) and a mini player.
• Full-screen now playing view without app chrome.
• Bottom sheets for context menus and the queue.
• Touch gestures: drag to reorder the queue, long press opens the song menu.
• Back button / back gesture moves through the app instead of leaving it.
• Profile tab bundles settings, playlists, the admin dashboard and logout.
• Phone-sized spacing, safe-area insets on notched devices, toasts above the bars.

🎵 Song Recognition

• Every scanned song is looked up. Library scans now run the metadata lookup (MusicBrainz → Mistral AI, if configured) for each new song.
• No more wrong matches. The old lookup took the first search result and overwrote your tags with it; in tests most well-known songs ended up as a cover, karaoke or parody version. A match is now only used when title, artist and length agree and it is the same version (live, remix, cover, … are told apart). Uncertain songs are left as they are instead of being guessed.
• Your tags win. Album, year and track number from your files are never replaced, only filled in when missing. The lookup no longer sets a year at all, since a text search can't tell the original release from a remaster.
• Untagged files named Artist - Title are recognized from the file name.
• Robust against outages: MusicBrainz requests are rate-limited and retried; songs that could not be looked up are retried on the next scan instead of counting as "not found".

🔍 Library Scan

• Scan progress with time remaining in the sidebar (desktop) and a strip below the top bar (mobile), plus live progress in Admin → Scan Library.
• First setup: a fresh installation with music in its folder shows that a scan is needed. An admin starts it, and cumu opens once the library is ready.
• Runs on the server: closing the browser does not stop a scan, and an interrupted scan continues after a restart. New files are picked up automatically in the background.

🧹 Library Cleanup & Fixes

• Albums of different artists that share a title (e.g. "Greatest Hits") are no longer merged; already merged albums are split once on startup.
• Duplicate songs and albums are prevented and cleaned up automatically. The database is backed up before the first cleanup, and no files are deleted.
• The site-wide drag & drop upload overlay was removed (the upload area in the admin panel still accepts dropped files).
• The auto lookup toggle in the settings now shows its real state.

---

Installation Options

Option 1: One-Line Installer (Recommended for Linux / LXC)

curl -fsSL https://raw.githubusercontent.com/Wolfiku/cumu/main/scripts/install.sh | bash

Option 2: Docker Compose

git clone https://github.com/Wolfiku/cumu.git
cd cumu
docker compose up -d

Option 3: Debian / Ubuntu Package (.deb)

dpkg -i cumu_0.4.0-alpha_all.deb

---

Full Documentation

See INSTALL.md for full deployment instructions.

What's Changed

• Add mobile shell with bottom tab bar, mini player, and touch UI by @Wolfiku in #3
• Show library scan progress and make metadata lookup safe by @Wolfiku in #4

Full Changelog: v0.3.0...v0.4.0-alpha

v0.3.1-alpha

🚀 Installation Methods

⚡ Option 1: One-Line Installer (Recommended for Linux / Bare Metal / LXC)

curl -fsSL https://raw.githubusercontent.com/Wolfiku/cumu/main/scripts/install.sh | bash

(Note: If logged in as root, do not add sudo.)

---

🐳 Option 2: Docker Container (Docker Compose)

docker pull ghcr.io/Wolfiku/cumu:latest
docker compose up -d

---

📦 Option 3: Debian / Ubuntu (.deb Package)

dpkg -i cumu_*.deb

---

💾 Option 4: Offline Docker Image Tarball (cumu_docker_image.tar.gz)

1. Download cumu_docker_image.tar.gz from Assets below.
2. Import and run:

   docker load -i cumu_docker_image.tar.gz
   docker run -d -p 3000:3000 --name cumu -v cumu_data:/app/data cumu:latest

Full Changelog: v0.3.0...v0.3.1

v0.3.0-alpha

🚀 Installation Methods

⚡ Option 1: One-Line Installer (Recommended for Linux / Bare Metal / LXC)

curl -fsSL https://raw.githubusercontent.com/Wolfiku/cumu/main/scripts/install.sh | bash

(Note: If logged in as root, do not add sudo.)

---

🐳 Option 2: Docker Container (Docker Compose)

docker pull ghcr.io/Wolfiku/cumu:latest
docker compose up -d

---

📦 Option 3: Debian / Ubuntu (.deb Package)

dpkg -i cumu_*.deb

---

💾 Option 4: Offline Docker Image Tarball (cumu_docker_image.tar.gz)

1. Download cumu_docker_image.tar.gz from Assets below.
2. Import and run:

   docker load -i cumu_docker_image.tar.gz
   docker run -d -p 3000:3000 --name cumu -v cumu_data:/app/data cumu:latest

Full Changelog: v0.2.0...v0.3.0

v0.2.0-alpha

Highlights & New Features

• Prioritized One-Line Installer:
  Streamlined bare-metal installation script for Debian, Ubuntu, Proxmox LXC, Fedora, and Arch. Automatically configures Node.js 20+, systemd background service, and daily background updates.

  curl -fsSL https://raw.githubusercontent.com/Wolfiku/cumu/main/scripts/install.sh | bash

• Daily Automated Background Updates:

  • Bare Metal / LXC: Automated daily cronjob (/etc/cron.daily/cumu-update). Includes cumu-update CLI tool.
  • Docker: Integrated Watchtower background container auto-pulls new container images without downtime.

• Admin Dashboard Update Button:
  Added a new System Update & Version section in Admin Settings & Stats with the button "Jetzt auf Updates prüfen & aktualisieren".

• Automated Path & Permission Validation:
  Server automatically validates read/write permissions on the configured music storage directory prior to saving.

• Interactive Port & Setup Wizard:
  Custom server port support during terminal installation and in the redesigned web setup wizard.

---

Installation Options

Option 1: One-Line Installer (Recommended for Linux / LXC)

curl -fsSL https://raw.githubusercontent.com/Wolfiku/cumu/main/scripts/install.sh | bash

Option 2: Docker Compose

git clone https://github.com/Wolfiku/cumu.git
cd cumu
docker compose up -d

Option 3: Debian / Ubuntu Package (.deb)

dpkg -i cumu_0.2.0_amd64.deb

---

Full Documentation

See INSTALL.md for full deployment instructions.