# Quickstart · zvuk

zvuk v1.14.1 · MIT · https://zvuk.schmooky.dev/docs/quickstart/

Two function calls and a user gesture.

Start here

# Quickstart

Two function calls and a user gesture.

## 1\. Install

bash bash

```
pnpm add @schmooky/zvuk
```

## 2\. Construct the engine

Declare your buses up front. `createEngine` does not touch the AudioContext. It records the shape of the mix and nothing else, so calling it at module load is safe.

ts ts

```
import { createEngine } from '@schmooky/zvuk';

export const engine = createEngine({
  buses: {
    music: { level: 0.8 },
    sfx:   { level: 1.0 },
    ui:    { level: 0.7 },
  },
  master: { headroom: -3 },  // dB
});
```

## 3\. Unlock from a user gesture

Browsers block audio until the user does something. Call `engine.unlock()` from a click, tap or keypress handler. It is idempotent, so calling it from several handlers is fine.

ts ts

```
document.querySelector('button')!.addEventListener('click', async () => {
  await engine.unlock();
  await engine.loadSound('coin', ['/sfx/coin.webm', '/sfx/coin.m4a'], { bus: 'sfx' });
  engine.sound('coin').play();
});
```

Pass an array of URLs to ship a codec ladder. The first one your browser can decode wins. [Asset formats](/guides/asset-formats/) explains why that matters more than it sounds.

## 4\. Play, fade, mix

Every time-valued option in zvuk is in **seconds**. Fades, crossfades, attack and release, snapshot applies, all of them. That matches the Web Audio API, so there is one convention to remember rather than two.

ts ts

```
const v = engine.sound('coin').play({
  volume: { jitter: 0.05 },
  pitch:  { jitter: 0.04 },
});

// Bus-level fade — click-free (duration in seconds)
engine.bus('music').fadeTo(0.1, 0.8);

// Voice-level fade with curve
await v.fade({ to: 0, duration: 0.8, curve: 'equal-power' });
await v.ended;
```

## 5\. Clean up

On an SPA route change or a game teardown, call `engine.close()`. Every voice stops, the AudioContext closes, and listeners detach. Close is terminal. Construct a new engine if you need audio again.

ts ts

```
await engine.close();
```

## Where to go next

-   [The Engine](/concepts/engine/) covers the full lifecycle, state machine and scheduler.
-   [Bus](/concepts/bus/) covers routing, concurrency and sidechain.
-   [Recipes](/recipes/) has six patterns you can click and copy.
-   [Asset formats](/guides/asset-formats/) walks through webm/Opus and m4a/AAC.