Web Player Controller

Web Player Controller(구 VG Controller)는 고객사의 웹사이트에 iframe으로 삽입된 Kollus 플레이어와 통신하여, 재생 상태를 제어하거나 실시간 이벤트를 수신할 수 있게 해주는 JavaScript 라이브러리입니다.

주요 특징

통합 제어: 플레이어 종류와 관계없이 단일 규격으로 제어 가능합니다.
독립적 구동: 별도의 외부 라이브러리 의존성 없이 독립적으로 동작합니다.
이벤트 기반 구조: 메서드 호출 및 실시간 이벤트 리스너 구조를 지원합니다.

용어 정의

이 문서에서 사용하는 주요 기술 용어와 플레이어 표기에 대한 정의입니다. (참고: Kollus 플레이어 종류)

용어	설명
비디오 게이트웨이	시청자 요청에 따라 재생 데이터 및 인증 정보를 전달하는 서버
플레이어 ID	Kollus 플레이어 고유 ID
하드웨어 ID	Windows 환경 등 식별 가능한 값이 존재하는 경우 제공되는 하드웨어 고유 ID
HLS Fragment	HLS(HTTP Live Streaming) 프로토콜 기반 재생 시 전체 영상을 분할한 최소 단위의 미디어 세그먼트 파일
v3	HTML5 Player for PC (Hybrid): Microsoft Edge 또는 Chrome 45 이상에서 암호화 콘텐츠 재생 시 적용되는 하이브리드 HTML5 플레이어
v4	HTML5 Player for All: 비암호화 콘텐츠 전용 비설치형 HTML5 플레이어
v5	Web Player: 설치형과 비설치형의 장점을 결합한 차세대 통합 웹 플레이어

라이브러리 설치 및 초기화

클라이언트 스크립트를 로드한 후, 제어 대상(iframe)을 지정하여 인스턴스를 생성합니다.

기본 구현 예제

<script src="https://file.kollus.com/wpcontroller/web-player-controller-client.latest.min.js"></script>
<script>
window.onload = function () {
  try {
    var controller = new WebPlayerControllerClient({
      target_window: document.getElementById('child').contentWindow,
    });
    // Register event listeners and call methods
  } catch (e) {
    console.error(e);
  }
};
</script>
<body>
  <iframe id="child" src="https://v.kr.kollus.com/{MEDIA_CONTENT_KEY}..."></iframe>
</body>

주의사항

대상 지정: target_window 속성에는 반드시 iframe 요소의 contentWindow 객체를 전달해야 합니다.
브라우저 호환성: 이 라이브러리는 window.postMessage API를 사용하여 통신합니다. 해당 API를 지원하지 않는 브라우저에서는 작동이 제한됩니다.
다중 플레이어 제어: 페이지 내 여러 개의 플레이어(iframe)가 존재할 경우, 각 iframe ID별로 개별 인스턴스를 생성해야 합니다.

예외 코드

초기화 및 통신 과정에서 발생할 수 있는 에러 코드입니다.

코드	메시지	설명
`-99`	This browser does not support postMessage API	postMessage API를 지원하지 않는 브라우저
`-98`	Player type must be one of v2, v3, v4 and v5	유효하지 않은 플레이어 유형 (v2, v3, v4, v5만 지원)
`-97`	Event listener is not callable	호출할 수 없는 이벤트 리스너 (유효한 함수가 아님)
`-96`	Target window is not found	대상 Window 객체를 찾을 수 없음
`-95`	Custom skin is not supported	커스텀 스킨 미지원
`-1`	*	기타 PostMessage API 예외

CDN 경로

Web Player Controller는 CDN을 통해 제공됩니다.

경로 변경 안내

기존 'VG Controller'가 'Web Player Controller'로 명칭이 변경되었습니다. 기존 경로는 계속 유지되나 신규 기능 업데이트가 제한되므로, 지속적인 최신 기능 지원을 위해 신규 경로 사용을 권장합니다.

기존 경로: https://file.kollus.com/vgcontroller/vg-controller-client.{version}.min.js
신규 경로: https://file.kollus.com/wpcontroller/web-player-controller-client.{version}.min.js

특정 버전 고정

<script src="https://file.kollus.com/wpcontroller/web-player-controller-client.{version}.min.js"></script>

보안 강화 (SRI 적용)

라이브러리 변조 방지를 위한 SRI(Subresource Integrity) 속성 사용을 권장합니다.

<script src="https://file.kollus.com/wpcontroller/web-player-controller-client.{version}.min.js"
  integrity="sha256-esUCCL4RPYMS8AR+Sl3lNrFa5M+zgpt4Gb77qtz66OY="
  crossorigin="anonymous">
</script>

버전별 Integrity Code

버전	Integrity Code
3.0.7	sha384-s4QrCGcyFWEQmJsr0iK1A3HSjah8VE8Zq48k0jxHHUFOCsshRFRT1kNgj/xY/QPO
3.0.6	sha384-GdgPx9dCVTR5LL/T/CRoUPK1Af8Ss0uuHrG9m8A9ZjfwvgOBP2Hn0FpJOpbKxc2y
3.0.5	sha384-r4w31weNrojq8zcLil+4GUls/WL09DTxjgrTyBNz1D8lctVLId2QGiTrh1jq3AuK
3.0.4	sha384-XReEw9S0i2G9sfZyY3GOzLxC4XVfupJ3coBxfyT6rW7uowVbox9jddVW3e4HPdfI
3.0.3	sha384-vmOxuvAuxL9FhXfuWUtWy8+Bza8yMfKzM2YZd9nl+IBfO402BQqv7r9L7rzyCg3J
3.0.2	sha384-JSsUl7m8gxMpuk9IhIoILT6hHINhUzOK1/fKQmMLczpK8ad0iAlz53sTVJxG4ZEQ
3.0.1	sha384-TfZVDcnfT4uqCCeXU1MAM3L+8QhlduK94+2ukm5/TU8SmFfJusmzSFr+eW1nNzx5
3.0.0	sha384-Zu3WwunWVyaqnMrkKBjhgXL5dYyHK4U6XrtUvRVkLdXBSBOJrOw6/EGrsB9Yaw57
2.0.2	sha384-rD/iy3kIQHyXISy6nUBDw+m9ITNCXEiCNVO+6xGTuAKhSBRaCloGhKRJU9F14PhW
2.0.1	sha384-90u5dxpIgg4TvsndT8r1j54hjn302/IRkwzAeEQDq3zeWezi1VVjHGXyS4MBLbuC
2.0.0	sha384-aifzvq3KnpoCh/8DaG5t/PreNEXgAUUOsSuOsL0MHO6ZYvKSPkWpfRXbM3mB62Qx
1.6.2	sha256-0PBHq7Y0DcK/F1PGmAybxZh1NLL5AP89//qiSsTaR84=
1.6.1	sha256-CyKubDJ/UhR0QZbNpapLJ+eb3cxgS1Q9xUe0YUu3Yzs=
1.6.0	sha256-D+uxBOAbz5FeHAlzHxIb6pZm0OH2POTSJM8q7lVIAvw=
1.5.1	sha256-8X2N8jt72DqHSjlXad5eiArLfGXP8Br6W2CukrzzT/o=
1.5.0	sha256-bP2RqUMWigIFnYO5jpgwS9i+yrXRqsyMKOT34TEQSgc=
1.4.2	sha256-0jaAeov9h/kDevNySYTfIs3gd3uwqdR5KGF05kEtN30=
1.4.1	sha256-VVBBfWTrTqxPWkhAdCqrfkmawZyX0pmVEN5Ao1fK6yI=
1.4.0	sha256-aVGw8cCTLjL4ommgpWzXY/ZdNoxnIVkQOpyFkBF9hvg=
1.3.0	sha256-KEzr9IDpxMYIPheF9clyiVrwfXCOrahMu9ZRAS1nyTc=
1.2.8	sha256-QsoI2nF9ArX728ZciKU5W58AAqm3tTJs2qPVVq1rw2k=
1.2.7	sha256-GrSA/4PPdqMAlJ1+yU6kNyLUKSkI/yao8qB/CdpgHLg=
1.2.6	sha256-p7sZuwAm+snPLJcKXhM19bcJAFblc/N7FIr+KbLOyiM=
1.2.5	sha256-8H84AFVTk2ecP6BvSwDZwKdb+wax7eCODMabRjtYFG4=
1.2.4	sha256-byGt/vmYwvCJ5JSUTUKYSM3NJvTCAkwAcQjRPYA7OfU=
1.2.3	sha256-gELbkblxei35tOlrZxsBGTxjErybUM8dd7ToRpw9AH4=
1.2.2	sha256-ZqrlMRldpWxcvsbTmjJ0EbUnpvRPBOY2Y26lGrF8p5g=
1.2.1	sha256-QDMKykvp9W0VqeIcE8Z66aDga51Bil4dbKyu+xhVYU8=
1.1.19	sha256-a0JNjidB76X3hqapRctQlBEYT7UplG6rSTYdeORsoo4=
1.1.18	sha256-dQ+ubgLE/ZCuAF3gsq4aiEuXwIPtmMgFKho0VfMg618=
1.1.17	sha256-7BYchZl3hCp8pAmQWyvtrddOiSq6jiEV/3rigiHh2Hc=
1.1.16	sha256-sSwregT7/iEaiS3SWkUw2n+ifhAJaC9z1SUhxM4iA6A=
1.1.15	sha256-rXuiAt3HjeCdCoTPCdNnud6tXyM0QnFoG4wVohJX/vo=
1.1.14	sha256-gWFSHnUUnRrD9uI+jupozk4UaYI+rTNrutx2DoICd9Q=
1.1.13	sha256-5O+p4Fj23xbBoe1uiVqYWaLo7m423e8E3eJPLs7ZXac=
1.1.12	sha256-xeXyA4xBrv11fpQ4OooLjlh/wA+lMW7fv8LQ3InbZt0=
1.1.11	sha256-cqT+zCkG9IrFD5YBYgW/2uryxmX9xfjBArGvE7XxEGU=
1.1.10	sha256-ArDmq7qhhyH1jPcmp9AceymlnmdzL/fcLuj+7Cd9qGA=
1.1.9	sha256-gWFSHnUUnRrD9uI+jupozk4UaYI+rTNrutx2DoICd9Q=
1.1.8	sha256-1qLSiIaxaFInegLeM4YYFvNjkfS1ljnTkeLIVB4N9yA=
1.1.7	sha256-h3FJeZn9qzc36yGdCexZWCR00PYain1kA8YxOo1RYdE=
1.1.6	sha256-V6e7g4znlH2R6mS4iZG+ICEEqUuzT2I0WQebNKZapIs=
1.1.5	sha256-ylu1Lig3obBjhaxhPGokQ218NYrOMtGTSF98cC3wuJM=
1.1.4	sha256-YjHHosJQBjbhyZR0+3fDAc5YAU0f6fOcOzK5fWuh/vM=
1.1.3	sha256-imuCUkIbY1leNcPL4k9Jj06Nsl5zeG7qG7A2qsxNzY8=
1.1.2	sha256-OyniGO0Qw8YtUR1Lc1jquxyzd2E2W8XlhwWV2lSkD9w=
1.1.1	sha256-KYhE+CIgE9hl1e+AO7wVv25P3ZHjkhfw1u+UxOmcu8w=
1.1.0	sha256-U9z4sQc8f3gU3EU8z17mib/XsZNAQTPJfNiv1ZSy708=
1.0.6	sha256-Lraa1NkO1eo0APSSCyEkHtfhK7PP8U4mG8JTgcOpdkg=
1.0.5	sha256-8pO9uPazQtQ5RmZuzI053S3siu1Zi73nLPHbN0yCUso=
1.0.4	sha256-ki4kmvmPXsvtI8VKngskOtm9rxOlTKHxD8NJQjnYJzI=
1.0.3	sha256-M27rCu4/1FrzE9IabhMXQB3+bL5lzgBDg7gt6SZo1OI=
1.0.2	sha256-AAMmt+wOnoGhdBmrvEQP/TRRv40zYfxtvx9M3BrATZA=

이벤트 리스닝

controller.on() 메서드를 활용하여 플레이어의 상태 변화 및 재생 이벤트를 실시간으로 수신합니다.

리스너 등록 방식

단일 리스너

controller.on('event_name', function(param) {
  // Register event listener
});

다중 리스너

controller.on('event_name', function(param) {
  // First listener
});
controller.on('event_name', function(param) {
  // Second listener
});
// Execute all listeners when the event is fired

메서드 체이닝 (Method Chaining)

연속적인 이벤트 등록을 간결한 코드로 구현할 수 있습니다.

controller.on('event_name_1', function(param) {
  // First listener
}).on('event_name_2', function(param) {
  // Second listener
});

리스너 실행 순서

JavaScript 비동기 환경 특성상, 동일 이벤트에 등록된 여러 리스너 간의 실행 순서는 보장되지 않습니다.

권장 사항: 엄격한 실행 순서가 필요한 로직은 하나의 리스너 내부에서 순차적으로 작성하세요.

이벤트 목록

재생 상태 이벤트

이벤트	설명	지원 플레이어
`loaded`	플레이어 구성 요소의 로딩이 완료된 시점에 발생	v3, v4, v5
`ready`	서버로부터 재생 데이터를 수신하여 재생 준비가 완료된 시점에 발생	v3, v4, v5
`play`	최초 재생 시작 또는 일시정지 후 재생 재개 시 발생	v3, v4, v5
`pause`	일시정지 시 발생	v3, v4, v5
`done`	재생 시점이 전체 길이(`duration`) 끝에 도달했을 때 발생	v3, v4, v5
`waiting`	네트워크 환경 영향으로 추가 버퍼링이 필요한 경우, 정상화 전까지 1초 주기로 발생	v4, v5

진행률(Progress) 이벤트

주의

HTML5 브라우저 성능 및 네트워크 환경에 따라 progress 이벤트는 정확히 1초 간격이 아닌 약 0.1~0.5초의 오차가 발생할 수 있습니다.

이벤트	설명	지원 플레이어
`progress`	재생 중 약 1초 간격으로 발생하며 현재 재생 위치 정보 전달	v3, v4, v5

progress 파라미터 상세

파라미터	타입	설명
`percent`	`integer`	현재 재생 진행률 (0~100)
`position`	`number`	현재 재생 위치 (sec)
`duration`	`number`	콘텐츠 전체 길이 (sec)

controller.on('progress', function(percent, position, duration) {
  console.log(percent + '%', position + 'sec');
});

탐색(Seek) 이벤트

이벤트	설명	지원 플레이어
`seeking`	시청자가 재생 시점 이동을 시작한 시점에 발생	v4, v5
`seeked`	재생 시점 이동 작업이 완료된 시점에 발생	v4, v5
`seek_start`	재생 시점 이동이 감지된 최초 시점에 발생	v4, v5
`jumpstepchange`	구간 이동(빨리감기/되감기) 시간 단위 변경 시 발생	v3, v4, v5

음향 이벤트

이벤트	설명	지원 플레이어
`muted`	음소거 상태(On/Off) 변경 시 발생	v3, v4, v5
`volumechange`	음량 수치 변경 시 발생	v3, v4, v5

muted 파라미터 상세

파라미터	타입	설명
`is_muted`	`boolean`	`true`: 음소거 적용 `false`: 음소거 해제

volumechange 파라미터 상세

파라미터	타입	설명
`volume`	`integer`	변경된 음량 수치 (0~100)

재생속도(배속) 이벤트

이벤트	설명	지원 플레이어
`speedchange`	재생속도 변경 시 발생	v3, v4, v5
`playbackrateschange`	사용 가능한 배속값 그룹 변경 시 발생	v3, v4, v5

speedchange 파라미터 상세

파라미터	타입	설명
`speed`	`string`	변경된 배속 (0.5~4)

화면 및 UI 이벤트

이벤트	설명	지원 플레이어
`screenchange`	전체 화면 모드와 일반 모드 간 전환 시 발생	v3, v4, v5
`picture_in_picture_entered`	PIP(Picture-in-Picture) 모드 진입 시 발생	v3, v4, v5
`picture_in_picture_leaved`	PIP 모드 종료 시 발생	v3, v4, v5
`device_orientation_changed`	모바일 화면 방향(가로/세로) 변경 시 발생	v4, v5
`user_active_changed`	사용자 인터랙션에 의한 컨트롤바 활성화/비활성화 상태 변경 시 발생	v4, v5
`custom_skin_changed`	커스텀 스킨 변경 시 발생	v4, v5

screenchange 파라미터 상세

파라미터	타입	설명
`screen`	`string`	`windowed`: 일반 모드 `fullscreen`: 전체 화면 모드

device_orientation_changed 파라미터 상세

파라미터	타입	설명
`orientation`	`string`	`Portrait`: 세로 방향 `Landscape`: 가로 방향

자막 이벤트

이벤트	설명	지원 플레이어
`subtitle_load_done`	자막 파일 로드 완료 시 발생	v3, v4, v5
`subtitle_list_change`	메인 자막 목록 변경 시 발생	v5
`subtitle_sub_list_change`	서브 자막 목록 변경 시 발생	v5
`subtitle_cue_data_change`	자막 Cue 데이터 변경 시 발생	v5
`subtitlevisibilitychange`	메인 자막 노출 상태(On/Off) 변경 시 발생	v3, v4, v5
`subtitle_sub_visibilitychange`	서브 자막 노출 상태(On/Off) 변경 시 발생	v3, v4, v5
`subtitle_sizechange`	메인 자막 폰트 크기 변경 시 발생	v3, v4, v5
`subtitle_sub_sizechange`	서브 자막 폰트 크기 변경 시 발생	v3, v4, v5
`subtitle_shadow_rect_change`	메인 자막 배경 스타일 변경 시 발생	v3, v4, v5
`subtitle_sub_shadow_rect_change`	서브 자막 배경 스타일 변경 시 발생	v3, v4, v5

스트리밍 이벤트

이벤트	설명	지원 플레이어
`streaming_manifest_loaded`	HLS 또는 DASH Manifest 파일 로드 완료 시 발생	v5
`hls_manifest_loaded`	HLS Manifest 파일 로드 완료 시 발생 (`streaming_manifest_loaded` 사용 권장)	v4, v5
`dash_manifest_loaded`	DASH Manifest 파일 로드 완료 시 발생 (`streaming_manifest_loaded` 사용 권장)	v4, v5
`streaming_frag_changed`	스트리밍 Fragment 변경 시 발생	v5
`hlsfragchange`	HLS Fragment 변경 시 발생 (`streaming_frag_changed` 사용 권장)	v4, v5
`bitrate_data_loaded`	비트레이트 데이터 로드 완료 시 발생 (오름차순 정렬)	v4, v5

bitrate_data 형식 예시

controller.on('bitrate_data_loaded', function(bitrate_data) {
  // bitrate_data format: [{ width: <int>, height: <int>, bitrate: <int> }]
});

기타 이벤트

이벤트	설명	지원 플레이어
`error`	재생 중 시스템 오류 발생 시 호출	v3, v4, v5
`html5_video_supported`	브라우저의 HTML5 Video 기능 지원 여부 확인 시 호출	v3, v4, v5
`repeat_stat_change`	구간 반복 상태 변경 시 발생	v3, v4, v5
`bookmark_change`	북마크 추가 및 수정 시 발생 (v3는 삭제 시에도 발생)	v3, v4, v5
`next_episode_auto_change`	다음 회차 자동 재생 설정 변경 시 발생	v3, v4, v5
`next_episode_requested`	다음 회차 콜백이 요청된 시점에 발생	v3, v4, v5
`chapter_data_change`	챕터 데이터 변경 시 발생	v5

repeat_stat_change 예시

controller.on('repeat_stat_change', function (data) {
  // - end: 구간 반복 종료 시점 (sec)
  // - start: 구간 반복 시작 시점 (sec)
  // - status: 구간 반복 상태
});

메서드 사용법

Controller 인스턴스를 통해 생성된 객체로 플레이어의 동작을 직접 제어할 수 있습니다.

기본 호출 방식

별도의 인자가 필요 없는 제어 명령은 메서드를 직접 호출합니다.

controller.play();

파라미터 전달 방식

설정값이 필요한 제어 명령은 메서드의 인자로 파라미터를 전달합니다.

controller.set_volume(90);

메서드 목록

이벤트 리스너 메서드

메서드	설명	지원 플레이어
`on(event_name, callback)`	이벤트 리스너 등록 파라미터 `event_name` (`string`): 이벤트 이름 `callback` (`function`): 이벤트 발생 시 호출될 함수 반환값: `WebPlayerControllerClient` 인스턴스	v3, v4, v5
`once(event_name, callback)`	한 번만 실행되는 이벤트 리스너 등록	v3, v4, v5
`off(event_name)`	특정 이벤트에 등록된 모든 리스너 일괄 제거	v3, v4, v5

재생 메서드

메서드	설명	지원 플레이어
`play([start_at])`	재생 시작 파라미터 (선택사항) `start_at` (`integer`, sec): 해당 시점부터 즉시 재생 호출 예시 재생 시작: `controller.play();` 10초 시점부터 재생: `controller.play(10);`	v3, v4, v5
`pause()`	현재 재생 중인 콘텐츠 일시정지	v3, v4, v5
`get_progress()`	현재 재생 정보(`percent, position, duration`) 반환	v3, v4, v5
`get_next_episode_auto()`	다음 회차 자동 재생 활성화 여부(`boolean`) 반환	v3, v4, v5
`set_next_episode_auto(is_auto)`	다음 회차 자동 재생 활성화/비활성화 설정 파라미터 `is_auto` (`boolean`): 자동 재생 여부	v3, v4, v5

탐색(Seek) 메서드

메서드	설명	지원 플레이어
`ff()`	현재 재생 위치에서 `set_jumpstep` 메서드로 설정된 `jumpstep`만큼 앞으로 이동 (빨리감기, 기본값: 10초)	v3, v4, v5
`rw()`	현재 재생 위치에서 `set_jumpstep` 메서드로 설정된 `jumpstep`만큼 뒤로 이동 (되감기, 기본값: 10초)	v3, v4, v5
`set_current_time(time)`	재생 상태를 유지하며 지정한 시점으로 이동 파라미터 `time` (`integer`, sec): 이동할 시점	v3, v4, v5
`get_current_time()`	현재 재생 위치 반환	v3, v4, v5
`set_jumpstep(jumpstep)`	`ff()` 또는 `rw()` 호출 시 이동할 시간 간격 설정 파라미터 `jumpstep` (`integer`, sec): 이동할 시간 간격	v3, v4, v5
`get_jumpstep()`	현재 설정된 `jumpstep` 값 반환	v3, v4, v5
`set_keyframe_seek_default(is_default)`	키프레임 단위 이동을 기본값으로 설정 파라미터 `is_default` (`boolean`): 기본값으로 설정할지 여부	v2

play([start_at])와 set_current_time(time) 비교

play(10): 10초 위치로 이동한 후 즉시 재생 시작
set_current_time(10): 10초 위치로 이동하지만, 기존 재생/일시정지 상태 유지

음향 메서드

메서드	설명	지원 플레이어
`get_volume()`	현재 설정된 음량 수치 반환	v3, v4, v5
`set_volume(volume)`	음량 설정 파라미터 `volume` (`integer`, 0~100): 설정할 음량	v3, v4, v5
`mute()`	음소거 상태 전환 (On/Off)	v3, v4, v5

화면 메서드

메서드	설명	지원 플레이어
`toggle_pip()`	PIP(Picture-in-Picture) 모드 활성화 상태 전환	v3, v4, v5
`get_screen()`	현재 화면 모드 반환 반환값 `windowed`: 일반 모드 `fullscreen`: 전체 화면 모드	v3, v4, v5
`set_screen()`	전체 화면 모드와 일반 모드 간 전환 (FireFox 브라우저 미지원)	v3, v4, v5
`set_fullscreen_element(element)`	전체 화면 전환 대상 DOM 요소 설정 파라미터 `element` (`string`): 전체 화면 전환 대상 HTML 요소	v3, v4, v5
`enable_virtual_fullscreen()`	전체 화면 버튼 클릭 시 실제 전체 화면 전환 없이 UI 토글 및 `screenchange` 이벤트만 발생 (`set_fullscreen_element()` 실행 시 본 기능은 해제됨)	v5
`get_video_visibility()`	비디오 화면의 현재 노출 상태 반환	v3, v4, v5
`set_video_visibility(visibility)`	비디오 화면 노출 여부 설정 (오디오 재생은 유지) `visibility` 파라미터 상세 `true`: 노출 `false`: 비노출	v3, v4, v5
`set_ratio(type)`	화면 확대 및 비율 방식 설정 `type` 파라미터 상세 `contain`: 가로/세로 비율을 유지하며 화면에 맞춤 `fill`: 비율과 관계없이 화면 전체를 채움 `enlargement`: 세로 길이를 기준으로 맞춤 (좌우 스크롤 발생 가능)	v3, v4, v5

Deprecated

다음 메서드는 더 이상 유지보수되지 않으므로 대체 메서드를 사용하세요.

enable_fullscreen_button() ➔ enable_virtual_fullscreen()

컨트롤바 메서드

메서드	설명	지원 플레이어
`set_control_visibility(visibility)`	내장 컨트롤바 노출 여부 설정	v3, v4, v5
`get_control_visibility()`	내장 컨트롤바 현재 노출 상태 반환	v3, v4, v5
`set_controls_inactive_time(time)`	컨트롤바 자동 숨김 대기 시간 설정 (`0`: 상시 노출)	v3, v4, v5
`get_controls_inactive_time()`	설정된 컨트롤바 자동 숨김 시간 반환	v3, v4, v5
`set_controls_activity(activity)`	컨트롤바 활성화 여부 설정	v3, v4, v5
`get_controls_activity()`	컨트롤바 활성화 상태 반환	v3, v4, v5
`set_controlbar_progress_only(enable)`	프로그레스 바(Progress Bar)만 노출하고 기타 제어 버튼 숨김 처리	v3, v4, v5
`get_controlbar_progress_only()`	프로그레스 바 단독 노출 여부 반환	v3, v4, v5
`set_controlbar_hide_playing(enable)`	재생 중 컨트롤바 자동 숨김 여부 설정	v4, v5
`get_controlbar_hide_playing()`	재생 중 컨트롤바 자동 숨김 설정 여부 반환	v4, v5
`hide_controlbar_button(value)`	버튼을 컨트롤바에서 숨김 (`ready` 이벤트 이후 호출 권장) `value` 파라미터 상세 `play`: 재생 `rewind`: 되감기 `forward`: 빨리감기 `repeat`: 구간 반복 `currenttime`: 현재 재생 시간 `durationtime`: 총 재생 시간 `quality`: 화질 `playbackrate`: 배속 `mute`: 음소거 `volume`: 볼륨 그래프 `subtitle`: 자막 `setting`: 설정 `fullscreen`: 전체 화면 모드 `chat`: 채팅 `pip`: PIP 모드 `bigplay`: 중앙 재생 버튼 (Kollus Web Player) `seekcontainer`: 모바일 좌우 되감기/빨리감기 (Kollus Web Player)	v3, v4, v5
`set_setting_panel_activity(activity)`	설정 패널 표시 여부 및 패널 지정 `activity` 파라미터 상세 `true`: 표시 `false`: 비표시 `패널 이름`: 지정한 이름의 패널 표시	v3, v4, v5

hide_controlbar_button 메서드 호출 예시

컨트롤바에서 전체 화면 모드 및 설정 버튼을 숨김 처리합니다.

controller.hide_controlbar_button(['fullscreen', 'setting']);

재생속도(배속) 메서드

메서드	설명	지원 플레이어
`set_speed(speed)`	재생속도를 0.5~4 범위 내에서 0.1 단위로 설정	v3, v4, v5
`get_speed()`	현재 적용 중인 재생속도를 문자열 형태로 반환	v3, v4, v5
`set_playback_rates(rates)`	플레이어 UI에 노출될 배속값 그룹 설정 (아래 메서드 호출 예시 참고)	v3, v4, v5
`get_playback_rates()`	현재 설정된 배속값 그룹을 문자열 형태로 반환	v3, v4, v5

set_playback_rates 메서드 호출 예시

단일 배열: 배속 옵션을 한 줄로 나열하여 구성합니다.

controller.set_playback_rates([0.5, 1, 1.5, 2]);

이중 배열: [배속값 배열, 표시할 행(Row) 수]

controller.set_playback_rates([[0.5, 1, 1.5, 2, 3, 4], 2]);

참고

iOS 환경에서 HLS 방식으로 시청할 경우, 운영체제 정책 및 기술 규격에 따라 최대 2배속까지만 지원됩니다.

구간 반복 메서드

메서드	설명	지원 플레이어
`set_repeat_start([position])`	구간 반복 시작 시점 설정 (인자 생략 시 현재 재생 위치를 기준으로 설정)	v3, v4, v5
`set_repeat_end([position])`	구간 반복 종료 시점 설정 (인자 생략 시 현재 재생 위치를 기준으로 설정)	v3, v4, v5
`unset_repeat()`	활성화된 구간 반복 설정을 해제하고 일반 재생 모드로 전환	v3, v4, v5
`get_repeat()`	현재 구간 반복 상태 정보(`status, start, end`) 반환	v3, v4, v5

set_repeat 메서드 호출 예시

10초 시점을 반복 시작 지점으로 설정합니다.

controller.set_repeat_start(10);

20초 시점을 반복 종료 시점으로 설정합니다.

controller.set_repeat_end(20);

북마크 메서드

메서드	설명	지원 플레이어
`refresh_bookmark()`	서버로부터 최신 북마크 목록을 동기화하여 업데이트 수행	v3, v4, v5
`get_bookmark_count()`	모든 북마크, 공식 북마크, 내 북마크 개수(`all, index, user`) 반환	v3, v4, v5
`set_bookmark_add_activity(activation)`	북마크 추가 버튼 활성화 여부 설정	v3, v4, v5
`set_bookmark_update_activity(activation)`	북마크 수정 버튼 활성화 여부 설정	v3, v4, v5

Deprecated

다음 메서드들은 더 이상 유지보수되지 않으므로 대체 메서드를 사용하세요.

set_bookmark_add_activation / set_bookmark_add_visibility ➔ set_bookmark_add_activity(activation)
set_bookmark_update_activation / set_bookmark_update_visibility ➔ set_bookmark_update_activity(activation)

자막 메서드

메서드	설명	지원 플레이어
`set_subtitle(value)`	자막 데이터(VTT URL 또는 RawData) 직접 설정	v3, v4, v5
`get_subtitles_list(type)`	사용 가능한 자막 목록 반환 (`MediaInfo` 객체 내 자막 속성 반환) `type` 파라미터 상세 `'main'` (기본값): 메인 자막 `'sub'`: 서브 자막	v3, v4, v5
`set_current_subtitle(index, type)`	지정한 인덱스의 자막으로 전환 파라미터 `index`: 자막의 인덱스 (0부터 시작) `type`: 자막 유형 `'main'` (기본값): 메인 자막 `'sub'`: 서브 자막	v3, v4, v5
`set_subtitle_visibility(visibility, type)`	자막 노출 여부 설정 `visibility` 파라미터 상세 `true`: 자막 노출 `false`: 자막 미노출 `type` 파라미터 상세 `'main'` (기본값): 메인 자막 `'sub'`: 서브 자막	v3, v4, v5
`get_subtitle_font_size(type)`	자막 텍스트 크기 반환 `type` 파라미터 상세 `'main'` (기본값): 메인 자막 `'sub'`: 서브 자막	v3, v4, v5
`set_subtitle_font_size(size, type)`	자막 텍스트 크기(px) 설정	v3, v4, v5
`get_subtitle_shadow_rect(type)`	자막 배경 스타일이 불투명한 사각형인지 여부 반환 반환값 `true`: 불투명한 사각형 `false`: 글자 테두리 그림자	v3, v4, v5
`set_subtitle_shadow_rect(is_rect, type)`	자막 배경 스타일 설정 `is_rect` 파라미터 상세 `true`: 불투명한 사각형 `false`: 글자 테두리 그림자 `type` 파라미터 상세 `'main'` (기본값): 메인 자막 `'sub'`: 서브 자막	v3, v4, v5
`get_subtitle_activity()`	자막 노출 위치 반환	v3, v4, v5
`set_subtitle_activity(activity)`	자막 노출 위치 설정	v3, v4, v5

Deprecated

다음 메서드들은 더 이상 유지보수되지 않으므로 대체 메서드를 사용하세요.

get_subtitles_sub_list() ➔ get_subtitles_list(type)
set_current_subtitle_sub(index) ➔ set_current_subtitle(index, type)
set_subtitle_sub_visibility(visibility) ➔ set_subtitle_visibility(visibility, type)
get_subtitle_sub_font_size() ➔ get_subtitle_font_size(type)
set_subtitle_sub_font_size(size) ➔ set_subtitle_font_size(size, type)
get_subtitle_sub_shadow_rect() ➔ get_subtitle_shadow_rect(type)
set_subtitle_sub_shadow_rect(is_rect) ➔ set_subtitle_shadow_rect(is_rect, type)

챕터 메서드

메서드	설명	지원 플레이어
`set_chapter_data(data)`	챕터 데이터 설정	v5
`get_chapter_data()`	챕터 데이터 반환	v5

set_chapter_data(data)의 data 파라미터는 URL String 또는 JSON 형식만 허용됩니다. 챕터 데이터가 변경되면 기타 이벤트 이벤트가 발생합니다.

// URL String
controller.set_chapter_data('https://example.com/chapters.json');

// JSON
controller.set_chapter_data({
  "ko": [
    {
      "position": 0,
      "value": "first"
    },
    {
      "position": 30,
      "value": "second"
    }
  ],
  "default_language_code": "ko"
});

비트레이트 메서드

메서드	설명	지원 플레이어
`set_bitrate(index)`	지정한 인덱스의 비트레이트로 전환. `set_bitrate()` 메서드로 실제 변경을 요청할 때는 해당 배열 인덱스에 +1을 한 값을 인자로 전달해야 합니다. (`0`: 자동)	v4, v5
`get_bitrate_data()`	사용 가능한 비트레이트 목록 반환. `get_bitrate_data()`를 통해 반환된 배열의 인덱스는 0부터 시작합니다.	v4, v5

플레이어 정보 메서드

메서드	설명	지원 플레이어
`get_player_type()`	현재 실행 중인 플레이어 종류 반환 반환값 `v3`: HTML5 Player for PC (Hybrid) `v4`: HTML5 Player for All	v3, v4, v5
`get_player_id()`	Kollus 플레이어 ID 반환 (`ready` 이벤트 이후 호출 가능)	v3, v4, v5
`get_hardware_id()`	하드웨어 ID 반환 (`ready` 이벤트 이후 호출 가능)	v3
`get_agent_version()`	플레이어 에이전트 버전 반환 (`ready` 이벤트 이후 호출 가능, 암호화 콘텐츠 재생 시에만 유효)	v5
`get_video_info()`	콘텐츠 해상도 및 비트레이트 정보(`width, height, bitrate`) 반환 (`ready` 이벤트 이후 호출 가능)	v3, v4, v5
`get_lms_data(callback)`	LMS 데이터 반환 파라미터 `callback` (`function`): LMS 데이터(`data` 객체)를 인수로 받는 콜백 함수	v3, v4, v5
`get_streaming_frag_data()`	HLS/DASH Fragment 관련 데이터 반환	v5
`get_streaming_manifest_data()`	HLS/DASH Manifest 관련 데이터 반환	v5
`dispose()`	플레이어 인스턴스 및 자원 해제	v4, v5

Deprecated

다음 메서드는 더 이상 유지보수되지 않으므로 대체 메서드를 사용하세요.

get_hls_frag_data() ➔ get_streaming_frag_data()

커스텀 스킨 메서드

메서드	설명	지원 플레이어
`get_custom_skin()`	현재 플레이어에 적용 중인 커스텀 스킨 설정(JSON) 반환 (`ready` 이벤트 이후 호출 가능)	v4, v5
`set_custom_skin(json_data)`	JSON 형식의 설정 데이터를 주입하여 커스텀 스킨 변경 (`ready` 이벤트 이후 호출 가능)	v4, v5

set_custom_skin 메서드 호출 예시

controller.set_custom_skin({
  controlbar: {
    enable: true,
    backgroundColor: 123123,
    backgroundAlpha: 0.2,
    progressButton: {
      enable: false
    }
  }
});

에러 메서드

메서드	설명	지원 플레이어
`get_error_detail()`	현재 발생한 에러의 상세 정보(`code, message, param`) 반환	v3, v4, v5
`set_custom_error(code, message, param)`	기본 에러 화면 대신 개발자가 정의한 커스텀 에러 코드와 메시지를 플레이어 UI에 노출	v3, v4, v5

채팅 메서드

메서드	설명	지원 플레이어
`set_chat_config(value)`	채팅 관련 설정 적용 (`ready` 이벤트 이후 호출 가능)	v3, v4, v5
`notify_visibleheight_changed(height)`	Android WebView 환경에서 키보드 활성화에 따른 화면 높이 변화값 전달	v3, v4, v5

set_chat_config 메서드 호출 예시

controller.set_chat_config({
  customer_page: [{
    title: 'Class Title',
    url: 'https://example.com'
    // or
    // html: '<h2>Custom HTML</h2>'
  }]
});

참고

보안 정책: 외부 페이지 주입 시 https 프로토콜이 적용된 URL만 허용됩니다.
스크립트 제약: html 속성으로 전달된 본문 내 script 태그는 보안상의 이유로 실행이 제한됩니다.

close 이벤트 메서드

메서드	설명	지원 플레이어
`set_enable_close_event()`	브라우저 종료(`close`) 감지 및 콜백 기능 활성화	v3, v4, v5
`set_close_callback_fn(fn)`	브라우저 종료 시 실행할 커스텀 콜백 함수 등록	v3, v4, v5
`get_enable_close_event()`	브라우저 종료(`close`) 콜백 할성화 여부 반환	v3, v4, v5
`set_close_button(enable, fn)`	모바일용 닫기 버튼 생성 및 클릭 이벤트 설정 (`ready` 이벤트 이후 호출 가능)	v4, v5

기타 메서드

메서드	설명	지원 플레이어
`set_vr_overlay(options)`	iOS 환경 내 VR 콘텐츠 재생을 위한 권한 요청 오버레이 설정	v3, v4, v5
`debug()`	플레이어의 디버그 로그 데이터를 콘솔에 출력	v5
`set_short_key(enable)`	플레이어 단축키 활성화 여부 설정	v2
`get_topmost()`	플레이어 창의 최상위 노출 설정 여부 반환	v2
`set_topmost(topmost)`	플레이어 창의 최상위 노출 여부 설정	v2
`set_lms_check()`	브라우저 종료 시 LMS 데이터 전송 완료 여부 확인 설정	v2

모바일 VR 콘텐츠 재생 시 유의사항

모바일 브라우저의 보안 정책 및 iframe 환경의 기술적 제약으로 인해 VR(360°) 콘텐츠 재생 시 아래 사항을 확인해야 합니다.

Android: iframe 내에서 디바이스의 orientation(방향) 정보 동기화 이슈로 인해, VR 영상의 좌우 조작 방향이 실제 디바이스 움직임과 반대로 작동하는 현상이 발생할 수 있습니다.
iOS: iOS 13 버전부터 보안 강화를 위해 DeviceMotion(가속도/자이로) 데이터 접근 시 사용자 승인이 필수입니다. 하지만 브라우저 보안 정책상 iframe 내부에서는 권한 요청 팝업 호출이 제한되어 VR 조작 기능이 작동하지 않습니다.

해결 방법

Web Player Controller 1.1.10 이상 버전을 사용하세요.
iOS 환경에서는 set_vr_overlay() 메서드를 반드시 호출하세요.

var controller = new WebPlayerControllerClient({
  // Specify the top-level parent window containing the player iframe
  target_window: player.contentWindow
});
controller.set_vr_overlay({
  // Specify the target DOM element to display the permission request overlay
  target_element: document.getElementById('player'),
  // Set a custom message to guide users to grant motion and gyro sensor permissions
  permission_request_help_message: 'Please allow access to the accelerometer and gyroscope sensors to use VR features.'
});

Issue

iOS 13.4 이상 버전의 경우, Apple의 개인정보 보호 정책에 따라 DeviceMotion API의 rotationRate 값이 정상적으로 반환되지 않습니다.

주요 특징​

용어 정의​

라이브러리 설치 및 초기화​

기본 구현 예제​

주의사항​

예외 코드​

CDN 경로​

최신 버전 자동 적용​

특정 버전 고정​

보안 강화 (SRI 적용)​

이벤트 리스닝​

리스너 등록 방식​

단일 리스너​

다중 리스너​

메서드 체이닝 (Method Chaining)​

이벤트 목록​

재생 상태 이벤트​

진행률(Progress) 이벤트​

progress 파라미터 상세​

탐색(Seek) 이벤트​

음향 이벤트​

muted 파라미터 상세​

volumechange 파라미터 상세​

재생속도(배속) 이벤트​

speedchange 파라미터 상세​

화면 및 UI 이벤트​

screenchange 파라미터 상세​

device_orientation_changed 파라미터 상세​

자막 이벤트​

스트리밍 이벤트​

bitrate_data 형식 예시​

기타 이벤트​

repeat_stat_change 예시​

메서드 사용법​

기본 호출 방식​

파라미터 전달 방식​

메서드 목록​

이벤트 리스너 메서드​

재생 메서드​

탐색(Seek) 메서드​

play([start_at])와 set_current_time(time) 비교​

음향 메서드​

화면 메서드​

컨트롤바 메서드​

hide_controlbar_button 메서드 호출 예시​

재생속도(배속) 메서드​

set_playback_rates 메서드 호출 예시​

구간 반복 메서드​

set_repeat 메서드 호출 예시​

북마크 메서드​

자막 메서드​

챕터 메서드​

비트레이트 메서드​

플레이어 정보 메서드​

커스텀 스킨 메서드​

set_custom_skin 메서드 호출 예시​

에러 메서드​

채팅 메서드​

set_chat_config 메서드 호출 예시​

close 이벤트 메서드​

기타 메서드​

모바일 VR 콘텐츠 재생 시 유의사항​

해결 방법​

주요 특징

용어 정의

라이브러리 설치 및 초기화

기본 구현 예제

주의사항

예외 코드

CDN 경로

최신 버전 자동 적용

특정 버전 고정

보안 강화 (SRI 적용)

이벤트 리스닝

리스너 등록 방식

단일 리스너

다중 리스너

메서드 체이닝 (Method Chaining)

이벤트 목록

재생 상태 이벤트

진행률(Progress) 이벤트

progress 파라미터 상세

탐색(Seek) 이벤트

음향 이벤트

muted 파라미터 상세

volumechange 파라미터 상세

재생속도(배속) 이벤트

speedchange 파라미터 상세

화면 및 UI 이벤트

screenchange 파라미터 상세

device_orientation_changed 파라미터 상세

자막 이벤트

스트리밍 이벤트

bitrate_data 형식 예시

기타 이벤트

repeat_stat_change 예시

메서드 사용법

기본 호출 방식

파라미터 전달 방식

메서드 목록

이벤트 리스너 메서드

재생 메서드

탐색(Seek) 메서드

play([start_at])와 set_current_time(time) 비교

음향 메서드

화면 메서드

컨트롤바 메서드

hide_controlbar_button 메서드 호출 예시

재생속도(배속) 메서드

set_playback_rates 메서드 호출 예시

구간 반복 메서드

set_repeat 메서드 호출 예시

북마크 메서드

자막 메서드

챕터 메서드

비트레이트 메서드

플레이어 정보 메서드

커스텀 스킨 메서드

set_custom_skin 메서드 호출 예시

에러 메서드

채팅 메서드

set_chat_config 메서드 호출 예시

close 이벤트 메서드

기타 메서드

모바일 VR 콘텐츠 재생 시 유의사항

해결 방법