HTMLMediaElement

Baseline Widely available *

This feature is well established and works across many devices and browser versions. It’s been available across browsers since ⁨2015年7月⁩.

* Some parts of this feature may have varying levels of support.

HTMLMediaElement インターフェイスは、HTMLElement に音声や動画で一般的なメディアに関する基本的な能力の対応に必要なプロパティやメソッドを追加します。

HTMLVideoElement およびHTMLAudioElement 要素はどちらも、このインターフェイスを継承しています。

プロパティ

このインターフェイスは祖先であるHTMLElement,Element,Node,EventTarget のプロパティを継承しています。

HTMLMediaElement.audioTracks: AudioTrackList で、この要素に含まれるAudioTrack オブジェクトを列挙します。
HTMLMediaElement.autoplay: 論理値で、 HTML のautoplay 属性の値を反映し、中断なしに再生できるだけの十分なデータが揃った時点で自動的に再生を始めるかどうかを示します。
メモ:ユーザーが期待していない、あるいは望んでいないときに自動的に音声を再生すると、ユーザーに不快な体験をさせることになるため、ほとんどの場合避けるべきですが、例外も存在します。詳しくは、メディアとウェブオーディオ API のガイドを参照してください。ブラウザーは自動再生要求を無視する可能性があることを念頭に置き、コードが自動再生の動作に依存していないことを確認する必要があります。
HTMLMediaElement.buffered読取専用: buffered プロパティにアクセスした時点で、ブラウザーがバッファリングしているメディアソースの範囲を（もしあれば）TimeRanges オブジェクトで返します。
HTMLMediaElement.controls: 論理値で、 HTML のcontrols 属性を反映し、リソースを制御するユーザーインターフェイス項目を表示するかどうかを示します。
HTMLMediaElement.controlsList: ユーザーエージェントが独自のコントロールのセットを表示するたびに、メディア要素に表示するコントロールをユーザーエージェントが選択するのに役立つDOMTokenList を返します。DOMTokenListは、nodownload、nofullscreen、noremoteplaybackの 3 つの値のうち 1 つ以上を取ります。
HTMLMediaElement.crossOrigin: 文字列で、このメディア要素のCORS 設定を示します。
HTMLMediaElement.currentSrc読取専用: 文字列で、選択されたメディアリソースの絶対 URL を返します。
HTMLMediaElement.currentTime: 倍精度浮動小数点値で、現在の再生時刻を秒単位で示します。メディアの再生が開始されておらず、シークも行われていない場合、この値はメディアの初期再生時刻となります。この値を設定すると、メディアは新しい時刻にシークされます。この時間は、メディアのタイムラインに対して相対的に指定されます。
HTMLMediaElement.defaultMuted: 論理値で、HTML のmuted 属性を反映します。標準状態で音声がミュートされているか、いないかを示します。
HTMLMediaElement.defaultPlaybackRate: double で、メディアの既定の再生速度を示します。
HTMLMediaElement.disableRemotePlayback: 論理値で、リモート再生の状態を設定または返却します。メディア要素にリモート再生 UI が許可されているかどうかを示します。
HTMLMediaElement.duration読取専用: 読み取り専用の倍精度浮動小数点値で、メディアの総時間を秒単位で示します。メディアデータがない場合、返値はNaN となります。メディアの長さが不定（ライブストリーミングメディアや WebRTC 呼び出しのメディアなど）の場合、値は+Infinity となります。
HTMLMediaElement.ended読取専用: メディア要素の再生が終了したかどうかを示す論理値を返します。
HTMLMediaElement.error読取専用: 直近のエラーに対応するMediaError オブジェクトを返すか、エラーが発生していない場合はnull を返します。
HTMLMediaElement.loop: 論理型で、 HTML のloop 属性を反映し、末尾に達したときにメディア要素が再び再生を始めるかどうかを示します。
HTMLMediaElement.mediaKeys読取専用安全なコンテキスト用: MediaKeys オブジェクトで、再生中にその要素がメディアデータを復号するために使用することができる一連のキーを返します。利用できるキーがない場合はnull となります。
HTMLMediaElement.muted: 音声がミュートされているかどうかを判断するための論理値です。ミュートされている場合はtrue で、そうでない場合はfalse となります。
HTMLMediaElement.networkState読取専用: ネットワーク経由でメディアを取得する際の現在の状態を示すunsigned short （列挙値）を返します。
HTMLMediaElement.paused読取専用: 論理値で、メディア要素が一時停止中であるか否かを示します。
HTMLMediaElement.playbackRate: double で、メディアの再生レートを示します。
HTMLMediaElement.played読取専用: ブラウザーが再生したメディアソースの範囲を含むTimeRanges オブジェクトを返します（もしあれば）。
HTMLMediaElement.preload: HTML のpreload 属性を反映した文字列で、どのデータを先読みすべきかを示します。取りうる値はnone,metadata,auto です。
HTMLMediaElement.preservesPitch: 音のピッチを保持するかどうかを決定する論理値です。false に設定すると、ピッチは音声の速度に合わせられます。
HTMLMediaElement.readyState読取専用: メディアの準備状態を示すunsigned short （列挙値）を返します。
HTMLMediaElement.remote読取専用: このメディア要素に関連付けられたRemotePlayback オブジェクトインスタンスを返します。
HTMLMediaElement.seekable読取専用: ユーザーがシークできる時間帯があれば、それを含むTimeRanges オブジェクトを返します。
HTMLMediaElement.seeking読取専用: メディアが新しい位置へのシーク中であるかどうかを論理値で返します。
HTMLMediaElement.sinkId読取専用安全なコンテキスト用: 出力する音声機器の固有の ID を文字列で返します。ユーザーエージェントの既定の音声機器を使用している場合は、空文字列を返します。
HTMLMediaElement.src: 使用するメディアリソースの URL を記した HTML のsrc 属性を反映した文字列です。
HTMLMediaElement.srcObject: このHTMLMediaElement に関連付けられたメディアのソースとなるオブジェクト、または割り当てられていない場合はnull です。
HTMLMediaElement.textTracks読取専用: TextTrackList オブジェクトで、この要素に含まれるTextTrack オブジェクトのリストを返します。
HTMLMediaElement.videoTracks読取専用: VideoTrackList オブジェクトで、この要素に含まれるVideoTrack オブジェクトのリストを返します。
HTMLMediaElement.volume: double で音声の音量を示します。 0.0 (無音) から 1.0 (最大) の間です。

廃止されたプロパティ

これらのプロパティは廃止されており、たとえブラウザーがまだ対応していても使わないでください。

HTMLMediaElement.controller非推奨;非標準: 要素に割り当てられたメディアコントローラーを表す MediaController オブジェクト、または何も割り当てられていない場合はnull です。
HTMLMediaElement.mediaGroup非推奨;非標準: 所属する要素のグループ名を示す HTML のmediagroup 属性を反映した文字列です。メディア要素のグループは、共通の MediaController を共有します。
HTMLMediaElement.mozAudioCaptured読取専用非標準非推奨;: 論理値を返します。オーディオストリームキャプチャに関連します。
HTMLMediaElement.mozFragmentEnd非標準非推奨;: double で、メディア要素がcurrentSrc のフラグメント URI を持っている場合はフラグメントの終了時刻にアクセスすることができます。それ以外の場合はメディアの再生時間と同じです。

メソッド

このインターフェイスには祖先であるHTMLElement,Element,Node,EventTarget から継承したメソッドもあります。

HTMLMediaElement.addTextTrack(): メディア要素に新しいTextTrack オブジェクト（字幕用トラックなど）を追加します。これはプログラム的なインターフェイスのみで、 DOM には影響しません。
HTMLMediaElement.captureStream(): メディアコンテンツのストリームをキャプチャしてMediaStream 返します。
HTMLMediaElement.canPlayType(): MIME メディア種別を指定する文字列（潜在的にはcodecs 引数も含む）が与えられた場合、canPlayType() は、メディアが再生可能であるべき場合には文字列probably を、メディアが再生されるかどうかを決定するのに十分な情報がない場合にはmaybe を、メディアが再生できない場合には空文字列を返します。
HTMLMediaElement.fastSeek(): 低い精度で素早く指定時刻にシークします。
HTMLMediaElement.load(): メディアを先頭にリセットし、src 属性または<source> 要素を使用して提供されたソースのうちから、最適なソースを選択します。
HTMLMediaElement.pause(): 再生を一時停止します。
HTMLMediaElement.play(): 再生を開始します。
HTMLMediaElement.seekToNextFrame()非推奨;非標準: メディア内の次のフレームをシークします。この非標準的で実験的なメソッドにより、メディアの読み込みとレンダリングをカスタム速度で手動で行ったり、メディアをフレーム単位で移動してフィルタリングやその他の操作を行ったりすることが可能になります。
HTMLMediaElement.setMediaKeys()安全なコンテキスト用: Promise オブジェクトを返します。再生に利用するMediaKeys を指定します。
HTMLMediaElement.setSinkId()安全なコンテキスト用: 出力に使用するオーディオ機器の ID を設定し、Promise を返します。これは、アプリケーションが指定された機器の使用が許可されている場合のみ動作します。

廃止されたメソッド

これらのメソッドは廃止されているため、たとえブラウザーがまだ対応していても使わないでください。

HTMLMediaElement.mozCaptureStream()非標準: Firefox の接頭辞が付いた HTMLMediaElement.captureStream() です。詳細はブラウザーの互換性を参照してください。
HTMLMediaElement.mozCaptureStreamUntilEnded()非標準非推奨;: [説明を入力]
HTMLMediaElement.mozGetMetadata()非標準非推奨;: 再生中のメディアデータに対するメタデータを Object として返します。呼び出すたびに、オブジェクトのコピーが新しく作られます。このメソッドを呼び出すには、loadedmetadata イベントが発行された後でなければなりません。

イベント

親であるHTMLElement からイベントを継承しています。

これらのイベントを待ち受けするには、addEventListener() を使用するか、このインターフェイスのonイベント名 プロパティにイベントリスナーを代入するかしてください。

abort: リソースが完全にロードされておらず、かつその結果がエラーでない場合に発行されます。
canplay: ユーザーエージェントがメディアを再生することはできるが、コンテンツのさらなるバッファリングのために停止することなくメディアを最後まで再生するには十分なデータが読み込まれていないと推定されるときに発行されます。
canplaythrough: ユーザーエージェントがメディアを再生することができ、コンテンツのさらなるバッファリングのために停止することなく、メディアを最後まで再生するのに十分なデータが読み込まれたと推定されるときに発行されます。
durationchange: duration プロパティが更新されたときに発行されます。
emptied: メディアが空になったときに発行されます。例えば、メディアがすでに読み込まれており（または部分的に読み込まれており）、再読み込みのためにHTMLMediaElement.load() メソッドが呼ばれた場合などです。
encrypted: 初期化データがメディア内にあり、メディアが暗号化されていることを示す場合に発生します。
ended: メディア（<audio> または <video>）の終端に到達したとき、またはそれ以降のデータがないために再生が停止したときに発行されます。
error: エラーによりリソースの読み込みができなかった場合に発行されます。
loadeddata: メディアの 1 フレーム目の読み込みが終了した時点で発行されます。
loadedmetadata: メタデータが読み込まれたときに発行されます。
loadstart: ブラウザーがリソースの読み込みを開始したときに発行されます。
pause: 再生を一時停止する要求が処理され、アクティビティが一時停止状態になったときに発行されます。最も一般的には、メディアのHTMLMediaElement.pause() メソッドが呼び出されたときに発行されます。
play: HTMLMediaElement.play() メソッド、またはautoplay 属性の結果として、paused プロパティがtrue からfalse に変更されたときに発行されます。
playing: データ不足で一時停止または遅延していた再生が開始できる状態になったときに発行されます。
progress: ブラウザーがリソースを読み込む際に、定期的に発行されます。
ratechange: 再生速度が変更されたときに発行されます。
seeked: シーク動作が完了したときに発行されます。
seeking: シーク動作が開始されたときに発行されます。
stalled: ユーザーエージェントがメディアデータを取得しようとしたが，予想に反してデータが得られなかった場合に発行されます。
suspend: メディアデータの読み込みが中断されたときに発行されます。
timeupdate: currentTime プロパティで示される時刻が更新されたときに発行されます。
volumechange: 音量が変更されたときに発行されます。
waiting: 一時的なデータ不足で再生が停止したときに発行されます。
waitingforkey: キー待ち中に再生が最初にブロックされたときに発生します。