Knowledge baseExam Center
ENEnglish
Choose language13

CKTIS / JavaScript

HTMLMediaElement.play() — starting playback asynchronously

The play() method requests that audio or video playback start or resume. It returns a Promise, so the interface should account for both playback starting and the request being rejected.

Version: ECMAScript and Web APIs; exact feature edition and browser support reviewed per entry; Node 24 in repository does not prove browser API support

Syntax

media.play() // Promise<undefined>; media is an HTMLAudioElement or HTMLVideoElement

HTMLMediaElement.play() is a browser Web API method for audio and video elements, not an ECMAScript function. It takes no arguments. It returns a Promise that fulfills with undefined when playback starts—not when the media finishes.

Use await media.play() inside try...catch. Neither the call returning nor paused === false confirms that playback has started. The promise may remain pending while data loads; update the interface after it settles.

NotAllowedError means playback is not permitted, for example because of autoplay policy. Call the method directly in a click handler, but still handle refusal. NotSupportedError concerns an unsupported source. Interrupting a pending request through pause() or reloading can cause AbortError.

The example deliberately supplies text instead of a recording to demonstrate rejection handling without an external file. It does not demonstrate successful playback. This API belongs to the HTML Living Standard; Node 24 in a repository does not establish browser availability.

Examples

const media = document.createElement('audio');
media.src = 'data:text/plain,not-media';
const button = document.createElement('button');
button.textContent = 'Test play()';
const status = document.createElement('pre');
document.body.append(button, status);

button.addEventListener('click', async () => {
  button.disabled = true;
  try {
    await media.play();
    status.textContent = 'Playback started';
  } catch (error) {
    status.textContent = `Rejected: ${error.name}`;
  } finally {
    button.disabled = false;
  }
});

Result

Rejected: NotSupportedError

The displayed code and declared result were verified in an isolated environment using the method recorded in the verification evidence for this exact version.

Sources