API リファレンス

import { analyse, chord, degree, frequency, loudness, mix, notes, parse, parseKey, Player, render } from "plonkjs";
import type { Analysis, Instrument, MixReport, NoteEvent, PlayerOptions, PlayOptions, SfxOptions, Song } from "plonkjs";

Player

new Player(options?: { context?: AudioContext; destination?: AudioNode; master?: boolean })

メンバー	意味
play(song, { fade?, at? })	曲を先頭から、またはステップ at からループ再生します。fade 秒かけてフェードインします。再生中の曲は置き換わります。
stop(fade = 0)	fade 秒かけてフェードアウトし、停止します。
tempo(scale)	次の音符から速くしたり遅くしたりします。1 が曲本来の bpm です。
layer(instrument, volume, fade = 0.5)	ひとつの楽器のトラックを volume（0〜1）までフェードします。
sfx(instrument, options)	単発の効果音を鳴らします。音高は曲の調の degree（または note、freq）で、強さは velocity、長さは length 秒です。次の "step"、"beat"、"bar" まで待つこと（quantize）も、さらに after ステップ遅らせることもできます。鳴る時刻を返します。音楽をフェードアウトしていても効果音は鳴ります。
playing	曲が再生中かどうか。
played	直近にスケジュールされた 256 個の音符（音楽と効果音）。NoteEvent の配列です。
context	使用中のオーディオコンテキスト。

音符はオーディオクロック上で 0.15 秒先までスケジュールされます。そのため、ゲームのフレームが遅れても音楽はずれません。

Song

interface Song {
  bpm: number;
  swing?: number; // 0〜0.5
  key?: string; // "C major"、"A minor" など
  transpose?: number; // 半音
  instruments: Record<string, Instrument>;
  sections: Record<string, Record<string, string | string[]>>; // セクション -> 楽器 -> パターン（またはバリエーション）
  order: string[];
}

パターンの記法は曲とパターンを、Instrument については楽器を見てください。

純粋なヘルパー関数

関数	戻り値
notes(song, from, to)	ステップ [from, to) で始まるすべての NoteEvent。order に沿ってループします。
parse(pattern)	パターンのステップ。何かが始まるステップは Step（{ freqs, velocity, length }）、それ以外は null です。読めないステップがあると例外を投げます。
frequency(name)	音符名を Hz で返します（"A4" は 440）。読めなければ undefined。
chord(name)	オクターブ付きの和音名（"Am7@3"）を周波数の配列で返します。読めなければ undefined。
degree(key, n, octave = 4)	key の音階の n 度を Hz で返します（1 が主音、8 が 1 オクターブ上）。
parseKey(key)	調の主音と音階。音階の一覧は SCALES にあります。
songSteps(song)	曲を 1 周するステップ数。
sectionSteps(section)	セクションのステップ数。いちばん長いパターンの長さです。
stepSeconds(bpm)	1 ステップ（16 分音符）の秒数。

測る

関数	戻り値
mix(song, seconds = 20)	曲全体と楽器ごとの音をオフラインでレンダリングし、MixReport を返します。中身は曲全体の Analysis、トラックごとのラウドネスとミックスからどれだけ下にあるか、そしてわかりやすい言葉の warnings です。ブラウザ専用です（OfflineAudioContext が必要）。
render(song, seconds, only?)	曲（または一部の楽器だけ）を 48 kHz でオフラインレンダリングし、チャンネルごとのサンプルとして返します。ブラウザ専用です。
analyse(channels, rate?)	サンプルの Analysis。peakDb、clipped、lufs（ITU-R BS.1770）、bands（低域・中域・高域の割合）、silence を含みます。純粋な関数なので、どこでも動きます。
loudness(channels, rate?)	積分ラウドネス（LUFS）。純粋な関数です。

interface NoteEvent {
  time: number; // ステップ 0 からの秒数
  instrument: string;
  freq: number; // Hz、ドラムの場合は 0
  duration: number; // 秒
  velocity: number; // 0〜1
}