Demo

PxtoneJS v4 Demo

Install

npm

npm install pxtone

JSR (Deno)

deno add jsr:@petamoriken/pxtone

Direct download

Bundled scripts are available on GitHub Releases:

• Pxtone.js — IIFE bundle (exposes a Pxtone namespace as a global, e.g. Pxtone.Pxtone, Pxtone.PxtoneError)
• Pxtone.mjs — ES Modules bundle

Usage

Playing a .ptcop / .pttune file

Pxtone holds a native WebAssembly resource. While it will be automatically released eventually, it is recommended to call close() when the instance is no longer needed to ensure the resource is released promptly. If Symbol.dispose is available in your environment, you can also use the using declaration (Explicit Resource Management).

stream() returns a ReadableStream<AudioData> (format "f32-planar"). To play back with the Web Audio API using AudioBufferSourceNode, schedule each chunk ahead of time:

const response = await fetch("song.ptcop");
const fileBytes = await response.arrayBuffer();

const BUFFER_AHEAD = 0.5; // seconds

const ctx = new AudioContext();
const pxtone = new Pxtone({ sampleRate: ctx.sampleRate });
pxtone.read(fileBytes);

const stream = pxtone.stream({ loop: true });
const reader = stream.getReader();
let nextStartTime = ctx.currentTime + 0.1;

async function scheduleMore() {
  while (nextStartTime < ctx.currentTime + BUFFER_AHEAD) {
    const { done, value: audioData } = await reader.read();
    if (done) return;

    const buffer = new AudioBuffer({
      numberOfChannels: audioData.numberOfChannels,
      length: audioData.numberOfFrames,
      sampleRate: audioData.sampleRate,
    });
    for (let ch = 0; ch < audioData.numberOfChannels; ch++) {
      audioData.copyTo(buffer.getChannelData(ch), { planeIndex: ch });
    }
    audioData.close();

    if (nextStartTime < ctx.currentTime) nextStartTime = ctx.currentTime + 0.05;
    const source = new AudioBufferSourceNode(ctx, { buffer });
    source.connect(ctx.destination);
    source.start(nextStartTime);
    nextStartTime += buffer.duration;
  }
}

await scheduleMore();
setInterval(scheduleMore, 100);

// When stopping playback:
// pxtone.close();

Each AudioData chunk can also be forwarded to an AudioWorkletNode, MediaStreamTrackGenerator, or other consumers:

const response = await fetch("song.ptcop");
const fileBytes = await response.arrayBuffer();

const pxtone = new Pxtone();
pxtone.read(fileBytes);

console.log(pxtone.name);
console.log(pxtone.duration); // total length in seconds

const stream = pxtone.stream({ loop: true });
const reader = stream.getReader();

while (true) {
  const { done, value: audioData } = await reader.read();
  if (done) break;
  // pass audioData to an AudioWorklet, MediaStreamTrackGenerator, etc.
}
pxtone.close();

Decoding a .ptnoise file

decodeNoiseData() returns an AudioData with format "f32-planar". To play it back with the Web Audio API, copy each channel plane into an AudioBuffer:

const response = await fetch("drum.ptnoise");
const fileBytes = await response.arrayBuffer();

const ctx = new AudioContext();
const pxtone = new Pxtone({ sampleRate: ctx.sampleRate });
const audioData = await pxtone.decodeNoiseData(fileBytes);
pxtone.close();

const buffer = new AudioBuffer({
  numberOfChannels: audioData.numberOfChannels,
  length: audioData.numberOfFrames,
  sampleRate: audioData.sampleRate,
});
for (let ch = 0; ch < audioData.numberOfChannels; ch++) {
  audioData.copyTo(buffer.getChannelData(ch), { planeIndex: ch });
}
audioData.close();

const source = new AudioBufferSourceNode(ctx, { buffer });
source.connect(ctx.destination);
source.start();

API

new Pxtone(options?: PxtoneOptions)

Creates an instance backed by a WebAssembly service.

export interface PxtoneOptions {
  /**
   * Number of output channels. Must be `1` (mono) or `2` (stereo).
   * @default 2
   */
  numberOfChannels?: 1 | 2;
  /**
   * Output sample rate in Hz.
   * @default 44100
   */
  sampleRate?: number;
}

Properties

Audio output

| Property | Type | Description | | ------------------ | -------- | ------------------------ | | numberOfChannels | 1 \| 2 | Output channel count | | sampleRate | number | Output sample rate in Hz |

Metadata (available after read())

| Property | Type | Description | | --------- | ---------------- | -------------------------------- | | name | string \| null | Song title (Shift-JIS decoded) | | comment | string \| null | Song comment (Shift-JIS decoded) |

Master (available after read())

| Property | Type | Description | | ------------------ | ---------------- | ------------------------- | | ticksPerBeat | number \| null | Ticks per beat | | beatsPerMeasure | number \| null | Beats per measure | | beatTempo | number \| null | Tempo in BPM | | numberOfMeasures | number \| null | Total number of measures | | numberOfTicks | number \| null | Total length in ticks | | duration | number \| null | Total duration in seconds |

Loop (available after read())

| Property | Type | Description | | ------------------ | ---------------- | ------------------------------- | | loopStartMeasure | number \| null | Loop start position in measures | | loopEndMeasure | number \| null | Loop end position in measures | | loopStart | number \| null | Loop start position in seconds | | loopEnd | number \| null | Loop end position in seconds |

Playback

| Property | Type | Description | | ------------- | -------- | ------------------------------------ | | currentTick | number | Current playback position in ticks | | currentTime | number | Current playback position in seconds |

Song data

| Property | Type | Description | | -------- | ------------------------ | --------------------- | | units | readonly PxtoneUnit[] | Instrument tracks | | events | readonly PxtoneEvent[] | Automation event list |

Methods

static Pxtone.validate(buffer: ArrayBuffer | Uint8Array): boolean

Checks whether buffer is a valid .ptcop or .pttune file without loading it. Returns true if valid, false otherwise.

static Pxtone.validateNoiseData(buffer: ArrayBuffer | Uint8Array): boolean

Checks whether buffer is a valid .ptnoise file without loading it. Returns true if valid, false otherwise.

read(buffer: ArrayBuffer | Uint8Array): void

Loads a .ptcop or .pttune file and prepares it for playback. Throws a PxtoneError if the file is invalid or a stream is currently active.

stream(options?: StreamOptions): ReadableStream<AudioData>

Returns a ReadableStream that yields PCM chunks as AudioData objects (format "f32-planar"). Each chunk has at most numberOfFrames frames; the final chunk may be shorter. Only one stream may be active at a time. Throws a PxtoneError if no data has been loaded or a stream is already active.

export interface StreamOptions {
  /**
   * Playback start position in seconds.
   * @default 0
   */
  startTime?: number;
  /**
   * Units whose `played` flag is false are silenced.
   * @default false
   */
  unitMute?: boolean;
  /**
   * Loop playback from the song's repeat point.
   * @default false
   */
  loop?: boolean;
  /**
   * Maximum number of frames per channel per chunk. The final chunk may be shorter.
   * @default 1024
   */
  numberOfFrames?: number;
  /**
   * Backpressure threshold for the underlying `ReadableStream`.
   * @default 1
   */
  highWaterMark?: number;
  /** AbortSignal to cancel the stream early. */
  signal?: AbortSignal;
}

close(): void

Releases the underlying Wasm resource. Safe to call multiple times; subsequent calls are no-ops. If Symbol.dispose is available in the runtime environment, it is aliased to close() so the using declaration also works.

clear(): void

Resets the instance to its initial idle state, discarding all loaded song data.

decodeNoiseData(buffer: ArrayBuffer | Uint8Array): Promise<AudioData>

Decodes a .ptnoise file and returns an AudioData with format "f32-planar". Throws a PxtoneError if the data is invalid.

PxtoneError

Thrown by Pxtone methods on operation failures. Extends Error with an optional code property for programmatic error handling.

| code | Static constant | Description | | ------------------------------- | ---------------------------------------------- | ----------------------------------------------- | | "DISPOSED" | PxtoneError.CODE_DISPOSED | The instance has already been disposed. | | "STREAMING_ACTIVE" | PxtoneError.CODE_STREAMING_ACTIVE | Operation not allowed while a stream is active. | | "NOT_READY" | PxtoneError.CODE_NOT_READY | read() has not been called yet. | | "READ_FAILED" | PxtoneError.CODE_READ_FAILED | Failed to load the pxtone data. | | "TONES_READY_FAILED" | PxtoneError.CODE_TONES_READY_FAILED | Failed to initialize audio tones. | | "PLAYBACK_PREPARATION_FAILED" | PxtoneError.CODE_PLAYBACK_PREPARATION_FAILED | Failed to prepare audio playback. | | "RENDER_NOISE_FAILED" | PxtoneError.CODE_RENDER_NOISE_FAILED | Failed to render noise data. |

try {
  pxtone.read(buffer);
} catch (e) {
  if (e instanceof PxtoneError && e.code === PxtoneError.CODE_READ_FAILED) {
    console.error("Invalid pxtone file");
  }
}

PxtoneUnit

| Property | Type | Description | | -------- | --------- | -------------------------------------- | | name | string | Display name | | played | boolean | Whether the unit is active (not muted) |

togglePlayed(force?: boolean): void

Toggles the played flag for this unit. If force is provided, the flag is set explicitly rather than toggled.

PxtoneEvent

| Property | Type | Description | | -------- | ----------------- | ----------------------------------------------- | | tick | number | Tick position | | unit | PxtoneUnit | Target unit in the loaded song | | kind | PxtoneEventKind | Event type (see PxtoneEvent.KIND_* constants) | | value | number | Event payload |

WebAssembly

src/pxtone.wasm is built from petamoriken/pxtone-rs, a Rust port of the Pxtone Collage library.

License

MIT

See NOTICE.md for third-party license notices.