How do I unlock audio on iOS Safari?

Call await engine.unlock() from inside a real user gesture such as a click, tap or keydown. It is idempotent, so wiring it to several handlers is safe. zvuk creates the AudioContext lazily, so createEngine() before any gesture is fine, and it handles the suspend and resume around tab visibility and iOS audio-session interruptions for you.

Why is my sound cutting off mid-playback?

Usually one of three things. A shared HTMLAudioElement is being recycled, so the second play restarts the first. Or a bus concurrency cap is stealing the voice to make room for a newer one. Or the voice was garbage-collected because nothing held a reference. zvuk gives every play() its own Voice with its own source node, and voice stealing is an explicit per-bus policy rather than a side effect.

Background

Why another audio lib?

Q: Should I use zvuk or Howler.js?

Use Howler if you need to play clips and stop them, want the widest browser support including very old engines, and do not need a mixer. Use zvuk if your audio has structure: named buses, ducking, snapshots, voice limits, per-voice control. Howler has no first-class mixer model, no parameters and no snapshots; zvuk does not try to match its legacy browser reach.

Q: Should I use zvuk or Tone.js?

Tone.js is a music framework built around a transport and a synthesis graph. If you are sequencing notes, building an instrument, or writing anything with a musical clock, use Tone. zvuk plays and mixes recorded assets; it has no oscillators and no transport.

Howler exists. Tone.js exists. Raw Web Audio exists. Here is the gap zvuk fills.

The problem

Game audio on the web has three failure modes.

Autoplay and iOS Safari. Roughly half of the audio bug reports I have seen on shipped web games are some version of "no sound on iPhone".
Polyphony. Spam a reel-stop sound thirty times and the second one cuts off the first, because the same HTMLAudioElement is being recycled underneath.
Mix discipline. Ducking music under dialogue. Crossfading menu states. Reverb on ambience but not on UI. Web Audio gives you nodes. Nobody gives you the routing model.

Should I use zvuk or Howler?

Use Howler if you want to play clips and stop them, you need the widest possible browser support, and your mix is a volume slider. It is battle-tested and it will outlive us all.

Use zvuk if your audio has structure. Named buses, ducking, snapshots, voice limits, per-voice control. That is the part Howler does not model, and the part you end up writing yourself.

	zvuk	Howler	Tone.js	pixi-sound
Named mixer buses	yes	no	channels	no
Sidechain ducking	built in	no	build it	no
Mix snapshots	yes	no	no	no
Voice limits and stealing	per bus	no	no	no
Synthesis and transport	no	no	yes	no
Codec ladder	yes	yes	manual	yes
Renderer coupling	none	none	none	PixiJS
Use it if	your mix has structure	you just need clips	you are writing music	you already ship Pixi

Should I use zvuk or Tone.js?

Tone is a music framework. It has a transport, a synthesis graph, and scheduling built around musical time. If you are sequencing notes or building an instrument, use Tone and don't look back. zvuk plays and mixes recorded assets. There is no oscillator in it.

What zvuk adds

An Engine with an explicit state machine, running cold, unlocking, live, suspended, interrupted, closed.
A Mixer declared in createEngine config, with named buses and click-free fades.
A Voice per play() call, carrying abort signals, lifecycle promises and an async iterator of cues.
A codec ladder, so ['sfx.webm', 'sfx.m4a'] ships Opus to the world and AAC only to the devices that need it.
An iOS Safari resume sequence that has survived production slot games. On iOS 15 an immediate resume() after a visibility change failed often enough to be a bug report; a 200 ms delay stopped it.

What zvuk is not

A synthesis framework. There is no oscillator graph and no transport.
A streaming music player. Stream wraps <audio> for long files, and stops there.
A native bridge. v1 runs in browsers.

If you are shipping a slot game, an arcade title, a casual mobile-web game, or an interactive explainer where the sound has to hold together as a mix rather than as a pile of clips, that is the shape of the hole zvuk fills.