pynbs 0.3.0

A simple python library to read and write .nbs files from Note Block Studio

pynbs

A simple python library to read and write .nbs files from Open Note Block Studio. Compatible with python 2 and 3.

pynbs makes it possible to easily iterate over Note Block Studio songs.

import pynbs

for tick, chord in pynbs.read('demo_song.nbs'):
    print(tick, [note.key for note in chord])

You can also use pynbs to generate new songs programmatically.

import pynbs

new_file = pynbs.new_file(song_name='Hello world')
new_file.notes.extend([
    pynbs.Note(tick=i, layer=0, instrument=0, key=i + 35) for i in range(10)
])

new_file.save('new_file.nbs')

Installation

The package can be installed with pip.

$ pip install pynbs

The latest release follows the latest version of the nbs file format specification (version 3).

Basic usage

Reading files

You can use the read() function to read and parse a specific nbs file.

demo_song = pynbs.read('demo_song.nbs')

The read() function returns a pynbs file object. These objects have several attributes that mirror the binary structure of nbs files.

Header

The first attribute is header, the file header. It contains information about the file.

header = demo_song.header

Attribute	Type	Details
header.version	int	The NBS format version.
header.default_instruments	int	The amount of instruments from vanilla Minecraft in the song.
header.song_length	int	The length of the song, measured in ticks.
header.song_layers	int	The id of the last layer with at least one note block in it.
header.song_name	str	The name of the song.
header.song_author	str	The author of the song.
header.original_author	str	The original song author of the song.
header.description	str	The description of the song.
header.tempo	float	The tempo of the song.
header.auto_save	bool	Whether auto-saving has been enabled.
header.auto_save_duration	int	The amount of minutes between each auto-save.
header.time_signature	int	The time signature of the song.
header.minutes_spent	int	The amount of minutes spent on the project.
header.left_clicks	int	The amount of times the user have left clicked.
header.right_clicks	int	The amount of times the user have right clicked.
header.blocks_added	int	The amount of times the user have added a block.
header.blocks_removed	int	The amount of times the user have removed a block.
header.song_origin	str	The file name of the original midi or schematic.

For more information about all these fields, check out the official specification.

Notes

The notes attribute holds a list of all the notes of the song in order.

first_note = demo_song.notes[0]

Attribute	Type	Details
note.tick	int	The tick at which the note plays.
note.layer	int	The id of the layer in which the note is placed.
note.instrument	int	The id of the instrument.
note.key	int	The key of the note. (between 0 and 87)

Layers

The layers attribute holds a list of all the layers of the song in order.

first_layer = demo_song.layers[0]

Attribute	Type	Details
layer.id	int	The id of the layer.
layer.name	str	The name of the layer.
layer.volume	int	The volume of the layer.
layer.panning	int	The stereo panning of the layer.

Instruments

The instruments attribute holds a list of all the custom instruments of the song in order.

first_custom_instrument = demo_song.instruments[0]

Attribute	Type	Details
instrument.id	int	The id of the instrument.
instrument.name	str	The name of the instrument.
instrument.file	str	The name of the sound file of the instrument.
instrument.pitch	int	The pitch of the instrument. (between 0 and 87)
instrument.press_key	bool	Whether the piano should automatically press keys with the instrument when the marker passes them.

Iterating over songs

Iterating over a pynbs file object yields consecutively all the chords of the song with the associated tick.

for tick, chord in demo_song:
    ...

chord is a list of all the notes that play during the tick tick.

Creating new files

You can create new files using the new_file() function. The function lets you specify header attributes with keyword arguments.

new_file = pynbs.new_file(song_name='Hello world')

The function returns a new pynbs file object that you can now edit programmatically.

Saving files

You can use the save() method to encode and write the file to a specified location.

new_file.save('new_file.nbs')

Upgrading old files

While pynbs is up-to-date with the specification of the open source continuation of Minecraft Note Block studio, the original file format is still supported by the read() function, making it possible to bulk upgrade songs to the new format.

import glob
import pynbs

for old_file in glob.glob('*.nbs'):
    pynbs.read(old_file).save(old_file)

---

License - MIT