HTML <video> 요소는 비디오 콘텐츠를 문서에 삽입할 때 사용합니다. 오디오 콘텐츠도 함께 사용할 수 있지만, <audio>가 좀 더 적합한 사용자 경험을 제공합니다.

불러오는 중...

<video controls width="125">
  <source src="/gen/chestnut.webm" type="video/webm" />
  <source src="/gen/chestnut.mp4" type="video/mp4" />

  죄송합니다. 브라우저가 비디오를 지원하지 않습니다.
</video>

<video></video> 안의 내용은 미지원 브라우저에서 대체 콘텐츠로 보여집니다.

특성

전역 특성을 포함합니다.

autoplay

지정하면 비디오 다운로드가 끝나지 않았더라도 최대한 빠른 시점에 자동으로 재생하는 불리언 특성입니다.

오디오를(또는 오디오를 포함한 비디오)를 자동으로 재생하는 웹 사이트는 사용자 경험에 좋지 않으므로 되도록 피해야 합니다. 반드시 자동으로 재생해야 하는 경우 옵트인(opt-in) 기능, 즉 사용자가 직접 자동재생 기능을 활성화해야 하도록 개발하세요. 다만 미디어 소스를 처음부터 제공하지 않고, 나중에 사용자가 직접 지정하는 경우 autoplay를 유용하게 사용할 수 있습니다.

autopictureinpicture

지정하면 현재 문서에서 포커스가 벗어나 다른 문서, 또는 다른 앱으로 이동할 때 자동으로 PIP(Picture-in-Picture) 모드를 활성화하는 불리언 특성입니다.

controls

지정하면 볼륨, 탐색, 일시정지/재생 등 브라우저가 사용자 컨트롤을 제공하는 불리언 특성입니다.

controlslist

브라우저 내장 컨트롤을 사용할 때(controls 특성을 지정했을 때)의 일부 기능을 조절하는 열거형, 공백 구분 목록 특성입니다. 다음과 같은 값을 사용할 수 있습니다.

  • nodownload: 내장 컨트롤에서 다운로드 컨트롤을 숨겨야 함을 나타냅니다.
  • nofullscreen: 내장 컨트롤에서 전체 화면 컨트롤을 숨겨야 함을 나타냅니다.
  • noremoteplayback: 내장 컨트롤에서 원격 재생 컨트롤을 숨겨야 함을 나타냅니다.
crossorigin

CORS를 사용해 지정한 비디오 파일을 가져올지 나타내는 열거형 특성입니다. CORS 활성화 리소스<canvas> 요소에 사용해도 캔버스가 오염(taint)되지 않습니다. 가능한 값은 다음과 같습니다.

anonymous

자격 증명 없이 교차 출처 요청을 전송합니다. 즉, Origin HTTP 헤더를 쿠키, 인증서, HTTP Basic 인증 없이 전송합니다. 서버에서 Access-Control-Allow-Origin HTTP 헤더를 지정하지 않아서 요청 출처 사이트에 자격 증명을 보내지 않는다면 캔버스 이미지가 오염되고, 사용처가 제한됩니다.

user-credentials

자격 증명과 함께 교차 출처 요청을 전송합니다. 즉, Origin HTTP 헤더를 쿠키, 인증서, 또는 HTTP Basic 인증과 함께 전송합니다. 서버에서 Access-Control-Allow-Origin HTTP 헤더를 지정하지 않아서 요청 출처 사이트에 자격 증명을 보내지 않는다면 캔버스 이미지가 오염되고, 사용처가 제한됩니다.

특성이 존재하지 않으면 리소스를 CORS 요청 없이(Origin HTTP 헤더 없이) 가져오므로, <canvas>가 오염됩니다. 유효하지 않은 값의 경우 anonymous 깂을 사용한 것으로 간주합니다.

disablepictureinpicture

브라우저가 컨텍스트 메뉴에 PIP 모드를 제안하지 않고, 자동으로 PIP를 요청하지도 않도록 지정하는 불리언 특성입니다.

disableremoteplayback

지정하면 유선으로 연결한 장치(HDMI, DVI 등)와 무선 연결 기술(Miracast, Chromecast, DLNA, AirPlay 등)을 통한 오디오 원격 재생을 할 수 없는 불리언 특성입니다. 제안된 명세를 방문해 자세한 정보를 알아보세요.

height

비디오를 표시할 영역의 높이입니다. 픽셀 단위이며, 단위 없는 정수 값을 지정해야 합니다.

loop

지정하면 비디오를 끝까지 재생했을 때 다시 처음으로 돌아가서 재생을 이어갑니다.

muted

지정하면 비디오의 초기 상태를 음소거로 설정하는 불리언 특성입니다.

playsinline

비디오를 전체 화면이나 별도의 크기 조절 가능한 창에서 재생하지 않고, <video> 요소의 표시 영역 내에서 재생함을 나타내는 불리언 특성입니다.

playsinline의 부재가 동영상의 자동 전체 화면 재생을 의미하는 것은 아닙니다. 특히, 대다수의 사용자 에이전트에서 기본으로 인라인 재생을 택하고 있으므로, 일반적인 경우에는 playsinline을 지정해도, 지정하지 않아도 아무 변화가 없습니다.

poster

비디오를 다운로드하는 동안 보여줄 이미지의 URL입니다. 지정하지 않으면 비디오의 첫 번째 프레임을 사용하는데, 첫 번째 프레임를 하기 전에는 전에는 아무것도 보여주지 않습니다.

preload

최적의 사용자 경험을 제공하기 위해 미리 불러올 비디오 데이터에 대한 힌트를 브라우저에 제공하는 열거형 특성입니다. 가능한 값은 다음과 같습니다.

  • none: 비디오를 미리 불러오지 않습니다.
  • metadata: 길이 등 비디오 메타데이터만 미리 불러오도록 지정합니다.
  • auto: 사용자가 비디오를 재생할 것으로 예상하지 않더라도 전체 비디오 파일을 미리 불러옵니다.
  • 빈 문자열: auto와 같습니다.

기본값은 브라우저마다 다르나, 명세는 metadata를 추천합니다.

  • autoplay 특성이 preload보다 우선합니다. autoplay를 지정한 경우 당연히 브라우저는 전체 비디오를 다운로드해야 합니다.
  • preload 특성은 어디까지나 힌트 특성으로, 브라우저가 반드시 따라야 하는 것은 아닙니다.
src

삽입할 비디오의 URL입니다. HTTP 접근 제어의 대상입니다. <source> 요소를 사용하면 지정하지 않아도 됩니다.

width

비디오를 표시할 영역의 너비입니다. 픽셀 단위이며, 단위 없는 정수 값을 지정해야 합니다.

사용 일람

브라우저가 지원하는 파일 유형과 비디오 코덱은 서로 다릅니다. <source> 요소를 추가해서 다수의 소스를 제공하면 브라우저가 이해할 수 있는 첫 번째 소스를 자동으로 사용하므로 지원 범위를 넓힐 수 있습니다.

<audio controls>
  <source src="video.webm" type="video/webm" />
  <source src="video.mp4" type="video/mp4" />
  <p>
    브라우저가 HTML 비디오를 지원하지 않습니다. <a href="video.mp4">비디오 파일 링크</a>
    를 대신 사용하세요.
  </p>
</audio>
  • controls 특성을 지정하지 않으면 비디오 플레이어가 브라우저 기본 컨트롤을 제공하지 않습니다. 대신 JavaScript와 HTMLMediaElement API를 사용해서 컨트롤을 직접 구현할 수 있습니다.
  • 비디오 콘텐츠를 세밀하게 통제할 수 있도록, HTMLMediaElement에서는 여러가지 다양한 이벤트가 발생합니다. 오류 발생 여부와 함께, 비디오를 재생 또는 조작하기에 충분히 불러온 순간도 알아낼 수 있습니다.
  • <video> 프레임의 안에서 영상이 차지하는 위치는 object-position 속성으로 지정할 수 있으며, 영상의 크기는 object-fit 속성을 통해 바꿀 수 있습니다.
  • <video> 요소로도 오디오 콘텐츠를 재생할 수 있습니다. <audio>는 WebVTT 자막을 보여주지 않으므로, 자막을 붙여야 하는 경우 이 사실을 유용하게 활용할 수 있습니다.

CSS 스타일링

<video>대체 요소로, display의 기본값이 inline이지만 그 크기는 마치 inline-block인 것처럼 삽입한 비디오의 내재된 크기가 결정합니다.

<video> 스타일링에는 특별히 고려해야 할 사항은 없지만, 위치와 크기를 쉽게 잡을 수 있도록 displayblock으로 지정하곤 합니다.

트랙 추가/제거 감지하기

<video> 요소에 트랙이 추가되거나 제거되는 것은 addtrackremovetrack 이벤트로 감지할 수 있습니다. 그런데 이 두 종류의 이벤트는 <video> 요소에서 직접 발생하는 것이 아니라 <video>HTMLMediaElementvideoTracks 트랙 리스트 객체에서 발생합니다.

예를 들어, <video> 요소에 트랙이 추가되거나 제거될 때를 감지하는 코드는 다음과 같이 작성할 수 있습니다.

const elem = document.querySelector('video')

elem.videoTracks.addEventListener('addtrack', (event) => {
  console.log('추가함:', event.track)
})

elem.videoTracks.addEventListener('removetrack', (event) => {
  console.log('제거함:', event.track)
})

위의 코드는 트랙의 추가와 제거 이벤트를 수신하다가, 감지하면 콘솔에 기록합니다.

예제

<source>를 사용한 <video>

이 예제는 오디오 소스를 <video>에 직접 지정하지 않고, 내부 <source> 요소의 src 특성에 지정합니다. 항상 파일의 MIME 유형을 지정해서 브라우저가 재생 가능 여부를 알아내느라 시간을 낭비하지 않도록 하는 것이 좋습니다.

<video controls>
  <source src="foo.mp4" type="video/mp4" />
</video>

다수의 <source>를 사용한 <video>

이 예제는 다수의 <source>를 사용해 소스를 제공합니다. 브라우저가 첫 소스 파일(WebM)을 재생할 수 있으면 그걸 불러오고, 그렇지 않으면 두 번째(MP4), 마지막으로 AVI를 불러옵니다.

<video controls>
  <source src="foo.webm" type="video/webm" />
  <source src="foo.mp4" type="video/mp4" />
  <source src="foo.avi" type="video/avi" />
</video>

접근성 고려사항

발화를 포함하는 오디오는 콘텐츠를 정확히 설명하는 자막과 녹취록 모두 포함해야 합니다. WebVTT로 지정하는 자막은 청각이 저하된 사용자가 오디오 콘텐츠를 재생하면서 실시간으로 알 수 있고, 녹취록은 콘텐츠를 이해하는데 시간이 필요한 사용자가 익숙한 형식과 원하는 속도로 천천히 읽어볼 수 있습니다.

또한 음성만 있고 영상이 없는 미디어라도, <video> 요소에서 재생하면 영상 영역에 WebVTT 자막을 보여줄 수 있다는 점을 기억해두면 좋습니다. <audio>는 자막을 보여줄 영역이 없으므로, 이런 상황은 <video>가 오디오를 재생하는 몇 안되는 특별한 경우입니다.

자동 자막 생성 서비스를 사용한 경우 내용을 읽어보고 틀림이 없는지 확인해야 합니다.

발화 내용 외에도, 자막과 녹취록은 중요한 정보를 포함하는 음악과 소리 효과, 감정과 분위기 등을 포함해야 합니다. 아래의 WebVTT 예제를 보면 대괄호를 사용해서 독자가 분위기를 알 수 있도록 돕고 있습니다. 이렇게 청각적 콘텐츠에서 음악, 비언어적 소리와 중요한 소리 효과를 통해 조성하는 분위기를 텍스트로도 만들 수 있습니다.

1
00:00:00 --> 00:00:45
[밝은 테크노 음악]

2
00:00:46 --> 00:00:51
타임키퍼의 팟캐스트에 오신 것을 환영합니다! 이번 에피소드에서는 어떤 스위스 시계가 손목시계인지 알아보겠습니다!

16
00:00:52 --> 00:01:02
[웃음] 아, 죄송해요! 그러니까, 어떤 손목시계가 스위스 손목시계일까요?

명세

HTML Living Standard

브라우저 호환성

IEEdgeChromeSafariFirefox
91233.13.5
iOS SafariAndroid WebViewAndroid ChromeAndroid FirefoxSamsung Internet
3지원지원4지원
Aspect ratio computed from width and height attributes
IEEdgeChromeSafariFirefox
미지원79791471*
iOS SafariAndroid WebViewAndroid ChromeAndroid FirefoxSamsung Internet
1479797912.0
autoplay
IEEdgeChromeSafariFirefox
91233.13.5
iOS SafariAndroid WebViewAndroid ChromeAndroid FirefoxSamsung Internet
10*지원지원4지원
controls
IEEdgeChromeSafariFirefox
91233.13.5
iOS SafariAndroid WebViewAndroid ChromeAndroid FirefoxSamsung Internet
3지원지원4지원
crossorigin
IEEdgeChromeSafariFirefox
?≤18??74*
iOS SafariAndroid WebViewAndroid ChromeAndroid FirefoxSamsung Internet
???79*?
height
IEEdgeChromeSafariFirefox
91233.13.5
iOS SafariAndroid WebViewAndroid ChromeAndroid FirefoxSamsung Internet
3지원지원4지원
loop
IEEdgeChromeSafariFirefox
91233.111
iOS SafariAndroid WebViewAndroid ChromeAndroid FirefoxSamsung Internet
6지원지원14지원
muted
IEEdgeChromeSafariFirefox
101230511
iOS SafariAndroid WebViewAndroid ChromeAndroid FirefoxSamsung Internet
?지원지원14지원
played
IEEdgeChromeSafariFirefox
?≤18??15
iOS SafariAndroid WebViewAndroid ChromeAndroid FirefoxSamsung Internet
???15?
poster
IEEdgeChromeSafariFirefox
91233.13.6
iOS SafariAndroid WebViewAndroid ChromeAndroid FirefoxSamsung Internet
3지원지원4지원
preload
IEEdgeChromeSafariFirefox
9123*3.14
iOS SafariAndroid WebViewAndroid ChromeAndroid FirefoxSamsung Internet
3지원*지원*4지원*
src
IEEdgeChromeSafariFirefox
91233.13.5
iOS SafariAndroid WebViewAndroid ChromeAndroid FirefoxSamsung Internet
3지원지원4지원
width
IEEdgeChromeSafariFirefox
91233.13.5
iOS SafariAndroid WebViewAndroid ChromeAndroid FirefoxSamsung Internet
3지원지원4지원
MDN BCD에서 가져오는 데이터입니다.

같이 보기

마지막 업데이트:
이 페이지를 오프라인에서 볼 수 있습니다.

sorto.me

CC BY-SA 4.0

based on MDN (contributors)