Overview

The autoplay directive controls whether <video> and <audio> elements may start playing without a user gesture, or whether HTMLMediaElement.play() may succeed automatically. Its default allowlist is self, so a same-origin document may attempt playback within the browser's own autoplay policy.

Details

`autoplay=*` allows every frame, `autoplay=(self)` restricts to the document's own origin, and `autoplay=()` forbids autoplay entirely. For a cross-origin iframe such as an ad or embedded widget to autoplay, the parent must delegate with `<iframe allow="autoplay">`; without that, media inside the frame can be blocked from autoplaying even when muted.

When the policy denies autoplay, the Promise returned by a play() call made without the muted attribute rejects with a NotAllowedError. This layers on top of, and independently from, the browser's own autoplay heuristics (user activation, media engagement index), so even a permissive policy can still be overridden by those heuristics. It replaces the autoplay feature of the legacy Feature-Policy header.

Syntax

Permissions-Policy: autoplay=(self "https://cdn.example.com")

Notes

• Always handle the play() rejection caused by autoplay blocking with .catch() so the UI does not break; a common pattern is muted autoplay followed by an unmute on user click.
• For embeds like YouTube iframes to autoplay with sound, you must set allow="autoplay" on the frame.

Related directives