Skip to content
/ rsnbs Public

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

License

Notifications You must be signed in to change notification settings

omninbs/rsnbs

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

30 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

rsnbs

GitHub Actions crates.io Rust Version Code style: rustfmt

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

rsnbs has all the functionality pynbs has, like iterating over Note Block Studio songs

use rsnbs::read_nbs;

let song = read_nbs("song.nbs");
for note in song.notes {
  println!("tick: {}, instrument: {}", note.tick.unwrap(), note.instrument.unwrap())
}

or generating new songs programmatically

use rsnbs::{Song, Note};

let song = Song::default();
for i in 0..10 {
  Song.notes.push(Note {
    tick: Some(i), layer: None, instrument: None,
    velocity: 30, panning: None, pitch: None, key: Some(i+35)
  })
}

the main difference is that every field is an option (for version differences sake) where None acts as 0/"".

Installation

The package can be installed with cargo

$ cargo install rsnbs

Reading / Writing

You can use the read_nbs function to read an parse a specific NBS file of any version.

  let song = rsnbs::read_nbs("song.nbs");

This returns a rsnbs::Song object wich can then be written using Song::save

  song.save("song.nbs", version);

Song struct

Song implements the Default trait so you can instance a default with 1 layer and all None fields

  let song = Song::default();

Fields

Header

the first field is header, the file header, of type struct Header

Attribute Type Details
header.version i8 The NBS version this file was saved on.
header.default_instruments i8 The amount of instruments from vanilla Minecraft in the song.
header.song_length i16 The length of the song, measured in ticks.
header.song_layers i16 The ID of the last layer with at least one note block in it.
header.song_name String The name of the song.
header.song_author String The author of the song.
header.original_author String The original song author of the song.
header.description String The description of the song.
header.tempo i16 The tempo of the song multiplied by 100.
header.auto_save bool Whether auto-saving has been enabled.
header.auto_save_duration i8 The amount of minutes between each auto-save.
header.time_signature i8 The time signature of the song.
header.minutes_spent i32 The amount of minutes spent on the project.
header.left_clicks i32 The amount of times the user has left-clicked.
header.right_clicks i32 The amount of times the user has right-clicked.
header.blocks_added i32 The amount of times the user has added a block.
header.blocks_removed i32 The amount of times the user has removed a block.
header.song_origin String The file name of the original MIDI or schematic.
header.loop bool Whether the song should loop back to the start after ending.
header.max_loop_count i8 The amount of times to loop. 0 = infinite.
header.loop_start i16 The tick the song will loop back to at the end of playback.

Notes

the notes field has all the notes of type struct Note stored in a vec in order

Attribute Type Details
note.tick i32 The tick at which the note plays.
note.layer i32 The ID of the layer in which the note is placed.
note.instrument i8 The ID of the instrument.
note.key i8 The key of the note. (between 0 and 87)
note.velocity i8 The velocity of the note. (between 0 and 100)
note.panning u8 The stereo panning of the note. (between -100 and 100)
note.pitch i16 The detune of the note, in cents. (between -1200 and 1200)

Layers

the layers field is a vec of all layers of type struct Layer in order

Attribute Type Details
layer.name String The name of the layer.
layer.lock bool Whether the layer is locked.
layer.volume i8 The volume of the layer.
layer.panning u8 The stereo panning of the layer.

Instruments

the instruments field stores all the custom instruments of the song in order in a vec

Attribute Type Details
instrument.name String The name of the instrument.
instrument.file String The name of the sound file of the instrument.
instrument.pitch i8 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.