HTMLMediaElement

HTMLMediaElement 는 오디오와 비디오에 통용되는 미디어 관련 확장성을 제공하기 위해 HTMLElement에 메소드와 프로퍼티를 추가한 인터페이스입니다. HTMLVideoElement 와 HTMLAudioElement (en-US) 는 이 인터페이스를 상속합니다.

속성(Properties)

이 인터페이스는 HTMLElement, Element (en-US), Node (en-US), and EventTarget의 프로퍼티들도 모두 상속합니다.

HTMLMediaElement.audioTracks (en-US): AudioTrackList (en-US)는 엘레먼트의 AudioTrack (en-US) 객체의 목록입니다.
HTMLMediaElement.autoplay: 미디어가 준비된 즉시 재생할 것인지 결정하는 autoplay 속성에 연결된 Boolean값입니다..> 참고: 오디오(또는 오디오가 있는 비디오)를 자동으로 재생하는 사이트는 사용자에게 그리 탐탁치 않은 경험일 수 있습니다, 그러므로 가능한 한 지양해야합니다. 자동 재생 기능을 제공하려면, 사전 동의(사용자에게 기능을 켜도록 함)를 받아야 합니다. 의외로 이 점은 사용자의 조작에 의해 미디어 엘레먼츠를 늦게 생성하는 경우 유용할 수 있습니다.
HTMLMediaElement.buffered (en-US) 읽기 전용: buffered 프로퍼티에 접근한 시점에 브라우저가 버퍼에 담고 있는 미디어 소스의 구간 데이터를 나타내는 TimeRanges (en-US) 객체를 반환합니다.
HTMLMediaElement.controller (en-US): 미디어 엘레먼트에 할당된 MediaController 객체를 반환하거나 없다면 null을 반환합니다.
HTMLMediaElement.controls (en-US): 미디어 엘레먼트에 컨트롤를 표시할지 결정하는 controls HTML 속성 값을 Boolean으로 반환합니다.
HTMLMediaElement.controlsList (en-US) 읽기 전용: 브라우저가 미디어 엘레먼트에 자체 컨트롤을 표시할 때 어떤 컨트롤을 보여주거나 숨길 지 결정하는 DOMTokenList (en-US)를 반환합니다. DOMTokenList 는 nodownload, nofullscreen, noremoteplayback 값을 가질 수 있습니다.
HTMLMediaElement.crossOrigin (en-US): DOMString미디어 엘레먼트의 CORS 설정 (en-US)값을 반환합니다.
HTMLMediaElement.currentSrc 읽기 전용: 현재 선택된 미디어 소스 URL의 절대 경로를 DOMString로 반환합니다.
HTMLMediaElement.currentTime: 현재 재생 시점을 초 단위로 표현한 double값입니다. 이 값을 세팅하여 재생 시점을 변경할 수 있습니다.
HTMLMediaElement.defaultMuted (en-US): Boolean 기본적으로 음소거 상태인지 표시하는 muted HTML 속성 값을 Boolean으로 반환합니다.
HTMLMediaElement.defaultPlaybackRate (en-US): 미디어 기본 재생 배속을 double 값으로 반환합니다.
HTMLMediaElement.disableRemotePlayback (en-US): Is a Boolean that sets or returns the remote playback state, indicating whether the media element is allowed to have a remote playback UI.
HTMLMediaElement.duration 읽기 전용: 미디어의 전체 길이를 초 단위로 double 값으로 반환합니다. 재생 가능한 미디어가 없을 경우 0을 반환합니다.
HTMLMediaElement.ended (en-US) 읽기 전용: 미디어 재생 완료 여부를 Boolean 값으로 반환합니다.
HTMLMediaElement.error (en-US) 읽기 전용: 마지막으로 발생한 MediaError (en-US) 객체를 반환합니다. 발생한 에러가 없을 경우 null을 반환합니다.
HTMLMediaElement.loop (en-US): 미디어의 반복 재생을 결정하는 HTML 속성 loop 값을Boolean으로 반환합니다.
HTMLMediaElement.mediaGroup (en-US): 미디어가 속한 그룹을 나타내는 mediagroup 속성을 DOMString 값으로 반환합니다. 같은 그룹에 속한 미디어들은 동일한 MediaController에 의해 제어됩니다.
HTMLMediaElement.mediaKeys (en-US) 읽기 전용 Experimental: MediaKeys (en-US) 객체 또는 null을 반환합니다. MediaKeys는 재생할 미디어 데이터를 복호화 하는데 사용합니다.
HTMLMediaElement.mozAudioCaptured 읽기 전용 비표준: 오디오 스트림 캡쳐 여부를 Boolean 값으로 반환합니다. (Mozilla 전용 비표준 속성.)
HTMLMediaElement.mozFragmentEnd 비표준: MediaElement의 currentSrc에 fragment URI가 존재하는 경우 fragment end time을 double 값으로 반환합니다. 없을 경우 미디어 길이를 반환합니다. (Mozilla 전용 비표준 속성)
HTMLMediaElement.mozFrameBufferLength 비표준 지원이 중단되었습니다: MozAudioAvailable 이벤트 발생시마다 반환된 framebuffer의 샘플 숫자를 unsigned long 로 반환한다. 이 숫자는 모든 오디오 채널의 총합이며, 기본값은 채널 수 * 1024(예, 2 채널 * 1024 샘플 = 2048)이다.레이턴시가 낮은 경우 mozFrameBufferLength 를 더 큰 값으로 지정할 수도 있습니다. 범위는 512에서 16384 사이입니다. 범위를 넘어서는 값은 Error를 발생시킵니다. loadedmetadata (en-US) 이벤트가 발생할 때 새 값을 지정하는 것이 적절합니다. 오디오 정보는 알고 있지만 재생 시작 전 또는 MozAudioAvailable 이벤트가 발생하기 전 시점이죠.
HTMLMediaElement.mozSampleRate 읽기 전용 비표준 지원이 중단되었습니다: 디지털 샘플링 주파수 값을 double로 반환합니다. 예를 들어 CD 오디오의 경우 초당 44100 샘플을 가집니다.
HTMLMediaElement.muted (en-US): 오디오 음소거 여부를 Boolean 값으로 반환합니다. 음소거라면 true 반대는 false 를 반환합니다..
HTMLMediaElement.networkState 읽기 전용: 네트워크를 통한 미디어 데이터 전송 상태를 unsigned short (enumeration)으로 반환합니다.
HTMLMediaElement.paused (en-US) 읽기 전용: 미디어 일시 정지 여부를 Boolean 값으로 반환합니다.
HTMLMediaElement.playbackRate: 재생 속도를 double 값으로 반환합니다.
HTMLMediaElement.played 읽기 전용: 브라우저에서 재생된 미디어 소스 범위를 포함한 TimeRanges (en-US) 객체를 반환합니다.
HTMLMediaElement.preload: 프리로드 할 데이터 타입을 명시하는 preload attribute를 DOMString 값으로 반환한다. 가능한 값들 : none, metadata, auto.
HTMLMediaElement.preservesPitch (en-US) 비표준: 사운드 피치 유지 여부를 Boolean 값으로 반환합니다. false 일 경우, 오디오 재생 속도에 따라 변하게 됩니다. Firefox의 (mozPreservesPitch)와 WebKit의 (webkitPreservesPitch)로 구현되어 있습니다.
HTMLMediaElement.readyState 읽기 전용: 미디어 대기 상태를 unsigned short (enumeration)으로 반환합니다.
HTMLMediaElement.seekable 읽기 전용: 탐색(seeking) 가능한 범위를 포함한 TimeRanges (en-US) 객체를 반환합니다.
HTMLMediaElement.seeking 읽기 전용: 탐색(seeking) 중 여부를 Boolean 값으로 반환합니다.
HTMLMediaElement.sinkId (en-US) 읽기 전용 Experimental: 별도의 오디오 재생 장치로 출력중이라면 장치의 unique ID를 DOMString 으로 반환합니다. 브라우저로 재생 중이라면 빈 문자열입니다. 이 ID는 MediaDevices.enumerateDevices()에서 반환된 MediaDeviceInfo.deviceid, id-multimedia, id-communications 중 하나입니다.
HTMLMediaElement.src: 미디어 리소스 URL이 포함된 src attribute를 DOMString 값으로 반환합니다.
HTMLMediaElement.srcObject: 현재 HTMLMediaElement 객체에서 재생 중이거나 재생 되었던 미디어를 표현하는 MediaStream (en-US) 객체를 반환합니다. 없는 경우, null 을 반환합니다.
HTMLMediaElement.textTracks (en-US) 읽기 전용: TextTrack (en-US) 리스트를 반환합니다.
HTMLMediaElement.videoTracks (en-US) 읽기 전용: VideoTrack (en-US) 리스트를 반환합니다..> 참고: Gecko는 싱글 트랙 재생만을 지원합니다. 또한 트랙 메타데이터 파싱은 Ogg 컨테이너 포맷에서만 가능합니다..
HTMLMediaElement.volume (en-US): 오디오 볼륨을 double 값으로 반환합니다. 0.0 (무음)에서 1.0 (최대크기) 사이 값을 가집니다..

이벤트 핸들러(Event handlers)

HTMLMediaElement.onencrypted (en-US): 미디어 암호화 시 호출되는 EventHandler (en-US)를 설정합니다.
HTMLMediaElement.onwaitingforkey (en-US): 재생하기 위해 복호화 키가 필요한 경우 호출되는 EventHandler (en-US)를 설정합니다..

폐기된 속성(Obsolete attributes)

아래 속성들은 폐기되었으며 브라우저가 지원하더라도 사용되지 않아야 합니다.

HTMLMediaElement.initialTime 읽기 전용 비표준 지원이 중단되었습니다: 최초 재생 지점을 초 단위로 double 값으로 반환합니다.
HTMLMediaElement.mozChannels 읽기 전용 비표준 지원이 중단되었습니다: 오디오 채널 수를 double 값으로 반환합니다. (예, 스테레오인 경우 2).

폐기된 이벤트 핸들러(Obsolete event handlers)

HTMLMediaElement.onmozinterruptbegin 비표준 지원이 중단되었습니다: Audio Channel manager에 의해 재생이 인터럽트 된 경우 호출되는 event handler 를 설정합니다. Firefox 전용 기능으로 Firefox OS에서 추가되었으며 Firefox 55 버전에서 제거되었습니다.
HTMLMediaElement.onmozinterruptend 비표준 지원이 중단되었습니다: 재생 인터럽트가 해결된 경우 호출되는 EventHandler (en-US)를 설정합니다. Firefox 전용 기능으로 Firefox OS에서 추가되었으며 Firefox 55 버전에서 제거되었습니다.

메소드

This interface also inherits methods from its ancestors HTMLElement, Element (en-US), Node (en-US), and EventTarget.

HTMLMediaElement.addTextTrack(): 미디어 엘리먼트에 본문 트랙(자막 등)을 추가합니다.
HTMLMediaElement.captureStream() (en-US) Experimental: 미디어 콘텐트의 스트림을 캡쳐하여 MediaStream (en-US) 객체로 반환합니다.
HTMLMediaElement.canPlayType() (en-US): 현재 지정된 미디어 타입을 재생할 수 있는지 확인합니다.
HTMLMediaElement.fastSeek() (en-US): 입력된 시간으로 바로 이동합니다.
HTMLMediaElement.load() (en-US): 미디어를 처음으로 리셋하고 src 어트리뷰트 또는 <source> (en-US) 엘리먼트로 전달된 소스 중 최적의 소스를 선택합니다.
HTMLMediaElement.mozCaptureStream() 비표준: [enter description]
HTMLMediaElement.mozCaptureStreamUntilEnded() 비표준: [enter description]
HTMLMediaElement.mozGetMetadata() 비표준: Returns Object, which contains properties that represent metadata from the playing media resource as {key: value} pairs. A separate copy of the data is returned each time the method is called. This method must be called after the loadedmetadata (en-US) event fires.
HTMLMediaElement.pause() (en-US): 미디어 재생을 일시 정지합니다.
HTMLMediaElement.play() (en-US): 미디어를 재생합니다.
HTMLMediaElement.seekToNextFrame() (en-US) 비표준 Experimental: 미디어의 다음 프레임으로 이동합니다. 비표준이며 실험적인 이 기능은 미디어를 읽고 렌더링 하는 속도를 조절할 수 있게 하거나 프레임별로 필터링 등 추가적인 기능을 수행할 수 있게 합니다.
HTMLMediaElement.setMediaKeys() (en-US) Experimental: 미디어 복호화에 필요한 키를 지정합니다. Promise 객체를 반환합니다.
HTMLMediaElement.setSinkId() (en-US) Experimental: 오디오를 출력할 장치의 ID를 지정합니다. Promise 객체를 반환합니다. 어플리케이션이 특정 장치를 사용할 수 있는 경우에만 동작합니다.

폐기된 메소드

아래 메소드들은 폐기되었습니다. 브라우저가 지원하더라도 사용하면 안됩니다.

HTMLMediaElement.mozLoadFrom() 비표준 지원이 중단되었습니다: Mozilla 구현체에서만 동작하는 이 메소드는 다른 미디어 엘리먼트에서 데이터를 로드합니다. load() 메소드와 유사하게 동작하지만 리소스 선택 알고리즘만 다릅니다. 엘리먼트의 소스를 다른 엘리먼트의 currentSrc를 바라보게 합니다. 지정된 엘리먼트의 캐시 및 버퍼에 담긴 데이터에도 모두 접근할 수 있으며 이 말은 즉 다운로드 된 모든 데이터를 공유한다는 의미입니다.

이벤트

부모 엘리먼트 HTMLElement에서 상속받은 이벤트와 GlobalEventHandlers에 정의된 이벤트를 믹스인합니다. addEventListener()를 통해 이벤트를 수신하거나 oneventname 프로퍼티에 리스터를 할당하여 수신합니다.

abort: 에러 외의 원인으로 전체 리소스가 로드 되지 못했을 때 발생합니다.
canplay: User agent가 미디어를 재생 가능한 시점에 발생합니다. 다만 전체 미디어를 재생하기 위해서는 콘텐츠의 버퍼링이 더 필요할 수 있습니다.
canplaythrough: 추가 버퍼링 없이 전체 미디어를 재생할 수 있는 시점에 발생합니다.
durationchange (en-US): duration 속성이 변경된 시점에 발생합니다..
emptied (en-US): 미디어가 제거된 시점에 발생합니다. 예를 들어 미디어가 이미 (부분적으로라도) 로드 되었는데. HTMLMediaElement.load() (en-US) 메소드 호출로 재 로드할 경우 발생합니다.
ended (en-US): (<audio> or <video>) 미디어가 끝까지 재생 완료 된 시점에 발생합니다.
error (en-US): 에러가 발생하여 리소스를 로드할 수 없는 시점에 발생합니다.
loadeddata (en-US): 미디어의 첫번째 프레임이 로딩 완료된 시점에 발생합니다.
loadedmetadata (en-US): 메타데이터가 로드 된 시점에 발생합니다.
loadstart (en-US): 브라우저가 리소스를 로드하기 시작하는 시점에 발생합니다.
pause (en-US): 미디어 일시 정지를 요청하고 paused 상태로 진입하는 시점에 발생합니다. 일반적으로 HTMLMediaElement.pause() (en-US) 메소드가 호출되는 시점입니다.
play (en-US): HTMLMediaElement.play() (en-US) 메소드 호출이나 autoplay 속성에 의해 paused 프로퍼티가 true 에서 false로 전환되는 시점에 발생합니다.
playing (en-US): 일시 정지 되거나 버퍼 부족으로 재생 정지 된 이후 재생 가능한 시점에 발생합니다.
progress (en-US): 브라우저가 리소르를 로딩 중일 때 주기적으로 발생합니다.
ratechange (en-US): 재생 속도가 변경될 때 발생합니다.
seeked (en-US): 미디어 시킹이 완료되는 시점에 발생합니다.
seeking (en-US): 미디어 시킹이 시작되는 시점에 발생합니다.
stalled (en-US): User agent가 미디어 데이터를 fetch 하였지만 전송되지 않은 경우 발생합니다.
suspend (en-US): 미디어 로딩이 중지된 시점에 발생합니다.
timeupdate (en-US): currentTime 속성이 변경되는 시점에 발생합니다.
volumechange (en-US): 볼륨이 변경되는 시점에 발생합니다.
waiting (en-US): 일시적인 버퍼 부족으로 재생이 정지된 시점에 발생합니다.

명세

Specification
HTML Standard # htmlmediaelement

브라우저 호환성

BCD tables only load in the browser

같이 보기

참고 자료
- <video> and <audio> (en-US) HTML elements.
- HTMLVideoElement and HTMLAudioElement (en-US) interfaces, derived from HTMLMediaElement.
문서