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 with JavaScript enabled. Enable JavaScript to view data.

같이 보기
-----

* 참고 자료
    + `<video>` and `<audio>` (en-US) HTML elements.
    + `HTMLVideoElement` and `HTMLAudioElement` (en-US) interfaces, derived from `HTMLMediaElement`.
* 문서
    + Using HTML5 audio and video (en-US)
    + Media formats supported by the audio and video elements (en-US)
    + Web Audio API (en-US)