HTMLMediaElement.play()

HTMLMediaElement の play() メソッドは、メディアの再生を開始しようとします。 再生が正常に開始されると解決する Promise を返します。 パーミッションの問題など、何らかの理由で再生を開始しなかった場合、その promise は拒否されます。

構文

var promise = HTMLMediaElement.play();

パラメーター

無し。

戻り値

再生が開始されたときに解決される、または何らかの理由で再生を開始できない場合は拒否される Promise。

例外

promise の拒否ハンドラ（rejection handler）は、その唯一の入力パラメータとして渡された例外名で呼び出されます（従来の例外がスローされるのとは対照的に）。 考えられるエラーは次のとおりです。

NotAllowedError

ユーザーエージェント（ブラウザー）またはオペレーティングシステムは、現在のコンテキストまたはシチュエーションではメディアの再生を許可していません。 これは、例えば、「再生」ボタンをクリックすることによってメディアの再生を明示的に開始することをブラウザーがユーザーに要求する場合に起こり得ます。

NotSupportedError

メディアソース（MediaStream、MediaSource、Blob、File など）はサポートしているメディア形式を表していません。

ブラウザーの実装の詳細、メディアプレーヤーの実装などによっては、他の例外が報告されることがあります。

使用上の注意

「自動再生（autoplay）」という用語は通常、読み込まれるとすぐにメディアの再生を開始するページを指すと考えられていますが、ウェブブラウザーの自動再生ポリシーは、play() の呼び出しを含むスクリプト起動によるメディアの再生にも適用されます。

ユーザーエージェントが自動またはスクリプト起動によるメディアの再生を許可しないように設定されている場合、play() を呼び出すと返された promise が直ちに NotAllowedError で拒否されます。 ウェブサイトはこの状況に対処する準備をしておくべきです。 例えば、サイトには再生が自動的に開始されたことを前提としたユーザーインターフェイスを表示するのではなく、返された promise が解決されたか拒否されたかに基づいて UI を更新する必要があります。 詳しくは、以下の例を参照してください。

自動再生および自動再生のブロックの詳細については、メディアおよびウェブオーディオ API の自動再生ガイドを参照してください。

例

この例では、再生が開始されたことを確認する方法と、ブロックされた自動再生を適切に処理する方法を示します。

let videoElem = document.getElementById("video");
let playButton = document.getElementById("playbutton");

playButton.addEventListener("click", handlePlayButton, false);
playVideo();

async function playVideo() {
  try {
    await videoElem.play();
    playButton.className = "playing";
  } catch(err) {
    playButton.className = "";
  }
}

function handlePlayButton() {
  if (videoElem.paused) {
    playVideo();
  } else {
    videoElem.pause();
    playButton.className = "";
  }
}

この例では、動画の再生は async の playVideo() 関数によってオンとオフを切り替えられます。 動画を再生しようとし、成功した場合は playButton 要素のクラス名を "playing"（再生中）に設定します。 再生が開始されない場合、playButton 要素のクラスはクリアされ、デフォルトの外観に戻ります。 これは、play() によって返された Promise の解決または拒否を監視することによって、再生ボタンが実際の再生状態と一致することを保証します。

この例が実行されると、再生のオンとオフを切り替えるために使用する <button> と同様に <video> 要素への参照を収集することから始めます。 次に、再生トグルボタンの click イベントのイベントハンドラを設定し、playVideo() を呼び出して自動的に再生を開始しようとします。

あなたは Glitch でこの例を試したり、リミックスすることができます。

仕様

ブラウザーの互換性

関連情報

• Web メディア技術
• 学ぶ: 動画と音声のコンテンツ
• メディアおよびウェブオーディオ API の自動再生ガイド
• Web Audio APIの利用