NoteBlock JS

NoteBlock JS is a JavaScript/TypeScript library designed to add immersive and reactive sound experiences to web applications. It transforms user UI interactions—clicks, hovers, keystrokes—into an engaging auditory experience, featuring thematic ambient background music out of the box.

📖 Leer en Español / Read in Spanish: README.es.md

Why NoteBlock JS?

Most web audio libraries are generic audio players or complex wrappers around the Web Audio API. NoteBlock JS was born out of a different question: What if the user interface sounded as good as it looked?

It offers something unique on npm: a package that combines sonic identity, UI reactivity, and thematic ambient music in one bundle, without complex setup or heavy dependencies.

Available Themes (33 Themes in Total)

NoteBlock JS includes a wide variety of visual and sound themes tailored for different industries and holidays:

🆓 Free Themes

| Theme | Description | |------|-------------| | main | Minimalist, floating musical notes inside a crystal case | | baroque | Golden pendulum, classical acoustic sound | | christmas | Christmas - Festive pine tree and bells | | autumn | Autumn - Falling leaves and warm, nostalgic melody | | winter | Winter - Drifting snowflakes and cold music box | | photography | Photography - Sleek 3D camera lens | | corporate | Business - Executive executive briefcase | | cafe | Coffee shop - Hot cup of coffee with procedural steam | | halloween | Spooky night - Flickering pumpkin candle and flying bats | | wedding | Wedding - Entwined dynamic marriage rings | | education | Education - Open textbook book with chalkboard and particles | | space | Space - Dark planet with orbiting satellite | | gym | Sports - Active headphones positioned vertically |

🔒 Premium Themes (Pro)

Require a valid license key to be unlocked in production.

| Theme | Description | |------|-------------| | celestial | Mystical sphere with orbiting rings and celestial music | | samurai | 3D Samurai helmet, blood moon, and katana slash sound FX | | spring | Spring - Floating flowers and bright ambient sounds | | summer | Summer - Sun rays and beach wave visuals | | dentist | Dentistry - 3D tooth listening to music with headphones | | medical | Medicine - Red cross and interactive EKG heartbeat wave line | | finance | Music visualizer bar chart in navy and cyan tones | | crypto | Cryptocurrency - Spinning golden blockchain coin | | music | Music Production - Vinyl record disc and notes | | umbral | Neon grid, synthwave vibe | | gamer | Gaming - Retro 8-bit dynamic controller | | tech | Technology - Glowing rotating double helix | | anime | Japanese style - Spinning shuriken star | | fashion | Fashion - Elegant wine glass and straw | | realestate | Real Estate - 3D house with opening door and yard sign | | travel | Tourism - Passenger airplane flying around a globe | | beauty | Beauty - Animated cosmetic lipstick | | restaurant | Gastronomy - Interactive hot dish cover cloche | | pet | Pets - Dynamic 3D puppy paw print | | lawyer | Law - Golden scales of justice |

🎮 Interactive Demo & Admin Panel

You can test all themes and sound effects in real time using the interactive admin dashboard.

• In Production: Try it live here: Live Demo (where you can preview and configure all themes and effects).
• In Local Development: Clone the repository and run npm start to open the local demo dashboard (app/demo.html) in your browser.

Features

• 🎵 Built-in Soundtrack Themes — Curated background ambient music ready to go
• ✨ Automatic Interaction Sound Effects — Sound feedback on buttons, links, inputs, and more
• 🎹 Procedural Synthesizer — Synthesizes procedural sounds on the fly for sliders and range elements
• 🎛️ Minimalist Player UI Widget — A sleek, clean, 3D visual component
• 🚀 Ultra-lightweight — ~8 KB minified + gzipped

Installation

npm install noteblock-js

Basic Usage

1. Initialize

import { WebSoundExperience } from 'noteblock-js';

const sound = new WebSoundExperience();

2. Add the Widget container

<div id="player"></div>

sound.initPlayer('#player');

3. Change Themes

sound.setTheme('baroque');
sound.setTheme('umbral');

Initialization Options

By default, the library points to the official NoteBlock JS server to serve the high-quality theme soundtracks. No extra configuration is needed to get started:

const sound = new WebSoundExperience();
sound.initPlayer('#player');

If you want to customize your setup (for instance, when pointing to your own server in local development):

const sound = new WebSoundExperience({
  soundsPath: 'http://localhost:4000/themes', // local server address
  musicVolume: 0.5,            // initial background music volume 0.0 - 1.0 (optional)
  playerSize: 90,              // width/height of the 3D player in px (optional, default 90)
  playerSide: 'left',          // slide out direction ('left' or 'right', default 'right')
  licenseKey: 'YOUR_LICENSE_KEY', // Pro license key (optional)
});

ℹ️ Note: The default soundsPath points to https://noteblocks-api.vcones.com/themes. You only need to change it if hosting assets yourself or developing locally.

Visual Customization

Widget Color

Change the widget accent color dynamically at any time:

sound.setColor('#00dffd');   // any hex color code
sound.setColor('#ff6b35');
sound.setColor('#7f5bd2');

Widget Opacity

Control how visible the visualizer is (ideal for subtle web integrations):

sound.setOpacity(1.0);   // fully visible (default)
sound.setOpacity(0.5);   // semi-transparent
sound.setOpacity(0.0);   // fully transparent (remains interactive)

Widget Size

Adjust the width and height of the 3D player canvas in pixels dynamically:

sound.setSize(120);   // scale up to 120px
sound.setSize(60);    // scale down to 60px

Widget Visibility

Hide or show the visualizer widget without destroying the audio player state:

sound.hidePlayer();   // hides the widget
sound.showPlayer();   // shows the widget

Volume Control

sound.setMusicVolume(0.3);   // adjust music volume (0.0 - 1.0)
sound.setFxVolume(0.8);      // adjust UI interactions volume (0.0 - 1.0)
sound.setFxVolume(0.0);      // mute interactions completely

Song Seeker

Jump to any point in the background track using a fraction value between 0.0 (start) and 1.0 (end):

sound.seek(0.0);
sound.seek(0.5);
sound.seek(0.75);

Playback and Track Control

Control the playback state and switch between different available audio tracks for each theme:

// Stop or pause the music and update the player widget's visual state
sound.stop();

// Switch to a specific music track within the current theme (0-indexed)
// Useful if a theme features multiple musical variations or tracks
sound.setTrack(1);

// Get the index of the music track that is currently playing
const currentTrack = sound.getTrack();

// Query the active theme identifier
const activeTheme = sound.theme; // Example: 'main', 'baroque', etc.

UI Element Effects Filtering

By default, NoteBlock JS adds sounds to all standard interactive tags. You can enable or disable sounds for specific element types:

sound.setElementEffects({
  buttonHover: true,
  buttonClick: true,
  inputHover: false,
  inputType: false,
  checkboxHover: true,
  checkboxClick: true,
  radioHover: true,
  radioClick: true,
  selectHover: true,
  selectClick: true,
  rangeHover: false,
  rangeSlide: true,
  linkHover: true,
  linkClick: true,
  textSelection: true, // sound feedback when selecting text on the page
  tooltipHover: true,
  tooltipClick: true,
});

You can update configurations iteratively at runtime:

sound.setElementEffects({ inputType: false });
sound.setElementEffects({ rangeSlide: false });

Automatic Interaction Sounds

Once the player is active, NoteBlock JS adds auditory feedback automatically to these standard HTML tags and CSS class conventions:

| Event | Target Elements | |--------|-----------| | Click | <button>, <a>, <select>, <input type="radio">, <input type="checkbox">, .tooltip, [data-tooltip], #tooltip | | Hover | <button>, <a>, <select>, <input>, <textarea>, .tooltip, [data-tooltip], #tooltip | | Typing | <input type="text">, <textarea> | | Slider | <input type="range"> | | Text Selection | Selecting text anywhere inside the document |

Custom Trigger Attributes

For non-standard interactive markup, like a div behaving as a button:

<div data-sound-hover>Hover Card</div>
<div data-sound-click>Custom Click Trigger</div>

Global Events

Keep your custom visual UI in sync with NoteBlock JS player state changes using the following global window events:

1. sound-theme-change

Fires every time the active theme or musical track changes:

window.addEventListener('sound-theme-change', (e) => {
  const { theme, trackIndex } = e.detail;
  console.log(`Theme changed to: ${theme}, track: ${trackIndex}`);
  document.body.className = `theme-${theme}`;
});

2. sound-can-play

Fires when the audio track for the current theme has loaded sufficiently in the browser and is ready to start playing:

window.addEventListener('sound-can-play', (e) => {
  const { theme, trackIndex } = e.detail;
  console.log(`Ready to play theme: ${theme}, track: ${trackIndex}`);
});

🔑 Pro Themes & License Keys

Premium themes (such as celestial, samurai, and other industry-specific ones) require a Pro license key to unlock.

You can purchase a license key at: 👉 tgmcode.gumroad.com/l/wnpbnx

Pass the key on initialization to unlock the themes:

import { WebSoundExperience } from 'noteblock-js';

const sound = new WebSoundExperience({
  licenseKey: 'YOUR_LICENSE_KEY_HERE'
});

sound.initPlayer('#player');
sound.setTheme('celestial');

⚠️ Important: Do not hardcode your raw license key in client-side code exposed to the public. We recommend loading it dynamically through server environment variables:

// Next.js / Node.js sample
const sound = new WebSoundExperience({
  licenseKey: process.env.NEXT_PUBLIC_NOTEBLOCKS_LICENSE_KEY
});

Available Plans

| Plan | Allowed Domains | Themes Included | |------|--------------------|-----------------| | Pro | Up to 3 domains | Full access to all Pro themes | | Agency | Unlimited domains | Full access to all Pro themes | | Enterprise | Unlimited domains | Full access to all Pro themes + priority support |

Note: Free themes and interaction sound effects work autonomously without a license key.

License

Copyright © 2026 noteblocksjs. All rights reserved.

This software and its related assets (including but not limited to audio tracks and visual 3D geometries) are proprietary and confidential. Unauthorized copying, distribution, or usage without prior written consent from the author is strictly prohibited.