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.
All 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:
If the information provided below differs from the old .nbs format, they are marked Green.
The header contains information about the file, all the data must be in the following order:
|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.|
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:
|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||Note block panning||The stereo position of the note block, from 0-200. 100 is center panning.|
|Short (Signed)||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.|
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):
|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||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.|
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 18 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:
|Byte||Custom instruments||The amount of custom instruments (0-18).|
The next four values are repeated the number of custom instruments:
|String||Instrument name||The name of the instrument.|
|String||Sound file||The sound file of the instrument (just the file name, not the path).|
|Byte||Sound pitch||The pitch of the sound file. Just like the note blocks, this ranges from 0-87. Default is 45 (F#4).|
|Byte||Press key||Whether the piano should automatically press keys with this instrument when the marker passes them (0 or 1).|