Skip to content

Commit b186b8e

Browse files
BentroenBentroen
authored
Merge pull request #390 from OpenNBS/gh-pages-dev
Improve NBS documentation: add 'Calculations' section, fix signedness, default values etc.
2 parents a2021c0 + 74e78f3 commit b186b8e

File tree

2 files changed

+75
-39
lines changed

2 files changed

+75
-39
lines changed

‎assets/css/style.scss‎

Lines changed: 12 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,18 @@
11
---
22
---
33

4-
table tbody tr:nth-child(2n).newversion {
5-
background-color: #00ff0032
4+
table tbody tr:nth-child(2n) {
5+
&, & span {
6+
&.newversion {
7+
background-color: #00ff0032
8+
}
9+
}
610
}
711

8-
table tbody tr:nth-child(2n+1).newversion {
9-
background-color: #00ff0049
12+
table tbody tr:nth-child(2n+1) {
13+
&, & span {
14+
&.newversion {
15+
background-color: #00ff0049
16+
}
17+
}
1018
}

‎pages/nbs.md‎

Lines changed: 63 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -14,13 +14,13 @@ permalink: /nbs
1414
<h2>About NBS</h2>
1515
<p>
1616
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. <br><br> 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.<br><br>
17-
All the data types found in a .nbs file are <a href="http://en.wikipedia.org/wiki/Signedness" target="_blank">signed</a>, and in <a href="http://en.wikipedia.org/wiki/Endianness" target="_blank">little-endian</a>. 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:
17+
Unless specified otherwise, the data types found in a .nbs file are <a href="http://en.wikipedia.org/wiki/Signedness" target="_blank">signed</a>, and in <a href="http://en.wikipedia.org/wiki/Endianness" target="_blank">little-endian</a>. 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:
1818
</p>
1919
<ol>
20-
<li>Header</li>
21-
<li>Note blocks</li>
22-
<li>Layers (Optional)</li>
23-
<li>Custom instruments (Optional)</li>
20+
<li><a href="/nbs#part1">Header</a></li>
21+
<li><a href="/nbs#part2">Note blocks</a></li>
22+
<li><a href="/nbs#part3">Layers</a> (Optional)</li>
23+
<li><a href="/nbs#part4">Custom instruments</a> (Optional)</li>
2424
</ol>
2525
<p>
2626
<span>If the information provided below differs from the old .nbs format, they are marked </span> <strong><span style="color: #01cc01c7">Green</span></strong>.
@@ -55,7 +55,7 @@ permalink: /nbs
5555
<!-- Two -->
5656
<section id="two" class="wrapper style2">
5757
<div class="container">
58-
<h2>Part 1: Header</h2>
58+
<h2 id="part1">Part 1: Header</h2>
5959
<p>The header contains information about the file, all the data must be in the following order:</p>
6060
<div class="table-wrapper">
6161
<table class="alt">
@@ -183,7 +183,7 @@ permalink: /nbs
183183
</table>
184184
</div>
185185
<hr>
186-
<h2>Part 2: Note blocks</h2>
186+
<h2 id="part2">Part 2: Note blocks</h2>
187187
<p>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.<br><br>
188188
The pattern of the note block format is as follows:</p>
189189
<div class="table-wrapper">
@@ -241,20 +241,20 @@ permalink: /nbs
241241
<td>The velocity/volume of the note block, from 0% to 100%.</td>
242242
</tr>
243243
<tr class="newversion">
244-
<td>Byte</td>
244+
<td>Byte (unsigned)</td>
245245
<td>Note block panning</td>
246-
<td>The stereo position of the note block, from 0-200. 100 is center panning.</td>
246+
<td>The stereo position of the note block, from 0-200. 0 is 2 blocks right, 100 is center, 200 is 2 blocks left.</td>
247247
</tr>
248248
<tr class="newversion">
249-
<td>Short (Signed)</td>
249+
<td>Short</td>
250250
<td>Note block pitch</td>
251251
<td>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.</td>
252252
</tr>
253253
</tbody>
254254
</table>
255255
</div>
256256
<hr>
257-
<h2>Part 3: Layers</h2>
257+
<h2 id="part3">Part 3: Layers</h2>
258258
<p>
259259
This part is optional. You can choose to stop writing here and the Note Block Studio will still load the song.
260260
However, you cannot simply jump to the next part.<br>
@@ -287,32 +287,32 @@ permalink: /nbs
287287
<td>The volume of the layer (percentage). Ranges from 0-100.</td>
288288
</tr>
289289
<tr class="newversion">
290-
<td>Byte</td>
290+
<td>Byte (unsigned)</td>
291291
<td>Layer stereo</td>
292292
<td>How much this layer is panned to the left/right. 0 is 2 blocks right, 100 is center, 200 is 2 blocks left.</td>
293293
</tr>
294294
</tbody>
295295
</table>
296296
</div>
297297
<hr>
298-
<h2>Part 4: Custom instruments</h2>
298+
<h2 id="part4">Part 4: Custom instruments</h2>
299299
<p>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.<br><br>
300-
A song can have a maximum of <span class="newversion">18</span> 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.
300+
A song can have a maximum of <span class="newversion">240</span> 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.
301301
Before we begin, we need to know the amount of custom instruments:</p>
302302
<div class="table-wrapper">
303303
<table class="alt">
304304
<thead>
305305
<tr>
306-
<th style="text-align: left">Type</th>
307-
<th style="text-align: left">Name</th>
308-
<th style="text-align: left">Description</th>
306+
<th>Type</th>
307+
<th>Name</th>
308+
<th>Description</th>
309309
</tr>
310310
</thead>
311311
<tbody>
312312
<tr>
313-
<td style="text-align: left">Byte</td>
314-
<td style="text-align: left">Custom instruments</td>
315-
<td style="text-align: left">The amount of custom instruments (0-<span class="newversion">18</span>).</td>
313+
<td>Byte (unsigned)</td>
314+
<td>Custom instruments</td>
315+
<td>The amount of custom instruments (0-<span class="newversion">240</span>).</td>
316316
</tr>
317317
</tbody>
318318
</table>
@@ -322,34 +322,62 @@ permalink: /nbs
322322
<table class="alt">
323323
<thead>
324324
<tr>
325-
<th style="text-align: left">Type</th>
326-
<th style="text-align: left">Name</th>
327-
<th style="text-align: left">Description</th>
325+
<th>Type</th>
326+
<th>Name</th>
327+
<th>Description</th>
328328
</tr>
329329
</thead>
330330
<tbody>
331331
<tr>
332-
<td style="text-align: left">String</td>
333-
<td style="text-align: left">Instrument name</td>
334-
<td style="text-align: left">The name of the instrument.</td>
332+
<td>String</td>
333+
<td>Instrument name</td>
334+
<td>The name of the instrument.</td>
335335
</tr>
336336
<tr>
337-
<td style="text-align: left">String</td>
338-
<td style="text-align: left">Sound file</td>
339-
<td style="text-align: left">The sound file of the instrument (just the file name, not the path).</td>
337+
<td>String</td>
338+
<td>Sound file</td>
339+
<td>The sound file of the instrument (relative path from the /Sounds directory).</td>
340340
</tr>
341341
<tr>
342-
<td style="text-align: left">Byte</td>
343-
<td style="text-align: left">Sound pitch</td>
344-
<td style="text-align: left">The pitch of the sound file. Just like the note blocks, this ranges from 0-87. Default is 45 (F#4).</td>
342+
<td>Byte</td>
343+
<td>Sound key</td>
344+
<td>The key of the sound file. Just like the note blocks, this ranges from 0-87. Default is 45 (F#4).</td>
345345
</tr>
346346
<tr>
347-
<td style="text-align: left">Byte</td>
348-
<td style="text-align: left">Press key</td>
349-
<td style="text-align: left">Whether the piano should automatically press keys with this instrument when the marker passes them (0 or 1).</td>
347+
<td>Byte</td>
348+
<td>Press piano key</td>
349+
<td>Whether the piano should automatically press keys with this instrument when the marker passes them (0 or 1).</td>
350350
</tr>
351351
</tbody>
352352
</table>
353353
</div>
354354
</div>
355355
</section>
356+
<!-- Three -->
357+
<section id="three" class="wrapper style1">
358+
<div class="container">
359+
<h2>Calculations</h2>
360+
<p>While processing the NBS file, the actual values of some properties must be calculated from multiple sources (typically layer and note).</p>
361+
<div>
362+
<h3>Note volume</h3>
363+
<p>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:</p>
364+
<code>(layer_volume * note_volume) / 100</code>
365+
</div>
366+
<div>
367+
<h3>Note panning</h3>
368+
<p>Similarly, the actual panning is also calculated from note and layer panning values.</p>
369+
<p>If the layer panning equals 100 (center), note panning is used without any modifications for playback. Otherwise, the following formula is applied:</p>
370+
<code>(layer_panning + note_panning) / 2</code>
371+
</div>
372+
<div>
373+
<h3>Note pitch</h3>
374+
<p>To calculate the actual pitch, it is necessary to combine its key and pitch (detune) using the following formula:</p>
375+
<code>(note_key * 100) + note_pitch</code>
376+
</div>
377+
<div>
378+
<h3>Custom instrument and note pitch</h3>
379+
<p>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:</p>
380+
<code>note_key + instrument_key - 45 + (note_pitch / 100)</code>
381+
</div>
382+
</div>
383+
</section>

0 commit comments

Comments
 (0)