nbs.js

Robust API for reading, manipulating, and writing OpenNBS files, inspired by NBSEditor and NBS4j.

It's cleanroom, too! No required dependencies!

🔧 Including

Tip

When using esm.run links, it's recommended to use versioned links! (e.g. @encode42/[email protected])

🟢 Node.js

Add the @encode42/nbs.js package from NPM using the package manager of your choice.

import { Song } from "@encode42/nbs.js"; // ESM (TypeScript, Vite, etc.)

const { Song } = require("@encode42/nbs.js"); // CJS (vanilla Node.js)

🌐 Browser

<script type="module">
	import { Song } from "https://esm.run/@encode42/nbs.js";
</script>

🦕 Deno

import { Song } from "https://esm.run/@encode42/nbs.js";

❔ FAQ

How do I use this?

Install nbs.js for your platform, then refer to the documentation and examples below.

There are more examples designed for use with Node.js in the examples directory!

🟢 Node.js

// ESM (TypeScript, Vite, etc.)
import { readFileSync } from "node:fs";
import { fromArrayBuffer } from "@encode42/nbs.js";

// CJS (vanilla Node.js)
const { readFileSync } = require("fs");
const { fromArrayBuffer } = require("@encode42/nbs.js");

const songFile = readFileSync("song.nbs"); // Read the selected NBS file
const buffer = new Uint8Array(songFile).buffer; // Convert it into an ArrayBuffer
const song = fromArrayBuffer(buffer); // Parse the buffer

console.dir(song);

🌐 Browser

<input type="file" id="file-input">

<script type="module">
	import { fromArrayBuffer } from "https://esm.run/@encode42/nbs.js"

	window.addEventListener("load", () => {
		const input = document.getElementById("file-input");

		// Initialize file input
		input.addEventListener("change", () => {
			const songFile = input.files[0]; // Read the selected NBS file
			songFile.arrayBuffer().then(buffer => { // Convert it into an ArrayBuffer
				const song = fromArrayBuffer(buffer); // Parse the buffer

				console.dir(song);
			});
		});
	});
</script>

🦕 Deno

import { fromArrayBuffer } from "https://esm.run/@encode42/nbs.js";

const songFile = await Deno.readFile("song.nbs"); // Read the selected NBS file
const buffer = new Uint8Array(songFile).buffer; // Convert it into an ArrayBuffer
const song = fromArrayBuffer(buffer); // Parse the buffer

console.dir(song);

Is there a demo?

Yes! A demo site is located here. It serves as an example of how to read NBS files, allows you to edit the song structure, and plays the result through the browser.

This repository also contains tests that could be used as examples, and examples designed for Node.js.

Where's the changelog?

I don't create GitHub releases, but I do keep a changelog here!

🔨 Building

Ensure PNPM and Node.js are installed.

1. Enter the directory containing the nbs.js source code in your terminal.
2. Install the build dependencies via pnpm install.
3. Run pnpm run build to generate the ESM and browser modules.

Generated files:

• dist/*.js: ESM bundle files for Node.js and related
• dist/*.global.js: UMD bundle files for browser scripts
• build/: Built ES2020 files.