NBS Studio Mobile

Android editor and player for Minecraft Note Block Studio (.nbs) songs.

This is a Cordova app: the source lives mostly in www/, and the Android project is generated under platforms/android.

Features

• Open and save .nbs files.
• Import MIDI files into an NBS song.
• Edit notes in a canvas piano-roll interface.
• Play songs with a Web Audio scheduler that is not tied to frame rate.
• Supports NBS tempo changer custom instruments.
• Supports custom instrument sample folders through Android's folder picker.
• Exports legacy Minecraft .schematic files using a NoteBlockStudio-style redstone/noteblock layout.
• Multilingual UI.

Android Permissions And Files

The app uses Android document pickers instead of broad storage permissions.

• Opening songs uses the system file picker.
• Saving .nbs uses the system create-document picker.
• Custom sounds use a folder picker so Android grants read permission.
• Schematic export asks for a destination folder, then writes the .schematic into that folder.

For custom sounds, choose either the Sounds folder itself or its parent. NBS custom instrument file paths are respected, including nested paths such as:

minecraft/block/sand1.ogg
Sounds/minecraft/block/sand1.ogg

If a custom sample cannot be found, the app reports the missing file/path in the status bar.

Build Requirements

• Node.js 20 or newer
• npm
• Android Studio with Android SDK installed
• Java from Android Studio's bundled JBR, or another compatible JDK

On macOS, Android Studio's bundled Java is usually here:

/Applications/Android Studio.app/Contents/jbr/Contents/Home

Build From The Command Line

Install dependencies:

npm install

Create or refresh the Android platform:

npm run prepare:android

Build a debug APK:

npx cordova build android --no-telemetry --debug

The debug APK is written to:

platforms/android/app/build/outputs/apk/debug/app-debug.apk

Open In Android Studio

Do not open the repository root as a native Android project. Generate the Cordova Android platform first:

npm install
npm run prepare:android

Then open:

platforms/android

Or let the helper open it:

npm run open:android

After changing www/, config.xml, hooks, or native plugin source, run a Cordova prepare/build again so the generated Android project is refreshed.

Project Layout

www/
  index.html              App shell
  css/style.css           UI styling
  js/app.js               App UI, editor wiring, file actions
  js/player.js            Web Audio playback engine
  js/nbs-parser.js        NBS reader
  js/nbs-serializer.js    NBS writer
  js/midi-parser.js       MIDI importer
  js/schematic-export.js  Legacy .schematic exporter
  js/lang.js              Translations
  sounds/                 Built-in note block samples
  samples/                Example songs

native/android/
  NBSFilePlugin.java      Cordova bridge for save, folder access, exports

hooks/
  after_prepare.js        Copies native plugin and patches Android project

scripts/
  ensure-android-platform.js
  open-android-project.js

Native Cordova Bridge

The custom NBSFile plugin provides:

• save - create a document and write bytes.
• chooseSoundsFolder - persist access to a custom sounds folder.
• getSoundsFolder - report the selected sounds folder.
• loadSound - load a custom sample by relative path.
• exportToFolder - choose a folder and write exported schematic data.

hooks/after_prepare.js copies the plugin into the generated Android project after Cordova prepares the platform.

Schematic Export

The exporter writes legacy Minecraft .schematic files. This format is for older Java Edition workflows, commonly Minecraft 1.12 and below or tools that still import classic schematics.

The export implementation follows NoteBlockStudio's classic schematic layout:

• Simple walkway
• Circular walkway
• Classic layout
• Layer compression
• Loop wiring
• Optional minecart track/chest
• Note block tile entities
• Gzipped NBT on Android

Troubleshooting

If Android Studio cannot open the project, make sure platforms/android exists:

npm run prepare:android

If changes to web files do not appear in the APK, rebuild with Cordova:

npx cordova build android --no-telemetry --debug

If custom sounds do not play, reselect the sounds folder from the app menu or preferences. The selected folder must contain the paths referenced by the NBS custom instrument file fields.

If Gradle cannot find dependencies in some regions, check hooks/after_prepare.js; it patches Cordova's generated Gradle repositories to use Aliyun mirrors.

License

Code is licensed under the license in LICENSE.

Minecraft and Note Block Studio assets may have their own license terms. Make sure redistributed sound assets are allowed for your use case.