VideoCtrls 클래스 문서

개요

VideoCtrls 클래스는 HLS.js를 지원하는 HTML5 비디오 요소를 관리하는 JavaScript/TypeScript 기반의 비디오 플레이어 컨트롤러입니다. 재생/일시 정지, 진행 상태 추적, 재생 속도 조절, 전체 화면 모드, 키보드 단축키 등의 기능을 제공합니다.

의존성

• Hls.js 라이브러리 (HLS 스트리밍 지원)
• HTML 및 CSS UI 요소

생성자

constructor(playerClazName: string, videoSrc: string, id: string | number)

매개변수:

• playerClazName: 플레이어 컨테이너의 CSS 선택자.
• videoSrc: 비디오 소스 URL.
• id: 비디오 인스턴스의 고유 ID.

초기화:

• 필수 HTML 요소 선택.
• HLS.js 지원 여부 확인 후 초기화.
• 플레이어 컨트롤을 위한 이벤트 리스너 추가.

속성

비디오 관련 요소

• video: <video> 요소.
• player: 컨테이너 요소.
• videoSrc: 비디오 소스 URL.
• progress, progressBar, progressThumb: 진행 상태 UI 요소.
• toggle: 재생/일시 정지 버튼.
• skipButtons: 앞/뒤로 이동 버튼.
• ranges: 볼륨 및 재생 속도 조절 슬라이더.
• timeDuration: 비디오 총 길이를 표시하는 요소.
• progressBoxEl: 진행 바 UI 컨테이너.
• hls: Hls.js 인스턴스.

상태 변수

• id: 비디오 인스턴스 ID.
• mousedown: 마우스 이벤트 상태 플래그.

메서드

비디오 컨트롤

• videoPlay(): 비디오 재생.
• videoPause(): 비디오 일시 정지.
• togglePlay(): 재생/일시 정지를 전환.
• updateButton(): 재생/일시 정지 버튼 아이콘 업데이트.

진행 상태 및 탐색

• handleProgress(): 비디오 재생 진행도 업데이트.
• scrub(event: any): 진행 바 클릭 시 이동.
• skip(event: any): 앞/뒤로 이동 버튼 클릭 처리.
• handleSkip(value: number): 특정 초만큼 이동.
• updateProgress(value: number): 진행 바 업데이트.

재생 속도 및 볼륨 조절

• handleRangeUpdate(event: any): 볼륨 및 재생 속도 조절.
• handlePlayBackRate(value: number): 재생 속도 설정.

전체 화면 & 키보드 컨트롤

• fullScreen(): 전체 화면 모드로 전환.
• handleKeyDownEvent(event: KeyboardEvent): 키보드 단축키 지원 (ArrowLeft, ArrowRight, Enter, Space).

라이프사이클 관리

• videoDestroy(): HLS.js 리소스 해제.
• handleTimeUpdate(percent: number, _paused?: boolean): 비디오 재생 위치 업데이트.

이벤트 핸들링

• addEventListeners(): UI 요소에 필요한 이벤트 리스너 추가.

이벤트 리스너

• click: 재생/일시 정지, 탐색, 진행 상태 업데이트 처리.
• mousemove: 진행 상태 UI 업데이트.
• keydown: 키보드 단축키 (ArrowLeft, ArrowRight, Enter, Space) 지원.
• change/mousemove: 볼륨 및 재생 속도 조절.

HLS.js란?

HLS(HTTP Live Streaming)는 애플(Apple)이 개발한 스트리밍 프로토콜로, 네트워크 상태에 따라 자동으로 비디오 품질을 조정하는 기능을 제공합니다. .m3u8 파일 형식으로 제공되며, 다양한 환경에서 실시간 및 주문형 비디오 스트리밍을 지원합니다.

Hls.js는 이러한 HLS 스트리밍을 HTML5 <video> 요소에서 실행할 수 있도록 도와주는 JavaScript 라이브러리입니다. VideoCtrls 클래스는 이 라이브러리를 활용하여 .m3u8 형식의 비디오를 원활하게 재생할 수 있도록 구현되었습니다.

HLS.js의 주요 기능

• 적응형 비트레이트 스트리밍(ABR): 네트워크 속도에 따라 비디오 품질 자동 조절
• 다중 오디오 트랙 지원: 다양한 언어 트랙 제공 가능
• 라이브 및 VOD(주문형 비디오) 지원: 실시간 스트리밍 및 기존 녹화 영상 지원
• 브라우저 호환성 확장: HLS를 기본적으로 지원하지 않는 브라우저에서도 실행 가능

VideoCtrls 클래스에서 HLS.js의 역할

1. Hls.isSupported()를 통해 HLS.js가 지원되는 환경인지 확인
2. hls.loadSource(this.videoSrc);를 사용해 .m3u8 파일을 로드
3. hls.attachMedia(_video);로 HTML5 비디오 요소에 연결하여 재생 가능하도록 설정
4. hls.on(Hls.Events.ERROR, callback);을 통해 스트리밍 중 발생하는 오류 처리

사용 예시

const videoController = new VideoCtrls(".video-player", "video.m3u8", 1);

이 코드는 지정된 소스와 ID를 가진 비디오 플레이어를 초기화하고 모든 필수 컨트롤 및 이벤트 리스너를 추가합니다.

참고 사항

• Hls.js를 사용하여 HLS 스트리밍을 지원합니다.
• .m3u8 형식을 기본적으로 지원하는 브라우저와 호환됩니다.
• 이벤트 기반 컨트롤 메커니즘을 제공합니다.

결론

VideoCtrls 클래스는 웹 애플리케이션에서 비디오 재생을 제어할 수 있도록 설계된 사용자 지정이 가능한 비디오 컨트롤러입니다.

결과문