About NBS

The .nbs format (Note Block Song) was created to work with Minecraft Note Block Studio, and contains data about how note blocks are laid out in the program to form a song.

To bring new features to Note Block Studio and make it future-proof, we are using an improved file format. The first 2 bytes of the .nbs file have been changed to 0 to indicate the new format.

Unless specified otherwise, the data types found in a .nbs file are signed, and in little-endian. Strings consist of a 32-bit integer, and then that many bytes for the characters. The file is made up of four parts, two of which are mandatory:

  1. Header
  2. Note blocks
  3. Layers (Optional)
  4. Custom instruments (Optional)

If the information provided below differs from the old .nbs format, they are marked Green.


NBS Changelog

Version 5:
  • May now hold up to 240 custom instruments, previously 18.
  • The path to custom sound files may contain slash characters, as a result of allowing custom sounds to be loaded from subfolders.
  • No fields have been added or removed, so version 5 files may be read identically to version 4.
Version 4:
  • Loop on/off, max loop count, and loop start tick are now saved.
  • The program now saves which layers are locked.
  • Note blocks now store velocity, panning, and pitch. These work in conjunction with layer volume and layer stereo.
Version 3:
  • Song length is now saved again after the vanilla instrument count.
Version 2:
  • Now stereo information is saved for each layer. This means that now the sound can pan to the left/right.
  • For every layer, there's now a byte that determines how much that layer pans.
    0 is 2 blocks right, 100 is centre, 200 is 2 blocks left.
Version 1:
  • The first two bytes, which used to indicate the song length, have been changed to 0 to indicate the new format.
  • The NBS version is now stored in the file.
  • The byte after the NBS version is now the amount of vanilla instruments.
    This change was necessary because, previously, the program didn't know when the custom instruments began. It always went up to 9, and everything after that was treated as a custom instrument.
Classic (Version 0):
  • This version is used by the original Minecraft Note Block Studio, which precedes the transition to Open Note Block Studio. You can find the original specification here.

Part 1: Header

The header contains information about the file, all the data must be in the following order:

Type Name Description
Short The first 2 bytes are always zero. In the old NBS format, this used to be song length, which can never be zero.
This is how you can check whether a .nbs file is using the new format.
Byte NBS version The version of the new NBS format.
Byte Vanilla instrument count Amount of default instruments when the song was saved. This is needed to determine at what index custom instruments start.
Short Song length The length of the song, measured in ticks. Divide this by the tempo to get the length of the song in seconds. Note Block Studio doesn't really care about this value, the song size is calculated in the second part.
(Note: this was re-added in NBS version 3)
Short Layer count The last layer with at least one note block in it, or the last layer that has had its name, volume or stereo changed.
String Song name The name of the song.
String Song author The author of the song.
String Song original author The original author of the song.
String Song description The description of the song.
Short Song tempo The tempo of the song multiplied by 100 (for example, 1225 instead of 12.25). Measured in ticks per second.
Byte Auto-saving Whether auto-saving has been enabled (0 or 1). As of NBS version 4 this value is still saved to the file, but no longer used in the program.
Byte Auto-saving duration The amount of minutes between each auto-save (if it has been enabled) (1-60). As of NBS version 4 this value is still saved to the file, but no longer used in the program.
Byte Time signature The time signature of the song. If this is 3, then the signature is 3/4. Default is 4. This value ranges from 2-8.
Integer Minutes spent Amount of minutes spent on the project.
Integer Left-clicks Amount of times the user has left-clicked.
Integer Right-clicks Amount of times the user has right-clicked.
Integer Note blocks added Amount of times the user has added a note block.
Integer Note blocks removed The amount of times the user have removed a note block.
String MIDI/Schematic file name If the song has been imported from a .mid or .schematic file, that file name is stored here (only the name of the file, not the path).
Byte Loop on/off Whether looping is on or off. (0 = off, 1 = on)
Byte Max loop count 0 = infinite. Other values mean the amount of times the song loops.
Short Loop start tick Determines which part of the song (in ticks) it loops back to.

Part 2: Note blocks

The next part contains the information about how the note blocks are placed, what instruments they have and what note. As you may know, the song is divided into ticks (horizontally) and layers (vertically). Often, a majority of the ticks and layers in the song are empty, which is why we specify the amount of "jumps" to the next active tick or layer, rather than just a bunch of empty slots.

The pattern of the note block format is as follows:

Type Name Description
Short Jumps to the next tick The amount of "jumps" to the next tick with at least one note block in it. We start at tick -1. If the amount of jumps is 0, the program will stop reading and proceed to the next part.
Short Jumps to the next layer Once we have found an active tick, we read the amount of vertical jumps to the next layer. We start at layer -1. If this is 0, we go back to step 1. If not, we have found a note block!
Byte Note block instrument The instrument of the note block. This is 0-15, or higher if the song uses custom instruments.
0 = Piano (Air)
1 = Double Bass (Wood)
2 = Bass Drum (Stone)
3 = Snare Drum (Sand)
4 = Click (Glass)
5 = Guitar (Wool)
6 = Flute (Clay)
7 = Bell (Block of Gold)
8 = Chime (Packed Ice)
9 = Xylophone (Bone Block)
10 = Iron Xylophone (Iron Block)
11 = Cow Bell (Soul Sand)
12 = Didgeridoo (Pumpkin)
13 = Bit (Block of Emerald)
14 = Banjo (Hay)
15 = Pling (Glowstone)
Byte Note block key The key of the note block, from 0-87, where 0 is A0 and 87 is C8. 33-57 is within the 2-octave limit.
Byte Note block velocity The velocity/volume of the note block, from 0% to 100%.
Byte (unsigned) Note block panning The stereo position of the note block, from 0-200. 0 is 2 blocks right, 100 is center, 200 is 2 blocks left.
Short Note block pitch The fine pitch of the note block, from -32,768 to 32,767 cents (but the max in Note Block Studio is limited to -1200 and +1200). 0 is no fine-tuning. ±100 cents is a single semitone difference. After reading this, we go back to step 2.

Part 3: Layers

This part is optional. You can choose to stop writing here and the Note Block Studio will still load the song. However, you cannot simply jump to the next part.

Here the information about the layers are stored, which includes their name, volume and stereo. These values are repeated the same number of layers in the song (the song height, specified in the header):

Type Name Description
String Layer name The name of the layer.
Byte Layer lock Whether or not this layer has been marked as locked. 1 = locked.
Byte Layer volume The volume of the layer (percentage). Ranges from 0-100.
Byte (unsigned) Layer stereo How much this layer is panned to the left/right. 0 is 2 blocks right, 100 is center, 200 is 2 blocks left.

Part 4: Custom instruments

Finally, the custom instruments of the song are stored. Like the previous part, this is optional. You can stop writing here and the song will still be loaded.

A song can have a maximum of 240 custom instruments, each with a name and sound file assigned to it. The sound file must be located in the /Sounds folder of the Minecraft Note Block Studio directory. Before we begin, we need to know the amount of custom instruments:

Type Name Description
Byte (unsigned) Custom instruments The amount of custom instruments (0-240).

The next four values are repeated the number of custom instruments:

Type Name Description
String Instrument name The name of the instrument.
String Sound file The sound file of the instrument (relative path from the /Sounds directory).
Byte Sound key The key of the sound file. Just like the note blocks, this ranges from 0-87. Default is 45 (F#4).
Byte Press piano key Whether the piano should automatically press keys with this instrument when the marker passes them (0 or 1).

Calculations

While processing the NBS file, the actual values of some properties must be calculated from multiple sources (typically layer and note).

Note volume

In Note Block Studio, each note can have its own velocity value. However, the actual volume of the note, when played, is affected according to the volume of the layer it's placed at. The following formula is used to achieve this behavior:

(layer_volume * note_volume) / 100

Note panning

Similarly, the actual panning is also calculated from note and layer panning values.

If the layer panning equals 100 (center), note panning is used without any modifications for playback. Otherwise, the following formula is applied:

(layer_panning + note_panning) / 2

Note pitch

To calculate the actual pitch, it is necessary to combine its key and pitch (detune) using the following formula:

(note_key * 100) + note_pitch

Custom instrument and note pitch

The audio file used for a custom instrument may be in a key other than F#4 (45), which is the center of Minecraft's 2-octave range and also the default value for all vanilla instruments. If that's the case, the final pitch of the played notes would not correspond to the pitch displayed in Note Block Studio. As such, the instrument's pitch must be taken into account while calculating the actual pitch of the played note. The final pitch is calculated using the following formula:

note_key + instrument_key - 45 + (note_pitch / 100)