Play Pxtone Collage "pxtone" files in the browser.

PxtoneJS v4 Demo

npm install pxtone

deno add jsr:@petamoriken/pxtone

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

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();

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();

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;
}

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

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

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.

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;
}

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.

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

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

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

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

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

Each note corresponds to one note-on event. Pitch, volume, and stereo-pan changes during the note are represented by segments. Notes belonging to the same unit never overlap: if the next note-on arrives before the current note is over, the current note is cut short at that tick.

velocity is the value written alongside the note-on, which is how pxtone stores the velocity of a note. A note with no velocity event of its own keeps whichever value was still in effect, starting from the default of 104.

A note always has at least one pitch segment, and its segments are chronological and cover the note from startTick to endTick without gaps. Portamento is exposed as a continuous linear model for visualization; tuning events and sample-level integer rounding are not included.

targetKey equals endKey except when the note ends, or another key event arrives, before the portamento completes; then endKey is the interpolated pitch reached so far while targetKey stays the key that was written. Renderers that snap a note to a single key row want targetKey; renderers that draw the glide want endKey.

Volume and pan-volume events change their value immediately rather than interpolating. Each array is chronological and covers the note without gaps. Values set before a note are carried into its first segment. Volume defaults to 104; pan volume defaults to 64 and ranges from 0 (left) to 64 (center) to 128 (right).

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

MIT

See NOTICE.md for third-party license notices.