nbswave

A Python package to render note block songs to a variety of audio formats.

Overview

nbswave is a Python package aimed at rendering note block songs from Open Note Block Studio to audio tracks. Supports many common audio formats, both for loading custom sounds as well as exporting tracks.

Setup

The package can be installed with pip.

$ pip install nbswave

In order to use the package, FFmpeg must be available:

1. Download precompiled binaries for ffmpeg and ffprobe here.
2. Add the destination folder to your PATH, or, alternatively, place both executables in the root folder of the project.

Usage

from nbswave import *

render_audio("song.nbs", "output.mp3")

The output format will be detected automatically based on the file extension. You can still specify it explicitly if you'd like:

from nbswave import *

render_audio("song.nbs", "output", format='wav')

[!NOTE] Compatibility with audio formats depends on your FFmpeg configuration.

Custom instruments

In order to render songs with custom instruments, you have a few options:

1. Copy the sounds manually to the sounds folder

2. Pass the path to a folder (or ZIP file) containing custom sounds:

from pathlib import Path

nbs_sounds_folder = Path.home() / "Minecraft Note Block Studio" / "Data" / "Sounds"
render_audio("song.nbs", "output.mp3", custom_sound_path=nbs_sounds_folder)

If any sound file used in the song is not found in that location, a MissingInstrumentException will be raised. This behavior can be suppressed with the following argument:

render_audio("song.nbs", "output.mp3", ignore_missing_instruments=True)

Advanced usage

For more advanced use cases where you might need more control over the export process, it's possible to use the SongRenderer class. This will allow you to load custom instruments from multiple sources, as well as query which instruments are still missing:

from nbswave import *

renderer = SongRenderer("song.nbs")

renderer.load_instruments(nbs_sounds_folder)
renderer.load_instruments("some_more_instruments.zip")

renderer.missing_instruments()

track = renderer.mix_song()

track.save("song.mp3")

[!TIP] For additional parameters, check out the source code!

Contributing

Contributions are welcome! Make sure to open an issue discussing the problem or feature suggestion before creating a pull request.

This project uses poetry for managing dependencies. Make sure to install it, and run:

$ poetry install

This project follows the black code style. Import statements are sorted with isort.

$ poetry run isort nbswave
$ poetry run black nbswave
$ poetry run black --check nbswave

---

License - MIT