SubSonicSter

SubSonicSter is an Android application that enables playing the Hitster card game without Spotify by using a self-hosted SubSonic-compatible music server.

Purpose

This app allows you to play Hitster using your own music library hosted on a SubSonic-compatible server. Instead of requiring Spotify, you can use any SubSonic server (such as Navidrome, Gonic, Airsonic, or Nextcloud Music) to stream music directly from your personal collection.

Download

Pre-built APK files are available in the Releases section of this repository.

1. Go to the Releases tab on Codeberg
2. Download the latest release APK file
3. Install it on your Android device (see Installing the APK below)

Features

• QR code scanning for Hitster cards
• Integration with SubSonic API-compatible music servers
• CSV-based card set configuration
• Simplified CSV import: one button in Card Config downloads the official playlist index and imports every Hitster CSV from songseeker-hitster-playlists (no need to fetch files one by one)
• Real-time song playback with buffering
• Support for multiple CSV card files

For a complete list of changes and version history, see the CHANGELOG.md.

Screenshots

CSV Card Files

The app uses CSV files to map QR codes to songs. The recommended source is the community repository:

https://github.com/andygruber/songseeker-hitster-playlists/tree/main

Easiest import (recommended)

1. Open the app and go to Card Config.
2. Tap Add all CSV-Files from songseeker-hitster-playlists repository.

The app downloads the file playlists.csv from Andy Grubers songseeker-hitster-playlists Github Repository and then each listed CSV automatically. You need an internet connection for this step; afterwards, all card sets from that index are available in the app without manually copying URLs or files.

You can still paste a CSV URL to fetch a single file, or add a local CSV from storage if you prefer.

These CSV files contain the card-to-song mappings the app uses to decide which song to play when you scan a QR code.

SubSonic-Compatible Servers

This app works with any server that implements the SubSonic API. Here are some popular self-hosted options that you can easily set up on your own via Docker:

• Navidrome
• Gonic
• Airsonic / Airsonic-Advanced
• Nextcloud Music

Requirements

• Android 7.0 (API level 24) or higher
• Camera permission (for QR code scanning)
• SubSonic-compatible music server
• Internet connection

Setup

1. Install the app on your Android device
2. Configure your SubSonic server:
   • Open the app and navigate to "Config"
   • Enter your SubSonic server URL (e.g., https://music.example.com)
   • Enter your username and password
3. Import CSV card files:
   • Navigate to Card Config
   • Use Add all CSV-Files from songseeker-hitster-playlists repository for a one-step import of every playlist from the official index (see CSV Card Files), or download a single file by URL / add a local CSV if you like
4. Start scanning: Use the "Scan QR Code" option to begin playing

How It Works

1. Scan a QR code from a Hitster card
2. The app parses the URL to identify which CSV file to use and which song index to look up
3. The app searches your SubSonic server for the matching song (title and artist)
4. If found, the song starts playing automatically after buffering
5. Use the Play/Pause button to control playback

Development

This entire application was created through Vibecoding (AI-assisted development). The app is built using:

• Kotlin with Jetpack Compose for the UI
• AndroidX Media3 for audio playback
• CameraX and ZXing for QR code scanning (F-Droid compatible)
• Hilt for dependency injection
• Retrofit for SubSonic API communication
• Kotlin Coroutines for asynchronous operations

Code Quality Standards

⚠️ IMPORTANT: This project treats all compiler and lint warnings as errors.

The build will fail if any warnings are present. This ensures:

• High code quality and consistency
• Deprecated APIs are addressed immediately
• Potential issues are caught early in development
• No accumulation of technical debt

Configuration:

• Kotlin compiler: allWarningsAsErrors = true (see app/build.gradle.kts)
• Java compiler: -Werror flag enabled (see app/build.gradle.kts)
• Android Lint: warningsAsErrors = true (see app/build.gradle.kts and gradle.properties)

⚠️ DO NOT disable these settings. If you encounter a warning, fix it rather than disabling the check. See gradle.properties for detailed documentation.

Building

To build this app from source, you'll need:

• Android Studio (latest stable version recommended)
• JDK 17 or higher
• Android SDK with API level 24 or higher
• Gradle (included via wrapper)

Building the APK

1. Clone the repository:

   git clone <repository-url>
   cd SubSonicSter

2. Open the project in Android Studio, or build from the command line using Gradle:

3. Build a Debug APK:

   # On Windows
   gradlew.bat assembleDebug
   
   # On Linux/macOS
   ./gradlew assembleDebug

   The APK will be located at: app/build/outputs/apk/debug/app-debug.apk

4. Build a Release APK:

   # On Windows
   gradlew.bat assembleRelease
   
   # On Linux/macOS
   ./gradlew assembleRelease

   The APK will be located at: app/build/outputs/apk/release/app-release.apk

   Note: Building a release APK requires signing configuration. For testing purposes, you can use the debug build or configure signing in app/build.gradle.kts.

Installing the APK

After downloading or building the APK, you can install it on your Android device:

1. Enable installation from unknown sources:

   • Go to your device Settings → Security (or Apps → Special app access)
   • Enable "Install unknown apps" or "Install from unknown sources" for your browser or file manager

2. Transfer the APK to your device (if downloaded on PC):

   • Transfer via USB, email, cloud storage, or direct download from Codeberg

3. Install the APK:

   • Open the APK file on your device
   • Tap "Install" when prompted
   • Follow the on-screen instructions

Alternative: Install via ADB (if your device is connected via USB with USB debugging enabled):

adb install app-release.apk

Disclaimer and Liability

TRADEMARK DISCLAIMER: This app is in no way affiliated with, endorsed by, or associated with the Hitster card game or Jumbo Spiele GmbH. Hitster and Jumbo are trademarks of their respective owners. All product names, trademarks, and registered trademarks are property of their respective owners. This app is an independent, unofficial project and claims no trademark rights.

NO WARRANTY: This software is provided "as is", without warranty of any kind, express or implied, including but not limited to the warranties of merchantability, fitness for a particular purpose and noninfringement.

CSV PARSING RISKS: The app relies on CSV files for card-to-song mapping. These CSV files may contain malformed or unexpected data that could cause parsing errors or unexpected behavior. The developer assumes no responsibility for any issues, data loss, security vulnerabilities, or other problems that may arise from:

• Malformed CSV file contents
• Invalid or unexpected data formats in CSV files
• Security issues related to CSV parsing
• Any consequences resulting from the use of CSV files obtained from external sources

By using this application, you acknowledge that you use CSV files at your own risk and that the developer cannot be held liable for any damages or issues arising from their use.

NO LIABILITY: In no event shall the author or contributors be liable for any claim, damages or other liability, whether in an action of contract, tort or otherwise, arising from, out of or in connection with the software or the use or other dealings in the software.

License

This project is dual-licensed under the following licenses:

1. Beerware License (Revision 42) - See LICENSE.beerware
2. MIT License - See LICENSE.mit

You may choose to use this software under either license, whichever suits your needs best.

For F-Droid and other distributions that require OSI/FSF-approved licenses, please use the MIT License.

See the LICENSE file for complete details about both licenses.

Quick Summary

• Beerware: You can do whatever you want with this software. If we meet some day and you think this is worth it, you can buy me a beer in return.
• MIT: Permission is granted to use, modify, distribute, and sell copies of the software, provided the copyright notice and permission notice are included in all copies.

Development

Changelog Management

The project uses a single source of truth for changelogs: CHANGELOG.md. Fastlane changelog files are automatically generated from this file using a cross-platform Gradle task.

To regenerate Fastlane changelogs after updating CHANGELOG.md:

Using Gradle (cross-platform):

./gradlew generateFastlaneChangelogs

Or via Fastlane:

fastlane generate_changelogs

Important: Only edit CHANGELOG.md directly. Do not manually edit files in fastlane/metadata/android/en-US/changelogs/ as they will be overwritten when the task runs.

Fastlane Icon

The app icon for Fastlane metadata is automatically copied from Android resources during the build process. To regenerate it:

./gradlew copyFastlaneIcon

Or generate all Fastlane metadata at once:

./gradlew generateFastlaneMetadata

The generated icon file is automatically excluded from version control (see .gitignore).

Contributing

Contributions, bug reports, and feature requests are welcome. However, please note that this app was created through Vibecoding, and the development process may differ from traditional open-source projects.

Support

For issues, questions, or contributions, please use the Codeberg Issues section of this repository.

---

Enjoy playing Hitster with your own music library! 🎵🎮