> For the complete documentation index, see [llms.txt](https://wiki.playgama.com/playgama/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.playgama.com/playgama/guides/game-development/sound.md).

# Sound

Audio assets, one volume controller for mute, pause, ads and the platform audio state, and browser autoplay.

Sound is required — music, effects for actions and interface sounds — and so is its control: a mute button, silence during ads and in the background, and respect for the platform's own mute. Both missing sound and sound that keeps playing when it should not are among the most common reasons a game is sent back. The rules are in section 3.3 of the [User Experience Requirements](/playgama/game-requirements/user-experience-requirements.md) and item 2.1.6 of the [Advertising and Payments Requirements](/playgama/game-requirements/advertising-requirements.md).

## Get good audio

* Use recorded or professionally produced sound: a licensed or free (CC0) sound library, a composer, or a dedicated audio generation tool. Sound synthesized in code — procedural Web Audio tones, including those an AI coding agent writes — is not accepted (item 3.3.2).
* Choose sounds in one style, normalize their loudness, and keep effects short so they do not pile up.
* Give the game a music track for menus and one for gameplay at least; loop it without an audible gap.
* Ship compressed files: OGG or MP3 for music, short OGG/MP3 or an audio sprite for effects. Never ship WAV — it multiplies the download size and the load time.
* Load the music after `game_ready` instead of before it: the player should not wait for a soundtrack to start playing (see [Performance & Optimization](/playgama/guides/performance-and-optimization.md)).

## One volume controller

Most sound bugs come from several places muting and unmuting the game independently. Keep one controller that owns the master volume and computes it from all the reasons the game must be silent:

| Reason                             | Where it comes from                                                                                                                                                                                                                     |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| The player pressed the mute button | the game's own setting, saved through [Storage](/playgama/bridge-sdk/api/storage.md)                                                                                                                                                    |
| The platform muted the game        | [`platform.isAudioEnabled`](/playgama/bridge-sdk/api/platform.md#is-audio-enabled) at startup, then `AUDIO_STATE_CHANGED`                                                                                                               |
| The platform paused the game       | [`PAUSE_STATE_CHANGED`](/playgama/bridge-sdk/api/platform.md#pause)                                                                                                                                                                     |
| A full-screen ad is open           | [interstitial state](/playgama/bridge-sdk/api/advertisement/interstitial.md#interstitial-state) and [rewarded state](/playgama/bridge-sdk/api/advertisement/rewarded.md#rewarded-state) `opened` until `closed`, `rewarded` or `failed` |
| The page is hidden                 | `document.visibilitychange`                                                                                                                                                                                                             |

The game is audible only when none of these applies. When the last reason goes away, the controller restores the volume — and it never turns sound on just because one of the reasons cleared while another still holds.

* Read `platform.isAudioEnabled` once at startup, before any sound plays: the event only reports later changes (item 3.3.4). A game reloaded while the platform is muted must stay silent.
* Stop the game loop together with the sound when the game is paused by the platform or by an ad (item 2.1.6).
* The mute button (item 3.3.3) controls only the player's own reason; it is shown on the main menu and in the pause menu.

## Browser autoplay

Browsers block audio until the player interacts with the page. Create or resume the `AudioContext` (or call your engine's audio unlock) in the first `pointerdown`/`keydown` handler, and do not try to play music on the loading screen before that. On iOS, resume the context again when the page becomes visible — Safari can leave it suspended after the page was in the background.

## Check before uploading

* The game is silent from the first frame when started with the platform muted, and after a reload in that state.
* Sound stops when the tab is hidden or the browser is minimized, and comes back when the player returns (item 3.3.5).
* Sound and gameplay stop during every interstitial and rewarded ad and resume after it.
* The mute button works, and its state survives a reload.