feat(audio): procedural audio primitives (tone + noise) + audio.ts cleanup

[obiot]

Summary

Lands the procedural-audio surface for melonJS 19.5, plus a clean-up pass on the audio module while we're in there.

New public API on me.audio:

• getAudioContext(): AudioContext | null — exposes the shared WebAudio context used by file-based playback so user code can build custom WebAudio graphs without spawning a second context.
• tone(opts) — fire-and-forget envelope-shaped oscillator with multi-partial freq (array → chord/bell), gain envelope, StereoPanner pan, percussive pitchSlide. Covers UI clicks, hit confirms, simple chimes, placeholder SFX.
• noise(opts) — single-shot noise burst with "white" | "pink" | "brown" spectral colour, optional BiquadFilterNode band-shape with an exponential filterSweep. Covers explosions, hi-hats, swooshes, wind, footsteps.

Both run on the shared context, route through Howler.masterGain, so audio.muteAll() / audio.setVolume() apply uniformly; both are silent no-ops when WebAudio is unavailable.

Types factored out into audio/types.ts: ToneOptions, NoiseOptions, NoiseFilter, PannerAttributes (now exported alongside the function), SoundAsset, LoadSettings. Each field documented with defaults in prose.

Plinko-planck demo refactored to two thin wrappers around audio.tone — drops ~70 lines of bespoke envelope code from plinko-planck/audio.ts.

audio.ts cleanup pass:

• console.log → console.warn for the audio-disabled failure path.
• (Howler as any)._muted → narrow (Howler as unknown as { _muted: boolean })._muted.
• audioTracks: Record<string, Howl> → Record<string, Howl | undefined> (matches runtime), redundant typeof sound !== "undefined" guard halves dropped across 11 functions, missing optional-chaining added to 5 sites.
• Pre-existing panner() bug fixed: was casting a Howl instance to PannerAttributes via as unknown as; now does a proper get-after-set.
• panner() example fixed: distanceModel: "exponential" isn't in Howler's union — switched to "inverse".

JSDoc normalization sweep over every function in audio.ts. Pre-existing module had mixed style (lowercase-no-period summaries vs sentence-case-with-period, stale <br> tags from a pre-TypeDoc renderer, @returns wording drift, optional-bracket inconsistency). Now all in one voice. Functional behaviour unchanged.

Test plan

• pnpm test — 25 tests in tests/audio.spec.js (was 11). New coverage: getAudioContext exports + context sharing, tone (every option combination, pan clamping, zero/negative duration, multi-partial freq, shared-context scheduling), noise (every option combination, optional filter + sweep, pan clamping, zero/negative duration, shared-context scheduling, muteAll/unmuteAll respect).
• pnpm build — melonjs lint + types + bundle all clean.
• pnpm doc — TypeDoc emits 0 audio-specific warnings.
• Plinko-planck verified manually in the dev server — peg clacks still arpeggiate + pan, slot chimes still ring pentatonic per tier, audio.muteAll() from the console silences everything.

API surface checklist

• me.audio.getAudioContext()
• me.audio.tone({ freq, duration, wave?, gain?, attack?, pan?, pitchSlide? })
• me.audio.noise({ duration, type?, gain?, attack?, pan?, filter?, filterSweep? })
• me.audio.ToneOptions / NoiseOptions / NoiseFilter / PannerAttributes / SoundAsset / LoadSettings — types resolvable via the audio namespace

Commits in this PR

7 in scope order:

• b8031b66b feat(audio): expose getAudioContext() + add tone() procedural primitive
• b51371ae7 fix(audio): nudge Howler.ctx creation in getAudioContext()
• 9c9d6c9a6 refactor(audio): tidy tone() module layout
• a0427d826 fix(audio): tone() respects master mute / volume + tighten PannerAttributes
• 16ffd94fc feat(audio): add noise() — procedural noise burst with optional bandshape
• 2ef9356c5 chore(audio): cleanup pass on audio.ts
• a49f25494 docs(audio): normalize JSDoc style across the audio module

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds two new public audio APIs to melonJS — getAudioContext() to expose the shared Howler AudioContext and tone() to fire a single‑shot envelope‑shaped oscillator (multi‑partial freq, gain envelope, pan, pitch slide). The plinko‑planck demo's private synth helper is rewritten on top of the new primitive, dropping ~70 lines of bespoke WebAudio code.

Changes:

• New audio.tone(opts) and audio.getAudioContext() public APIs in packages/melonjs/src/audio/audio.ts, with full JSDoc and a ToneOptions interface.
• Test suite extended in tests/audio.spec.js covering exports, shared context identity, option permutations, pan clamping, zero/negative duration tolerance, and scheduling on the shared context.
• plinko-planck/audio.ts rewritten to consume the new primitive; throttle switched from ctx.currentTime to performance.now(); CHANGELOG entries added.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated no comments.

File	Description
packages/melonjs/src/audio/audio.ts	Adds getAudioContext() and tone() (plus ToneOptions) on top of Howler's shared context.
packages/melonjs/tests/audio.spec.js	New procedural audio describe block exercising the new APIs and edge cases.
packages/examples/src/examples/plinko-planck/audio.ts	Replaces private WebAudio synth with calls to audio.tone; uses performance.now() for throttle.
packages/melonjs/CHANGELOG.md	Documents the two new audio APIs in the unreleased section.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 6 comments.

Comments suppressed due to low confidence (1)

packages/melonjs/src/audio/audio.ts:972

• Same as tone(): the noise envelope uses env.gain.exponentialRampToValueAtTime(...), which requires the gain value at the start of the exponential ramp to be > 0. If callers pass gain: 0/negative, this can throw InvalidStateError. Clamp gain to a small positive floor (or avoid exponential ramps when gain <= 0) to keep noise() truly no-throw.

	const env = ctx.createGain();
	env.gain.setValueAtTime(0, t0);
	env.gain.linearRampToValueAtTime(gain, t0 + atk);
	env.gain.exponentialRampToValueAtTime(0.0001, t1);

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (3)

packages/melonjs/src/audio/audio.ts:1020

• noise() also connects envelope/filter/panner nodes to Howler.masterGain without any teardown. Even though BufferSourceNode stops, the connected Gain/Biquad/StereoPanner nodes can remain in the graph indefinitely, causing graph growth over time. Add an onended handler (or timed cleanup) to disconnect the created nodes once playback completes.

	// Optional band-shaping filter (with optional sweep on its frequency).
	let tail: AudioNode = env;
	if (filter !== undefined) {
		const biquad = ctx.createBiquadFilter();
		biquad.type = filter.type;
		biquad.frequency.setValueAtTime(filter.frequency, t0);
		if (filter.Q !== undefined) {
			biquad.Q.setValueAtTime(filter.Q, t0);
		}
		// Filter sweep also goes through `exponentialRampToValueAtTime`
		// — only schedule the ramp when both start and target are > 0.
		if (filterSweep !== 1 && filter.frequency > 0) {
			biquad.frequency.exponentialRampToValueAtTime(
				Math.max(0.01, filter.frequency * filterSweep),
				t1,
			);
		}
		tail.connect(biquad);
		tail = biquad;
	}

	// Route through master gain so mute/volume apply uniformly.
	const out = Howler.masterGain;
	if (pan === 0) {
		tail.connect(out);
	} else {
		const panner = ctx.createStereoPanner();
		panner.pan.setValueAtTime(Math.max(-1, Math.min(1, pan)), t0);
		tail.connect(panner).connect(out);
	}

	src.start(t0);
	src.stop(t1 + 0.02);

packages/melonjs/src/audio/types.ts:47

• LoadSettings is described as being forwarded to a fetch request / RequestInit, but audio loading is done via Howler (Howl) which uses XHR internally (xhrWithCredentials). The docs should avoid referencing fetch.credentials and instead describe how these fields affect Howler’s request behavior.

/**
 * Optional settings forwarded to the underlying `fetch` request used
 * to load audio resources. Mirrors a subset of the standard `RequestInit`
 * surface (see
 * {@link https://developer.mozilla.org/en-US/docs/Web/API/RequestInit | MDN — RequestInit}).
 * @category Audio
 */
export interface LoadSettings {
	/** Cache-busting query string appended to the resource URL. */
	nocache?: string;
	/** Forwarded to `fetch.credentials` for cross-origin authenticated requests. */
	withCredentials?: boolean;

packages/melonjs/src/audio/types.ts:188

• ToneOptions.attack is documented as capped at duration / 2, but tone() also enforces a minimum attack floor (0.001s) after flooring duration. For very short durations the cap description becomes inaccurate. Please tweak the prose to match the actual clamping rules.

	/**
	 * Attack time in seconds — linear ramp from 0 up to `gain`.
	 * Capped at `duration / 2`. Defaults to `0.005`.
	 */
	attack?: number;

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (2)

packages/melonjs/src/audio/audio.ts:1042

• noise() schedules src.stop(...), but the created nodes (env, optional biquad, optional stereo panner) are never disconnected. Because these nodes are connected to out, repeated calls can grow the audio graph unnecessarily. Consider using src.onended to disconnect the chain (and clear references) once the burst finishes.

	src.start(t0);
	src.stop(t1 + 0.02);

packages/melonjs/src/audio/audio.ts:1039

• noise() assumes ctx.createStereoPanner() exists whenever pan !== 0. To keep this API robust across WebAudio implementations, add a feature check and either skip panning or fall back to a PannerNode-based approach when createStereoPanner is unavailable.

	} else {
		const panner = ctx.createStereoPanner();
		panner.pan.setValueAtTime(Math.max(-1, Math.min(1, pan)), t0);
		tail.connect(panner).connect(out);
	}

[Copilot]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 8 comments.

Comments suppressed due to low confidence (1)

packages/melonjs/src/audio/types.ts:188

• Same as NoiseOptions.attack: ToneOptions.attack is documented as only capped at duration / 2, but runtime clamps to a minimum of 0.001 seconds. Consider reflecting that minimum in the public type docs so the API docs match behavior.

	/**
	 * Attack time in seconds — linear ramp from 0 up to `gain`.
	 * Capped at `duration / 2`. Defaults to `0.005`.
	 */
	attack?: number;

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

packages/melonjs/src/audio/playback.ts:297

• orientation() docs claim omitted y/z default to the current values, but the setter path forwards undefined to sound.orientation(x, y, z, id). Consider reading the current orientation first (or otherwise applying defaults) so the documented behavior is guaranteed, or adjust the docs to reflect the actual behavior.

	const sound = state.tracks[sound_name];
	if (!sound) {
		throw new Error(`audio clip ${sound_name} does not exist`);
	}
	if (x === undefined) {
		return sound.orientation();
	}
	sound.orientation(x, y, z, id);
}

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Comments suppressed due to low confidence (1)

packages/melonjs/src/audio/playback.ts:64

• load() sets the Howler loop option via an assignment (loop: (sound.loop = true)), which forces every loaded sound to loop and mutates the caller’s SoundAsset. This should pass the actual sound.loop boolean (defaulting to false) without modifying the input object.

	state.tracks[sound.name] = new Howl({
		src: urls,
		volume: getGlobalVolume(),
		autoplay: sound.autoplay === true,
		loop: (sound.loop = true),
		html5: sound.stream === true || sound.html5 === true,
		// @ts-expect-error xhrWithCredentials is a valid Howl option but not in the type definitions

[Copilot]

Pull request overview

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.