Documentation menu

Quick Start

This guide takes you from installation to a production-ready acoustic scroll integration in five steps.

1. Install the package

npm install @puejs/core

2. Create an emitter

An emitter binds an acoustic profile to a scroll container. Pass window to observe the document, or any scrollable element.

TypeScript
import { createEmitter, presets } from "@puejs/core"; const emitter = createEmitter(window, {  preset: presets.organic,});

At this point the emitter is in the idle state. It observes nothing and produces no sound.

3. Start on a user gesture

Browsers only allow audio playback after a user interaction. Call start() from a gesture handler — a click on a dedicated control is the recommended pattern.

TypeScript
const toggle = document.querySelector<HTMLButtonElement>("#acoustic-feedback"); toggle?.addEventListener("click", async () => {  await emitter.start();  toggle.setAttribute("aria-pressed", "true");});

Once started, every scroll above the velocity threshold triggers an emission.

4. Tune the acoustic profile

Presets are a starting point. Every parameter can be overridden, and the result is fully type-checked.

TypeScript
const emitter = createEmitter(window, {  preset: presets.organic,  pitch: { min: 0.82, max: 1.24 },  resonance: 0.65,  duration: 420,  throttle: "velocity",});

Options can also be changed at runtime without recreating the emitter:

TypeScript
emitter.update({ resonance: 0.4, volume: 0.6 });

5. Clean up

Emitters hold an AudioContext and a scroll listener. Release them when the view unmounts.

TypeScript
emitter.destroy();

What's next