Code creation:NbsApi

From Lê Duy Quang's personal wiki
Jump to: navigation, search

NbsApi (short for Note block song application programming interface) is a Java library for reading and writing Minecraft note block song files (.nbs) for use in Minecraft Note Block Studio.

Overview[edit]

The API provides high-level interface for reading and editing note block songs, even creating new songs from scratch.

The library's release as well as its source code can be found here. You can also check out its Javadoc.

Usage[edit]

This section describes general usage of the library. For a detailed description of classes and functions, as well as the syntax, refer to the library's Javadoc.

Creating a new song[edit]

A song can be made from scratch by invoking the constructor Song. The parameters are described in the table below.

Parameters for Song constructor
Name Type Description
length short The length of the song. Deprecated as the length is now determined by the note table.
name String The name of the song.
author String The author of the song. Can ba the one made this file.
originalAuthor String The original author of the song (if any).
description String The description of the song.
tempo short The tempo of the song. Must be a multiple of 25 and from 25 to 2000. The song will play at a rate of tempo:100 ticks per second.
autoSave boolean Whether the song is automatically saved after a specified interval when open in Minecraft Note Block Studio.
autoSaveDuration byte The time in minutes that when passed Minecraft Note Block Studio will save the file.
timeSignature byte The number of notes per beat.
minutesSpent int The corresponding stat.
leftClicks
rightClicks
blocksAdded
blocksRemoved
MidiSchematicFile String The name of the file (MIDI, schematic) that the song was imported from.
songBoard List<Layer> The main part of the song; containing all of the notes. Enter new ArrayList<Layer>() to make it a fresh start.

Reading a song from file[edit]

A song can be read from A .nbs file. Invoke the constructor Song(fromFile).

Reading/Editing song metadata[edit]

All of the metadata can be read by calling getX(), where X is the name of a parameter above. They can also be edited by invoking setX(newX).

Editing song board[edit]

The song board contains all of the notes in the song. It consists of layers as rows, each layer contains a series of notes on that row.

Layer[edit]

A layer is a "row" of the song board.

Creating a layer[edit]

There are two constructors for a Layer:

  • Layer(): An empty layer with default settings (name = ""; volume = 100).
  • Layer(String name, byte volume): An empty layer with a name and volume.
Layer properties[edit]

A layer has two properties:

  • String name: The name of the layer.
  • byte volume: The volume of the layer. Must be from 0 (muted) to 100 (maximum volume).

They are get/setable with approriate methods.

Notes (musical)[edit]

The main part of a layer is a list of notes, which is a HashMap and is retrievable by invoking getNoteList(). The keys are integers specifying a tick, and the values are notes at those ticks.

Each note contains two attributes:

  • instrument: Specifies the sound when the note is played. Can be one of these:
    • BASS
    • BELL
    • CHIME
    • CLICK
    • DRUM
    • FLUTE
    • GUITAR
    • HARP
    • SNARE
    • XYLOPHONE
  • pitch: A number from 0 to 87 specifying the pitch of the note.

Saving the song[edit]

A song can be saved to a file by invoking one of the following:

  • writeSongToFile(File file): Writes the song to the specified file in .nbs format.
  • writeSongToMidiFile(File file): Writes the song to the specified file as MIDI. Each channel stores note for an instrument in the song.