NBS Player

NBS Player is an Android app for playing Note Block Studio (.nbs) songs. It is built with Kotlin, Jetpack Compose, Material 3, and a small native C++ audio engine backed by Oboe.

The app can open local .nbs files, import zipped song packages, keep a persistent playlist, use custom instrument sounds, and respond to Android media controls.

Features

• Play Note Block Studio .nbs files on Android.
• Open songs directly from Note Block World.
• Import ZIP song packages containing song.nbs and an optional sounds/ folder.
• Add songs to a persistent local playlist.
• Shuffle, delete, loop, seek, and auto-play the next song.
• Use custom .ogg or .wav instrument samples from a user-selected sounds folder.
• Handle Android media buttons and system playback controls.
• Open local files from Android's document picker or compatible share/open intents.
• Native low-latency playback through Oboe.

Requirements

• Android Studio
• JDK 11 or newer
• Android SDK 36
• Android NDK 27.0.12077973
• CMake 3.22.1
• Android device or emulator running Android 7.0/API 24 or newer

The Gradle wrapper uses Gradle 9.4.1, and the app currently targets Android SDK 36.

Build

Clone the project and build with the Gradle wrapper:

./gradlew assembleDebug

Install the debug build on a connected device:

./gradlew installDebug

Run unit tests:

./gradlew test

Run Android instrumentation tests:

./gradlew connectedAndroidTest

Release Build

Create a release APK:

./gradlew assembleRelease

Before publishing a release, configure signing for the release build type in app/build.gradle.kts or through Android Studio's signing configuration.

Supported Files

NBS Player supports:

• .nbs files from Note Block Studio.
• .zip packages with this structure:

song-package.zip
|-- song.nbs
`-- sounds/
    |-- harp.ogg
    |-- bass.ogg
    `-- minecraft/
        `-- dig/
            `-- sand1.ogg

ZIP packages must include song.nbs at the package root. The sounds/ directory is optional and can contain custom samples referenced by the song.

Custom Sounds

To use custom instrument samples:

1. Open the app.
2. Tap Add Sounds.
3. Select a folder that contains .ogg or .wav files.
4. Confirm the folder access prompt.

Files should match the instrument names or paths used by the NBS song. For example:

harp.ogg
flute.wav
minecraft/dig/sand1.ogg

The app stores persistent Android Storage Access Framework permission for the selected folder.

Project Layout

app/src/main/java/re/octofla/nbsplayer/
|-- audio/       Native audio bridge, sample loading, and synthesis
|-- media/       Android media session and media button handling
|-- model/       Song, note, instrument, and playlist models
|-- parser/      NBS binary parser
|-- playback/    Playback controller and scheduling
|-- playlist/    Playlist persistence
|-- ui/          Jetpack Compose UI
`-- zip/         ZIP song package extraction

app/src/main/cpp/
|-- audio_engine.cpp
|-- nbs_jni_bridge.cpp
`-- CMakeLists.txt

Publishing Checklist

• Update versionCode and versionName in app/build.gradle.kts.
• Configure release signing.
• Build and test a release artifact.
• Verify Android permissions and Play Store data safety answers.
• Add screenshots, app icon assets, and store listing copy.
• Review third-party asset and dependency license requirements before publishing publicly.

License

NBS Player is available under the MIT License. See LICENSE for details.