How Howler.js Interacts with document.hidden

This article explains how the Howler.js audio library interacts with the browser’s document.hidden property through the Page Visibility API. By default, Howler.js automatically monitors whether your web page is visible to the user and pauses or mutes audio playback accordingly to save system resources and improve user experience. Below, you will find a clear breakdown of this default behavior, why it matters, and how you can customize or disable it in your web applications.

The Default Interaction: Automatic Muting

By default, Howler.js listens for the browser’s visibilitychange event, which is triggered whenever the value of document.hidden changes.

• When document.hidden is true: If a user switches to another tab, minimizes the browser window, or locks their device screen, the browser sets document.hidden to true. Howler.js detects this change and automatically mutes all active audio globally.
• When document.hidden is false: Once the user returns to the tab, document.hidden becomes false. Howler.js automatically restores the audio volume to its previous state.

This automatic behavior prevents users from being annoyed by unexpected background noise from inactive tabs and helps mobile devices conserve battery and CPU resources.

Controlling the Behavior with autoMute

While automatic muting is ideal for web games and interactive applications, some projects—such as music players or podcast streaming sites—require audio to keep playing even when the tab is in the background.

Howler.js allows you to control this interaction using the global Howler.autoMute property.

// Disable automatic muting when the document is hidden
Howler.autoMute = false;

By setting Howler.autoMute to false, Howler.js will completely ignore the document.hidden state, allowing your audio to play continuously regardless of tab visibility. This configuration must be set globally before or during the initialization of your sound objects.

Browser Limitations and Policy Considerations

Even if you set Howler.autoMute = false, you must still comply with modern browser Autoplay Policies. Browsers require a user interaction (like a click or tap) on the page before any audio can play. If a user opens your page in a background tab without interacting with it first, document.hidden will be true, and the browser will block Howler.js from playing any audio until the user actively visits and clicks on the page.