# Gramophone: an Android music player built on media3 and Material 3

> Gramophone is a Kotlin Android music player that reads your on-device library through MediaStore, renders Material 3 theming, and plays synced lyrics in LRC, TTML and SRT. It is small, GPL-3.0, and deliberately dependent on the codecs your phone already ships.

**FoedusProgramme/Gramophone** — A sane music player built with media3 and material design library that is following android's standard strictly.

- Repository: https://github.com/FoedusProgramme/Gramophone
- Stars: 2,313 · Forks: 131
- Language: Kotlin
- License: GPL-3.0
- Published: 2026-08-04 · Updated: 2026-08-18 · Language: en
- Canonical page: https://hysenlabs.com/projects/foedusprogramme-gramophone

## What Gramophone is, and the listener it is aimed at

Gramophone is an Android music player written in Kotlin, built on media3 and the Material Design library, and distributed under GPL-3.0. It is not a streaming client and it does not manage a cloud library. It reads the music already on the device through MediaStore, which is Android's system-wide media database, and presents it as a browsable library with search, list and grid views, folder and filesystem browsing, natural sorting, and playlists.

The audience is narrow and specific. If you keep local audio files on your phone, already have them indexed by the system scanner, and want a player that looks like the rest of Android 12 and later rather than like a skinned media centre, this is the target case. The README describes the app as "light, stable, and minimalistic", and the feature list backs that up: no equalizer of its own, no tag editor, no cloud sync. It supports system and third-party Equalizer apps instead of shipping one.

The library is the boundary. Anything MediaStore has not indexed is invisible to Gramophone, and the README's own troubleshooting points users back to the system media database when songs are missing. That is a design decision, not a bug, and it shapes everything else about the app.

## MediaStore, media3 and the codec decision that defines playback

Two mechanisms carry most of the app. The first is MediaStore: Gramophone queries the system media database rather than walking the filesystem itself, which is why it starts fast on large libraries and why the README tells users to reboot and wait a few minutes after changing settings, so the system rescans. The second is media3, which the repository includes as a git submodule rather than as a plain dependency, visible in the top-level .gitmodules entry and in the media3 directory.

The consequence of relying on system codecs is spelled out in the README's FAQ, and it is the most important thing to understand before installing. The app is smaller because it does not bundle decoders, and the price is format support that varies by Android version and by device. According to the README, int32 (32-bit) FLAC files only work on Android 14 or later; FLAC in general is officially supported from Android 8; xHE-AAC only from Android 9; and Dolby Digital, Dolby Digital Plus and AC-4 require a device with licensed decoders. There is one deliberate exception: ALAC plays without a system decoder because Gramophone includes a lightweight Java ALAC decoder.

A second layer handles lyrics. Gramophone reads LRC, TTML and SRT files and supports word or syllable level karaoke synchronisation. That is more than most Android players attempt, and it is the feature most likely to decide the choice between this app and a simpler one. ReplayGain 2.0 support is listed as full, which matters for anyone with a mixed-volume library.

## Installing Gramophone from F-Droid, IzzyOnDroid or GitHub releases

There is no build step needed for normal use. The README points to three sources for the latest stable version: GitHub releases, F-Droid, and IzzyOnDroid. The package name is org.akanework.gramophone on all of them, and beta builds and sneak peeks are published in the project's Telegram channel rather than in the stable channels.

If you install the APK directly rather than through a store, the README publishes certificate digests so you can confirm the file is the project's build and not a repackaged one. The GitHub, F-Droid and IzzyOnDroid certificate SHA-256 digest is listed as f451197ad7b80bd1bc981ba38a2c49d471856fb38bcc333676d6e8f8f3ce5d6e, and the Play Store digest is listed separately as 178869b0f9130d145b53404df4d4e5e311095406cb3c51a3e7a4b03bb3e87786. Checking the digest of a downloaded APK before installing it is the one verification step the project itself makes possible.

After first launch, two settings decide what you see. Gramophone hides songs shorter than 60 seconds by default, and the README says this is changed under Three dots > Settings > Behaviour, where setting the value to 0 shows everything. If a song is still missing after that, the README points at Behaviour > Folder blacklist, then at the system media database, which needs a reboot and a few minutes to rescan. For .opus files, the README notes they are only scanned from Android 10 onward, and suggests renaming the file to .ogg so it is detected on Android 6 and later.

## Building Gramophone from source, and why the submodule matters

Building is documented but assumes a real Android toolchain. The README requires the latest beta version of Android Studio and a fast network, which is a fair warning: media3 arrives as a submodule, so a shallow clone will not build.

The first step is fetching submodules. Without it the media3 sources are absent and the build fails before it starts.

```bash
git submodule update --init --recursive
```

The second step is the package type. Gramophone reads a release type string from an external file named package.properties in the repository root, and the README's example value is releaseType=SelfBuilt. This exists so a self-built APK is distinguishable from a store build.

```
releaseType=SelfBuilt
```

Save that as package.properties in the root folder, then open the project in Android Studio and import your own app signing signature. The README states you should be able to build at that point. Note what is not documented: there is no described command-line Gradle invocation, and no rollback or downgrade procedure for switching between build types. The gradlew wrapper exists in the repository, but the README does not walk through using it.

## Where Gramophone is the wrong player

The codec dependency is the clearest failure mode, and it is not a corner case. If your library is largely 32-bit FLAC and your phone runs Android 13 or older, the README says those files will not work, and the symptom described is a song that plays silently even though the volume is up. The same silent-playback symptom applies to Dolby formats on hardware without licensed decoders. Before blaming the app, check the Android version and the format.

Three other limits are worth stating plainly. Gramophone has no bundled equalizer, so if you need one you are relying on a system or third-party equalizer app that hooks into the audio session. It has no tag editing, so metadata fixes happen elsewhere. And because everything routes through MediaStore, a folder the system scanner ignores is a folder Gramophone cannot see; the README's advice to rename .opus to .ogg is a workaround for exactly this, and it is a workaround rather than a fix.

If your library is a mix of exotic formats and you want one player to handle all of them, a player that bundles its own decoders is the better fit, even though it will be a larger install. Gramophone's size is the point, and the format gaps are the price.

## How Gramophone differs from a decoder-bundling player

The useful comparison is not between Gramophone and another named Android player, but between two architectures. Gramophone delegates decoding to the platform and keeps the app small, which means its format support is a function of the phone it runs on. A player that bundles FFmpeg or a similar decoder set makes the opposite trade: a larger APK, but the same format support on every device, including old ones.

That difference decides real cases. On a modern phone with a licensed decoder set, the two approaches converge and Gramophone's smaller footprint wins. On an older device, or with 32-bit FLAC, xHE-AAC or Dolby content, the bundled-decoder player plays the file and Gramophone does not. The README is unusually honest about this, listing the version thresholds rather than claiming universal support.

The second architectural difference is the library source. Gramophone treats MediaStore as the source of truth; a filesystem-scanning player builds its own index. MediaStore gives faster startup and consistent metadata with the rest of Android, but it also means the app inherits the scanner's blind spots, including the extension handling the README describes.

## Maintenance, licensing and what a fork costs

The repository is not archived, and the last push was on 2026-08-20, which is the same date as the 1.1.2 release. Two earlier releases, 1.1.1 and 1.1.0, landed on 2026-07-23 and 2026-07-07. That is a steady release rhythm across the middle of 2026, and the default branch is beta, so the stable artefacts and the development branch are separated by design.

GPL-3.0 is the licence, and it has practical consequences for anyone planning to redistribute. A modified build distributed to others must be released under the same licence with source. The package.properties mechanism, with its releaseType=SelfBuilt value, exists partly so builds from different origins can be told apart. This is a description of the licence terms, not legal advice; read the LICENSE file in the repository for the actual text.

Upgrade cost is low for users, since the app ships through F-Droid, IzzyOnDroid, GitHub releases and the Play Store, and there is no server component or database migration to manage. For builders, the recurring cost is the submodule: media3 is pinned in the repository, so keeping your fork current means updating the submodule as well as the app code, and the README does not describe a rollback path if a newer media3 revision breaks playback.

## Conclusion

Adopt Gramophone if you want a small Android player that reads the system media database, themes itself with Material 3, and shows synced lyrics, and if your files are in formats your device already decodes. Do not adopt it if your library is mostly 32-bit FLAC on Android 13 or older, or Dolby formats on hardware without licensed decoders, because the README states those will not play. Before installing, verify the signing certificate SHA-256 digest against the one published in the README, and if you build from source, remember that the media3 directory is a git submodule that must be initialised first.

## FAQ

### How do I set up Gramophone on Android?

Download the latest stable version from GitHub releases, F-Droid or IzzyOnDroid, then check the APK against the certificate SHA-256 digest published in the README before installing. After first launch, open Three dots > Settings > Behaviour if songs seem to be missing.

### How do I use Gramophone to browse my music?

Gramophone reads your on-device library through MediaStore, so songs the system scanner has indexed appear automatically, with search, list and grid views, folder and filesystem browsing, natural sorting and playlists. If a song is missing, the README points to the minimum song length setting, the folder blacklist, and the need for the system media database to rescan.

### Why does a song in Gramophone play silently even though the volume is up?

The README attributes this to the app relying on system media codecs: int32 FLAC only works on Android 14 or later, xHE-AAC only from Android 9, and Dolby formats need a device with licensed decoders. ALAC is the exception, because Gramophone includes a lightweight Java ALAC decoder.

### Does Gramophone show synced lyrics?

Yes. The README lists synced lyrics in LRC, TTML and SRT, including word or syllable level karaoke synchronisation.

### How do I build Gramophone from source?

Run git submodule update --init --recursive first, because media3 is included as a git submodule, then create package.properties in the repository root containing releaseType=SelfBuilt. Open the project in the latest beta version of Android Studio and import your own app signing signature.

## Sources

- [Official README](https://github.com/FoedusProgramme/Gramophone#readme)
- [Project repository](https://github.com/FoedusProgramme/Gramophone)
- [Release notes](https://github.com/FoedusProgramme/Gramophone/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/foedusprogramme-gramophone