Developer Guide / 开发指南

This document describes the overview of this project for developers.

See also Build Instruction.

Last Update: 2026.05.28

Toolchain & Dependencies

This is a Kotlin Android Application.

Gradle Version Catalogs is used in this project:

Please refer libs.versions.toml for all the libraries and all gradle plugins.

Toolchain

• Gradlew 9.5.1, along with JDK 21
• Android Gradle Plugin 9.2.1
• Android SDK 37
• kotlin for JVM(Android) 2.3.20

Libraries

Highlight:

• Jetpack Compose
• Jetpack Datastore
• kotlinx.serialization
• kotlinx.parcelize
• koin as a lightweight Dependency Injection solution

See List of Libraries and Gradle Plugins in Use for details

Build Variants

Since 1.8¹, we have two Flavor Dimension currently: channel (for different release channels), target (for Android platforms).

Typically, there are two default BuildTypes (debug/release); all release shrinks and minifies.

However, since 2.0, due to replacement of signing key, BuildType named intermediateRelease has been added. intermediateRelease is used to be signed with rotated keys, signed with both old and new keys (in APK signature scheme v3 format for Android 9 and higher), to make users transit smoothly. It is just a temporary BuildType.

Dimension channel

Dimension channel2	Extra Package Name Suffix	Usage	Note
stable	(None)	Stable & LTS channel release
fdroid	(None)	Fdroid reproducible build release	based on stable
preview	.preview	Preview channel release
next	.eap	Early Access Preview channel release
checkout	.checkout	(Github Action Build )	for locating bug

Dimension target

We make this distinction mostly for bypassing Scope Storage for Android 10.

Dimension target	Target SDK	Min SDK	Descriptions
modern	(Latest)	26	for mainstream android device users
legacy	28	24	for legacy android device user (especially Android 10, to bypass Scope Storage)

Project Structure

Gradle Module

Currently:

• app(app/): source code of the Phonograph Plus
• changelog-generator(tools/changelog-generator): utility for generating formated changelogs and release notes

Repository Structure

Except files relative to gradle or building:

• .github/: Github Action and templates
• .idea/: Android Studio's config including code style config and run config
• app/, tools/changelog-generator: Gradle Module
• docs/: documents
• scripts/: utility scripts
• fastlane/metadata/android/: F-droid metadata, like summary, screenshot, changelogs
• crowdin.yml: Crowdin configuration
• ReleaseNote.yaml, ReleaseNoteStable.yaml: Pending release notes as well as metadata, used for generating changelogs and release note everywhere on releasing
• fdroid.properties: metadata of current latest version, unused
• version_catalog.json: containing the latest version metadata that Phonograph Plus used for checking updates

Source Code Structure of Phonograph Plus

For main source set (app/src/main):

main/
├── assets
├── java/
│   └── player.phonograph
│       ├── foundation (foundamental infrastructures, low-level utilities, compatibility)
│       ├── mechanism (core or business logics that contribute the main features)
│       ├── model (model and interface definations)
│       ├── repo (music library data source, internal databases)
│       ├── service (background music playback service)
│       ├── settings (preference storages)
│       ├── ui (user interface)
│       ├── App.kt
│       └── Constants.kt
├── res
└── AndroidManifest.xml

Footnotes

1. Before 1.8, there is only one flavor channel(or purpose), without target. ↩

2. Before v0.4.0, there are more variants (like common as stable, ci for Github Action). ↩