HTMLMediaElement

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 (en-US) 読取専用: ユーザーエージェントが独自のコントロールのセットを表示するたびに、メディア要素に表示するコントロールをユーザーエージェントが選択するのに役立つ 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 (en-US) オブジェクトを返すか、エラーが発生していない場合は null を返します。
HTMLMediaElement.loop: 論理型で、 HTML の loop 属性を反映し、末尾に達したときにメディア要素が再び再生を始めるかどうかを示します。
HTMLMediaElement.mediaKeys 読取専用 Experimental: MediaKeys (en-US) オブジェクトまたは null を返します。 MediaKeys は、関連付けられた HTMLMediaElement が再生中にメディアデータの復号に使用できるキーのセットです。
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 (en-US): 音のピッチを保持するかどうかを決定する論理値です。 false に設定すると、ピッチは音声の速度に合わせられます。
HTMLMediaElement.readyState 読取専用: メディアの準備状態を示す unsigned short （列挙値）を返します。
HTMLMediaElement.seekable 読取専用: ユーザーがシークできる時間帯があれば、それを含む TimeRanges オブジェクトを返します。
HTMLMediaElement.seeking 読取専用: メディアが新しい位置へのシーク中であるかどうかを論理値で返します。
HTMLMediaElement.sinkId (en-US) 読取専用 Experimental: 出力を配信する音声機器の一意の ID を文字列で返します。ユーザーエージェントの既定値を使用している場合は、空の文字列を返します。この ID は MediaDevices.enumerateDevices() から返される MediaDeviceInfo.deviceid 値、 id-multimedia 値、 id-communications 値のいずれかである必要があります。
HTMLMediaElement.src: 使用するメディアリソースの URL を記した HTML の src 属性を反映した文字列です。
HTMLMediaElement.srcObject: 現在の HTMLMediaElement で再生する、または再生したメディアを表す MediaStream、または割り当てられていない場合は null です。
HTMLMediaElement.textTracks (en-US) 読取専用: TextTrackList (en-US) オブジェクトで、この要素に含まれる TextTrack オブジェクトのリストを返します。
HTMLMediaElement.videoTracks 読取専用: VideoTrackList オブジェクトで、この要素に含まれる VideoTrack オブジェクトのリストを返します。
HTMLMediaElement.volume: double で音声の音量を示します。 0.0 (無音) から 1.0 (最大) の間です。

イベントハンドラー

HTMLMediaElement.onencrypted (en-US): メディアが暗号化されたときに呼び出されるイベントハンドラーを設定します。
HTMLMediaElement.onwaitingforkey (en-US): 暗号化キー待ちで再生がブロックされたときに呼び出されるイベントハンドラーを設定します。

廃止されたプロパティ

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

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

メソッド

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

HTMLMediaElement.addTextTrack(): メディア要素に新しい TextTrack オブジェクト（字幕用トラックなど）を追加します。これはプログラム的なインターフェイスのみで、 DOM には影響しません。
HTMLMediaElement.captureStream() Experimental: メディアコンテンツのストリームをキャプチャして MediaStream 返します。
HTMLMediaElement.canPlayType(): MIME メディア種別を指定する文字列（潜在的には codecs 引数 (en-US)も含む）が与えられた場合、 canPlayType() は、メディアが再生可能であるべき場合には文字列 probably を、メディアが再生されるかどうかを決定するのに十分な情報がない場合には maybe を、メディアが再生できない場合には空文字列を返します。
HTMLMediaElement.fastSeek(): 低い精度で素早く指定時刻にシークします。
HTMLMediaElement.load(): メディア要素をリセットし、メディアリソースをリスタートします。処理されなかったイベントは破棄されます。メディアデータがダウンロードされる量は preload 属性の値に影響されます。src 属性の値、もしくは source 要素内の要素を削除した際のリソース解放、もしくは source の子要素が動的に変更される場合の再スキャンのために利用します。それ以外の場合に呼びだす必要はありません。
HTMLMediaElement.pause(): 再生を一時停止します。
HTMLMediaElement.play(): 再生を開始します。
HTMLMediaElement.seekToNextFrame() (en-US) Non-standard Experimental Deprecated: メディア内の次のフレームをシークします。この非標準的で実験的なメソッドにより、メディアの読み込みとレンダリングをカスタム速度で手動で行ったり、メディアをフレーム単位で移動してフィルタリングやその他の操作を行ったりすることが可能になります。
HTMLMediaElement.setMediaKeys() (en-US) Experimental: 再生に利用するMediaKeys (en-US) を指定します。Promise オブジェクトを返します。
HTMLMediaElement.setSinkId() (en-US) Experimental: 出力に使用するオーディオ機器の ID を設定し、Promise を返します。これは、アプリケーションが指定された機器の使用が許可されている場合のみ動作します。

廃止されたメソッド

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

HTMLMediaElement.mozCaptureStream() Non-standard: [説明を入力]
HTMLMediaElement.mozCaptureStreamUntilEnded() Non-standard Deprecated: [説明を入力]
HTMLMediaElement.mozGetMetadata() Non-standard: 再生中のメディアデータに対するメタデータを Object として返します。呼び出すたびに、オブジェクトのコピーが新しく作られます。このメソッドを呼び出すには、loadedmetadata イベントが発行された後でなければなりません。

イベント

親である HTMLElement や、 GlobalEventHandlers ミックスインから継承したメソッドがあります。これらのイベントを待ち受けするには、 addEventListener() を使用するか、このインターフェイスの onイベント名 プロパティにイベントリスナーを代入するかしてください。

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

仕様書

Specification
HTML Standard # htmlmediaelement

ブラウザーの互換性

BCD tables only load in the browser