Contribute to Interlude

How to build, test, and submit changes · Last updated 28 October 2026

Interlude is a fork of Metrolist and follows its contribution model: small, focused pull requests; a clear issue before large changes; and GPL-3.0 compatibility for everything you submit. This page covers the practical steps.

Before you write code

For anything larger than a typo fix, open an issue first. It saves you from spending a weekend on a feature that's already in progress or out of scope. The issue tracker and the roadmap are the source of truth for what's planned.

Building locally

You need a JDK (17 or newer) and the Android SDK. Android Studio installs and configures both for you; if you're building from a terminal, install them via Android command-line tools.

git clone https://github.com/naklirajveerfr/Interlude-Music.git
cd Interlude-Music
./gradlew assembleFossDebug

# first build downloads dependencies and takes several minutes
# APK output: app/build/outputs/apk/foss/debug/

adb install -r app/build/outputs/apk/foss/debug/*.apk

Build variants

fossDebug — the standard open-source debug build. This is what you'll use 95% of the time.
fossRelease — the release build. It requires signing config; see the keystore.properties example in the repository root.
gmsDebug / gmsRelease — builds that include Google Mobile Services (Cast). Not required for most work.

Signing key mismatch

A debug build and a release build have different signing keys. Installing a debug build over a release install (or vice versa) will fail with "App not installed". Uninstall the existing app first — this deletes its data, so back up first.

Coding conventions

Interlude follows standard Kotlin and Android conventions, with a few project-specific rules:

Kotlin only. No new Java files.
Jetpack Compose for all UI. No new XML layouts except where the framework requires them (e.g. widgets).
Material 3 Expressive for components. If you need a component that doesn't exist in Material 3 yet, prefer building it from primitives in the ui/components package rather than adding a dependency.
No new trackers, analytics, or crash-reporting SDKs. This is a hard rule — the app's privacy promise is a feature, not a nice-to-have.
Coroutines over RxJava. The project migrated away from RxJava and does not accept new RxJava code.
Ktlint runs as part of the build. Run ./gradlew ktlintFormat before committing.
Commit messages follow the format type(scope): summary — for example fix(player): stop audio on bluetooth disconnect.

Running tests

The test suite is split into unit tests (JVM, fast) and instrumented tests (on-device, slow):

# unit tests
./gradlew testFossDebugUnitTest

# instrumented tests (requires a connected device or emulator)
./gradlew connectedFossDebugAndroidTest

Not every change needs a new test, but changes to playback, the lyrics pipeline, and the download manager should include one. Bug fixes should ideally include a regression test that fails without the fix.

Translating

Interlude uses Android's standard string resources. Translations live in app/src/main/res/values-<locale>/strings.xml. To add a language:

Copy app/src/main/res/values/strings.xml to app/src/main/res/values-<locale>/strings.xml (e.g. values-fr for French).
Translate the string values, not the keys.
Do not translate strings that are proper nouns or API parameters; those are marked with a translatable="false" attribute.
Open a pull request with the new file. Partial translations are accepted as long as untranslated strings fall back gracefully to English.

Submitting a pull request

Fork the repository and create a branch from main with a descriptive name: fix/gapless-at-44khz, feat/phase-aligned-mix.
Make your changes in small, focused commits. Squash any "wip" commits before opening the PR.
Run ./gradlew ktlintFormat testFossDebugUnitTest and confirm it passes.
Open a PR against main. In the description, include a short summary, a link to the issue you're fixing (if any), and screenshots or a screen recording for UI changes.
A maintainer will review within a few days. Expect feedback on scope, testing, and conventions — this is normal and not a rejection.

What gets merged faster

Small PRs that fix one thing and include a test. Large PRs that touch many files at once, or that introduce new dependencies, take much longer to review and may be asked to split.

License

Interlude is licensed under GPL-3.0. By submitting a pull request you agree to license your contribution under the same terms. If your change includes code from another project, verify that project's license is GPL-3.0 compatible before including it — ask in the issue or PR if you're unsure.

Getting help

Open an issue for bug reports and feature requests.
GitHub Discussions for general questions and design discussion.
contact@interludemusic.online for anything that shouldn't be public.