Docs

Plain ES modules on Web Audio. No dependencies, no build step.

Install · Tabla · Taal JSON · Tanpura · Manjeera · Swarmandal · Swaralipi · Samples · Browsers · Taals

Install

npm i @ugfoundation/tabla-js

No bundler? Import it from jsDelivr:

import { Tabla } from 'https://cdn.jsdelivr.net/npm/@ugfoundation/tabla-js@0/src/index.js'

Types ship in src/index.d.ts.

Tabla

import { Tabla } from '@ugfoundation/tabla-js'
import kehrwa from '@ugfoundation/tabla-js/data/taals/kehrwa.json' with { type: 'json' }

const tabla = new Tabla({ context: new AudioContext(), tonic: 'D', sam: 'bell', filler: 'light', vibrate: true })
await tabla.load(kehrwa, 'Kaharwa 2') // no name = the first variation
tabla.bpm = 97 // matras per minute
tabla.start()
tabla.tihai() // after this cycle: tihai, land on sam, stop

Options

Options are also properties. bpm, tonic, filler and cents can change while it plays.

A variation with one kind of filler plays that kind.

Methods

onBeat

onBeat(beat, time, section) fires up to 0.1 s before each matra sounds.

• beat counts the section's cells. A tihai can span two cycles.
• time is the audio time the matra sounds.
• section is 'theka', 'fillerLight', 'fillerBusy' or 'tihai'. It is 'end' when a tihai lands.

Other exports

Taal JSON

A taal is one file in data/taals/. Its name is the taal id.

{
  "id": "kehrwa", "en": "Kaharwa", "bn": "কাহারবা", "hi": "कहरवा",
  "matra": 8, "bhaags": [4, 4], "sam": 1, "taali": [1], "khali": [5],
  "variations": [
    {
      "name": "Kaharwa 1",
      "theka": ["dha", "dhi", "na", "ti", "na", "dhi", "dha", "dhi"],
      "tihai": ["dhi na", "tete kata", "dha", "dhi na", "tete kata", "dha", "dhi na", "tete kata"],
      "tihaiArrival": "dha"
    }
  ]
}

Taal fields

Cells

One cell per matra. Bols in a cell share the matra equally.

A stroke rings until its drum plays again. Some cells are strokes, not bols: one bol sounds many ways.

Variation fields

Add a taal

1. Copy a file in data/taals/. Name it after the new id.
2. Edit it. Write one cell per matra.
3. Run ./test-local.sh. It checks every variation. The taal shows up on the test page and in the app.

No code? The app's composer builds a taal and exports this JSON.

Tanpura

import { Tanpura } from '@ugfoundation/tabla-js'

const tanpura = new Tanpura({ context, tonic: 'C#', octave: 3, first: 'ma' })
await tanpura.load()
tanpura.start()
await tanpura.tune({ tonic: 'D' }) // fetches a new sample set if needed

Five strings: first, second, Sa, Sa, kharaj. Each pluck rings out. Tuned in just intonation (Pa 3/2, Ma 4/3).

• Bare STRINGS names lie between kharaj and Sa. -low and -high sit an octave off.
• await tune({ tonic, octave, voice, alt }) moves Sa once its strings are fetched.
• The C#3 sample set covers Sa below F#3, the G#3 set the rest.
• NOTES: C … B. TANPURA_BANK: the default sample folder.

Manjeera

import { Manjeera, manjeeraFor } from '@ugfoundation/tabla-js'

const manjeera = new Manjeera({ context, pattern: manjeeraFor(8)[0].pattern })
await manjeera.load()
tabla.onBeat = (beat, time, section) => section !== 'end' && manjeera.beat(beat, time, 60 / tabla.bpm)

• It keeps the tabla's time, beat by beat. The pattern restarts on every sam.
• manjeeraFor(matra) lists the patterns that fit a taal. There are 32.
• A cell holds o (open), x (closed) or - (rest). Its strokes share the matra.
• beat(beat, time, seconds) plays one matra. stop(when?) lets it ring out.

Swarmandal

import { Swarmandal, RAAGS } from '@ugfoundation/tabla-js'

const swarmandal = new Swarmandal({ context, raag: RAAGS.find((r) => r.name === 'Yaman'), tonic: 'C', every: 10 })
await swarmandal.load() // again after changing raag, direction or tonic
swarmandal.start()

• RAAGS holds 117 raags. A line reads S r R g G M M# P d D n N; ' is an octave up.
• swars(line): each swar's semitones above Sa.
• strum(time) strums once, from audio time time.

Swaralipi

import { fromSwaralipi, Tabla } from '@ugfoundation/tabla-js'

const { taal, variation } = await fromSwaralipi(doc.meta.taal)
await tabla.load(taal, variation)

It turns a swaralipi-js taal ({ id, numBeats, bhaags, sam, khaali, variation }) into a tabla-js taal. The cycle is always numBeats long. It picks, in order:

1. the taal's own theka (and fillers, tihai, bols), or variations: a custom taal
2. the catalogue taal with that id or alias
3. that taal repeated to fill the cycle (kawali: 2 × qawwali)
4. any taal with the same vibhags
5. a plain theka on its vibhags, with generated: true

Every taal in gitabitan.io's swaralipi JSON plays a whole cycle. It fetches taals from CATALOGUE: this release on jsDelivr. Pass a second argument to host them yourself.

Samples

Every sound loads from bitoron, the project's asset CDN. Pass bank to host them yourself.

Browsers

• Start audio from a click or tap. Browsers block it before that.
• iPhone on silent: set navigator.audioSession.type = 'playback' first, as music apps do.
• Safari before 17.2 (iOS 16) can't import JSON. Fetch the taal there.
• Every instrument keeps time from a tiny Web Worker, so it plays on with the screen locked. Under a Content Security Policy, allow worker-src blob:. Without it, a plain timer runs instead.
• vibrate works on Android only. No iOS version has navigator.vibrate. Chrome skips it while the phone is on silent.

Taals

Tap a name to play it in the app.

App

The app is a small PWA on the library: the practice player and a taal composer. No build step. It runs offline once installed, and plays on with the screen off.

Contributing

Contributions are welcome under a CLA. See CONTRIBUTING.md. GPL-2.0-only © Upal & Gopa Das Foundation.