Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

Version 1 Next »


V/G Controller

Kollus VG Controller는 Videogateway로 제공되는 미디어의 일부 컨트롤을 고객사 웹사이트 내에서 구현 할 수 있도록 지원하는 Javascript library입니다. Kollus VG Controller는 다음과 같은 특징을 가지고 있습니다.

  • Videogateway에서 자동으로 실행되는 플레이어의 타입에 관계없이 동일한 코드로 제어 가능
  • 간단한 설치 + 쉬운 사용방법
  • 플레이어의 감지 실행을 고민할 필요가 없음
  • 서드파티 자바스크립트 라이브러리가 필요치 않음
메소드와 이벤트 목록 이름 옆에 표기되는 Flash, V2, V3, V4 Player 등은 해당 메소드나 이벤트를 지원하는Player를 의미합니다.

Flash : 암호화되지 않은 파일의 경우 일반적으로 Flash Player 를 통해 재생됩니다.[^1]
V2 : 암호화된 파일의 경우 일반적으로 V2 Player를 통해 재생됩니다. V2 Player는 IE의 경우 ActiveX, Chrome이나 Firefox의 경우 NPAPI를 이용 하는 Player입니다.[^2]
V3 : 암호화된 파일이 Edge나 Chrome 45버전 이상의 웹브라우져에서 호출될 경우 실행되는 하이브리드 HTML5 Player입니다.
V4 : 암호화되지 않은 파일의 경우 실행되는 HTML5 Player이며 Flash Player를 대체합니다.

이름 옆에 아무 Player도 표시되지 않는 경우는 모든 플레이어가 공통적으로 기능을 지원한다는 의미입니다.

[^1]: Adobe에서 2020년부터 Flash Player에 대한 지원을 중단한다고 발표하였습니다.

[^2]: Chrome 42+ / Firefox 52+ 브라우저에서는 NPAPI 지원을 중단하였습니다.

설치하기

VgControllerClient

(고객사 html page에 삽입)

...
<script src="https://file.kollus.com/vgcontroller/vg-controller-client.latest.min.js"></script>
<script>
    window.onload = function() {
    try {
        var controller = new VgControllerClient({
        	target_window: document.getElementById('child').contentWindow
        });
        // 여기서부터 이벤트 리스너를 등록하거나, 웹페이지 Element에 메소드를 bind하면 됩니다.
        } catch(e) {
            // Videogateweay Controller Library는 window.postMessage API를 이용하기 때문에
            // 해당 기능을 지원하지 않는 웹브라우져에서는 동작하지 않습니다.
            // 이 부분에 적절한 fail-over 코드를 추가하여 주십시요.
        }
    };
</script>
<body>
	<iframe id="child" src="http://v.kr..."></iframe>
</body>
...

  • VgControllerClient 생성시 파라미터로 전달하는 target_window의 경우 홈페이지에 첨부한 Kollus Videogateway iframe의 HTMLElement에 contentWindow 속성을 입력해야 합니다.
  • 본 스크립트는 window.postMessage API 를 이용하여 Player와 통신하므로, 해당 기능을 지원하지 않는 웹브라우져에서는 동작하지 않습니다.
  • 웹페이지 내에 하나 이상의 iframe을 embed한 경우 제어할 iframe마다 서로 다른 VgControllerClient 를 생성해야 합니다.
  • 이전 버전과의 호환성을 위해 (v0.5이하) new VgControllerClient() 대신 new Kollus.VideogatewayController() 를 사용해도 정상적으로 작동합니다.

이벤트 리스닝

플레이어로부터 수신되는 각종 이벤트 발생시 사용자가 정의한 callback 함수를 실행하도록 이벤트 리스너(EventListener)를 등록하는 방법입니다.

controller.on('event_name', function(param) {
// 이벤트 리스너
});


하나의 이벤트에 하나 이상의 리스너를 등록할 수도 있습니다. 이 경우 이벤트 발생시에 등록된 모든 리스너가 실행됩니다.

controller.on('event_name', function(param) {
	// 첫번째 리스너
});
controller.on('event_name', function(param) {
	// 두번째 리스너
});
// 이벤트 발생시 첫번째, 두번째 리스너가 모두 실행
// 다만, 자바스크립트 이벤트 루프와 callback 함수가 실행되는 방식에 의해, 첫번째 리스너가 반드시 먼저
// 실행된다고 보장할 수 없으며, 두번째 리스너가 실행되는 것이 첫번째 리스너가 실행된 뒤인 것도 아닙니다.
이벤트 리스너를 등록하는 함수인 on 은 메소드 체이닝(Method chaining)을 지원합니다.
controller.on('event_name_1', function(param) {
	// 첫번째 리스너
}).on('event_name_2', function(param) {
	// 두번째 리스너
});

메소드 사용하기

Videogateway Controller Library가 지원하는 메소드를 호출하는 방법은 간단합니다.

controller.play();
이게 전부입니다. 경우에 따라서 파라미터를 요구하는 메소드도 있습니다.
controller.set_volume(90);

참고사항

메소드 목록

on(event_name, callback_function)

이벤트 리스너를 등록합니다.

controller.on('event_name', function(param) {
	// event_name에 해당하는 이벤트 발생시, 두번째 인자인 callback function 실행
});


Parameters:

  • event_name String callback function을 bind할 이벤트 이름입니다.
  • callback_function Function 이벤트 발생시 실행될 callback function입니다. 경우에 따라서 callback function에는 파라미터가 주어질 수 있습니다.

Return:

  • Object VG-Controller Client 객체를 반환합니다.

off(event_name)

등록된 이벤트 리스너를 제거합니다.

controller.off('event_name');


Parameters:

  • event_name String callback function으로 bind된 이벤트 이름입니다.

Return:

  • Object VG-Controller Client 객체를 반환합니다.

get_progress()

재생 진행중인 위치 정보를 반환합니다.

Parameters:

  • No parameter

    eturn:

  • Object percent, position, duration을 property로 갖는 object 객체를 반환합니다. 각 값들에 대한 설명은 progress 이벤트 를 참고하여 주십시요.

play([start_at])

동영상을 재생합니다.

controller.play();

특정 지점부터 재생하려면 다음과 같이 재생할 위치를 파라미터로 입력하여 주십시요.
controller.play(10); // 10초 위치부터 재생


Parameters:

  • start_at Integer (Optional) 재생 시작 위치입니다. 생략하면 처음부터 재생합니다.

    eturn:

  • No return

pause()

동영상 재생을 일시정지합니다.

Parameters:

  • No parameter

    eturn:

  • No return

set_volume(volume)

음량을 변경합니다. 음량은 0 <= volume <= 100 사이의 Integer형 값이어야 합니다. 이 범위를 벗어난 감은 0이나 100으로 재조정 됩니다.

Parameters:

  • volume Integer 변경할 음량입니다.

    eturn:

  • No return

get_volume()

현재 설정된 음량을 반환합니다.

Parameters:

  • No parameter

    eturn:

  • Integer 현재 설정된 음량입니다.

mute()

음소거를 설정하거나 해제합니다. 음소거가 해제된 상태에서 호출하면 음소거를 설정하고, 반대로 설정된 상태라면 해제합니다.

Parameters:

  • No parameter

    eturn:

  • No return

ff()

set_jumpstep 메소드에 의해 설정된 이동할 시간값만큼 현재 재생 위치보다 이후로 이동합니다. 초기값은 10초입니다.

Parameters:

  • No parameter

    eturn:

  • No return

rw()

set_jumpstep 메소드에 의해 설정된 이동할 시간값만큼 현재 재생 위치보다 이전으로 이동합니다. 초기값은 10초입니다.

Parameters:

  • No parameter

    eturn:

  • No return

set_screen() V2 V3 V4

일반 윈도우 모드와 전체화면 모드로 화면 상태를 변경합니다. 화면이 일반 윈도우 모드인 경우 호출하면 전체화면으로, 전체화면 모드인 경우는 일반 윈도우 모드로 변경됩니다.

  • 이 기능은 Flash Player에서는 지원되지 않습니다.
  • IE 브라우져의 경우 IE 10 이하는 fullscreen 기능을 지원하지 않습니다.

Parameters:

  • No parameter

    eturn:

  • No return

get_screen()

현재 화면 모드를 반환합니다. set_screen이 V2, V3, V4 Player에서만 지원되긴 하지만, get_screen 함수는 모든 Player에서 정상적으로 현재 화면 상태를 반환합니다. 반환되는 값은 다음과 같습니다.

  • 일반 윈도우 모드 : windowed
  • 전체화면 모드 : fullscreen

Parameters:

  • No parameter

    eturn:

  • String 반환되는 현재 화면 모드입니다. windowed, fullscreen 두 값 가운데 하나를 갖습니다.

set_jumpstep(jumpstep)

ff 메소드나 rw 메소드를 통해 이동할 시간값을 설정합니다. 시간값은 초단위 정수로 입력합니다.

Parameters:

  • jumpstep Integer 이동할 시간값 입니다.

    eturn:

  • No return

get_jumpstep()

현재 설정된 이동할 시간값을 반환합니다.

Parameters:

  • No parameter

    eturn:

  • Integer 반환되는 이동할 시간값입니다.

set_control_visibility(visibility)

Player 내장 Control들을 숨김하거나 숨김을 해제합니다. 파라미터로 true를 주면 숨김 해제, false를 주면 숨김입니다.

Parameters:

  • visibility Boolean 내장 Control 숨김 여부입니다.

    eturn:

  • No return

get_control_visibility()

설정된 내장 Control 숨김 여부를 반환합니다.

Parameters:

  • No parameter

    eturn:

  • Boolean 내장 Control 숨김 여부입니다.

set_scalemode(scalemode) Flash

Flash Player의 Scalemode를 변경합니다. Flash Player가 아닌 환경에서 호출할 경우 오류를 발생시키진 않지만, Scalemode가 변경되진 않습니다. Scalemode는 다음 4가지 중 하나여야 합니다. (다른 값일 경우는 동작하지 않습니다.)

  • letterbox, stretch, zoom, none

Parameters:

  • scalemode String 설정할 scalemode의 값입니다.

    eturn:

  • No return

get_scalemode() Flash

설정된 Flash Player의 Scalemode를 반환합니다. Flash Player가 아닌 경우는 가장 이전에 호출된 set_scalemode 메소드에서 설정된 값이 반환됩니다.

Parameters:

  • No parameter

    eturn:

  • String 설정된 Scalemode값 입니다.

set_speed(speed) V2 V3 V4

재생 배속을 설정합니다. 배속의 범위는 기본적으로 0.5 <= speed <= 4 입니다. 배속 최대값은 플레이어의 설정에 따라 바뀔 수 있습니다. 또한, 배속은 0.1씩 증가하거나 감소할 수 있습니다. 그보다 작은 단위로 증감할 경우 기대한대로 배속이 증감하지 않을 수 있으니 주의하여 주십시요. 0.5보다 작거나 4보다 큰 값을 입력할 경우는 각각 0.5와 4로 값이 고정됩니다.

Parameters:

  • speed Integer 설정할 배속값 입니다.

    eturn:

  • No return

get_speed() V2 V3 V4

설정된 배속값을 반환합니다. Javascript에는 명시적인 Float형이 존재하지 않으므로, 소수점을 표현하기 위해 String형으로 반환합니다.

Parameters:

  • No parameter

    eturn:

  • String 설정된 배속값입니다. 1이나 2인 경우 각각 문자열 '1.0'과 '2.0'으로 표현합니다.

set_playback_rates(playback_rates) V3 V4

배속값 그룹을 설정합니다. Array type으로 순서는 상관없습니다. (Player 내부에서 Sort하여 UI를 구성합니다.) 이중배열의 형태로 들어가는 경우 UI에서 보여지는 배속값 그룹의 세로 줄 수를 설정 할 수 있습니다. 이 경우 첫번째 인자는 배속값의 배열이며, 두번째 인자는 세로 줄 수를 나타냅니다. ex) [[0.5, 1, 1.5, 2, 3, 4], 2]

Parameters:

  • playback_rates Array 설정할 배속값 그룹의 배열입니다.

    eturn:

  • No return

get_playback_rates() V3 V4

배속값 그룹의 배열을 반환합니다.

Parameters:

  • No parameter

    eturn:

  • Array 설정된 배속값 그룹 배열입니다.

set_topmost(topmost) V2

윈도우 최상위 여부를 설정합니다. 최상위로 설정하면 현재 웹브라우져가 백그라운드 상태가 되어도 항상 다른 윈도우보다 위에 있게 됩니다.

Parameters:

  • No parameter

    eturn:

  • No return

get_topmost() V2

윈도우 최상위 설정을 반환합니다. V2 Player를 제외한 다른 Player에서 호출시 항상 false를 반환합니다.

Parameters:

  • topmost Boolean true는 최상위 설정, false는 최상위 설정 해제입니다.

    eturn:

  • Boolean 윈도우 최상위 설정값 입니다.

set_brightness(brightness) V2

영상의 밝기를 설정합니다. 이 설정은 V2 Player에서만 동작합니다. 영상의 밝기는 -50 <= brightness <= 50입니다. -50보다 작거나 50보다 큰 값을 입력하면 각각 -50과 50으로 재조정됩니다.

Parameters:

  • brightness Integer 영상 밝기값 입니다.

    eturn:

  • No return

get_brightness() V2

설정된 영상 밝기값을 반환합니다. V2 Player가 아닌 경우 이 메소드를 호출하면 무조건 0을 반환합니다.

Parameters:

  • No parameter

    eturn:

  • Integer 설정된 영상 밝기값 입니다.

set_contrast(contrast) V2

영상의 대비를 설정합니다. 이 설정은 V2 Player에서만 동작합니다. 영상의 대비는 -50 <= contrast <= 50입니다. -50보다 작거나 50보다 큰 값을 입력하면 각각 -50과 50으로 재조정됩니다.

Parameters:

  • contrast Integer 영상 대비값 입니다.

    eturn:

  • No return

get_contrast() V2

설정된 영상 대비값을 반환합니다. V2 Player가 아닌 경우 이 메소드를 호출하면 무조건 0을 반환합니다.

Parameters:

  • No parameter

    eturn:

  • Integer 설정된 영상 대비값 입니다.

set_saturation(saturation) V2

영상의 색조를 설정합니다. 이 설정은 V2 Player에서만 동작합니다. 영상의 색조는 -50 <= saturation <= 50입니다. -50보다 작거나 50보다 큰 값을 입력하면 각각 -50과 50으로 재조정됩니다.

Parameters:

  • saturation Integer 영상 색조값 입니다.

    eturn:

  • No return

get_saturation() V2

설정된 영상 색조값을 반환합니다. V2 Player가 아닌 경우 이 메소드를 호출하면 무조건 0을 반환합니다.

Parameters:

  • No parameter

    eturn:

  • Integer 설정된 영상 색조값 입니다.

set_repeat_start([position])

구간반복의 시작 위치를 설정합니다. 인자 없이 호출하면 현재 위치를 구간반복의 시작 위치로 설정합니다.

controller.set_repeat_start();


인자로 위치(초)값을 입력하면 지정한 위치를 구간반복의 시작 위치로 설정합니다.

controller.set_repeat_start(10); // 10초 위치를 시작 위치로 설정


만약 먼저 설정된 종료 위치보다 시작 위치가 나중이라면 종료 위치가 해제됩니다.

Parameters:

  • position Integer (Optional) 시작 위치값 입니다.

    eturn:

  • No return

set_repeat_end([position])

구간반복의 종료 위치를 설정합니다. 인자 없이 호출하면 현재 위치를 구간반복의 종료 위치로 설정합니다.

controller.set_repeat_end();
인자로 위치(초)값을 입력하면 지정한 위치를 구간반복의 종료 위치로 설정합니다.
controller.set_repeat_end(20); // 20초 위치를 종료 위치로 설정


만약 먼저 설정된 시작 위치보다 종료 위치가 먼저라면 시작 위치가 해제됩니다.

Parameters:

  • position Integer (Optional) 종료 위치값 입니다.

    eturn:

  • No return

unset_repeat()

설정된 구간반복을 해제합니다.

Parameters:

  • No parameter

    eturn:

  • No return

refresh_bookmark()

플레이어 내 bookmark 리스트를 새로 갱신합니다.

Parameters:

  • No parameter

    eturn:

  • No return

enable_fullscreen_button() V3 V4

플레이어 내부의 fullscreen button을 활성화시킵니다. (IE 10 이하는 웹브라우져에서 fullscreen 기능을 지원하지 않으므로, 해당 웹브라우져에선 자동적으로 fullscreen button이 비활성화된 상태로 표시됩니다.)

Parameters:

  • No parameter

    eturn:

  • No return

get_player_id() V2 V3

플레이어 고유 아이디를 반환합니다. 이 함수는 ready 이벤트가 호출되기 전까지는 null을 리턴합니다.

Parameters:

  • No parameter

    eturn:

  • String 플레이어 고유 아이디입니다.

get_hardware_id() V2 V3

하드웨어 고유 아이디를 반환합니다. 이 함수는 ready 이벤트가 호출되기 전까지는 null을 리턴합니다.

Parameters:

  • No parameter

    eturn:

  • String 하드웨어 고유 아이디입니다.

set_subtitle_visibility(visibility)

자막 출력을 설정합니다.

Parameters:

  • visibility Boolean 출력 여부입니다.

    eturn:

  • No return

get_video_info() Flash V4

미디어의 width, height, bitrate값을 반환합니다. 이 함수는 ready 이벤트가 호출되기 전까지는 null을 리턴합니다.

Parameters:

  • No parameter

    eturn:

  • Object width, height, bitrate를 property로 갖는 Object를 반환합니다.

이벤트 목록

loaded

플레이어 로딩이 완료되면 이벤트가 발생합니다.

ready

플레이어 로딩이 끝나고 재생 정보를 서버로부터 획득하였으며, 실제 재생준비가 완료된 시점입니다.

play

재생 시작시에 발생합니다. 초기 재생 시작을 제외하고 일시 멈춤 상태에서 다시 재생을 시작할때도 발생합니다.

progress

재생시 매초마다 발생합니다.

controller.on('progress', function(percent, position, duration) {
	// 인자의 순서는 위와과 같습니다.
});


단, V3, V4 Player의 경우 HTML5 Video Player의 구조상 progress 이벤트가 정확하게 1초마다 발생하지 않을수 있습니다. (0.1에서 최대 0.5초 가량 차이가 날 수도 있습니다.) V3, V4 Player와 관련하여 progress 이벤트로 작업하실 경우 이 부분을 유념하여 주십시요.

Parameters:

  • percent Integer 진행 백분율입니다. 값의 범위는 0 <= percent <= 100 입니다.
  • position Integer 현재 재생중인 위치의 값입니다. 초단위입니다.
  • duration Integer 동영상의 전체 재생 길이입니다. 초단위입니다.

pause

일시 정지시에 발생합니다.

done

재생 완료시에 발생합니다. 재생 완료는 duration의 끝까지 모두 재생한 경우를 의미합니다.

muted Flash V3 V4

음소거 상태가 변경시 호출됩니다. (음소거시, 음소거 해제시 모두 발생)

controller.on('muted', function(is_muted) {
	// is_muted가 true면 음소거, false면 해제입니다.
});


다만, V2 Player의 경우 현재 muted 이벤트를 제공하지 않습니다. 대신 음소거가 되는 경우 volumechange 이벤트가 발생되고 변경된 음량을 0으로 제공합니다.

Parameters:

  • is_muted Boolean true면 음소거, false면 음소거 해제입니다.

scalemodechange Flash

스케일모드가 변경시 발생합니다.

controller.on('scalemodechange', function(scalemode) {
// ...
});


스케일모드는 Flash Player에만 존재하는 기능입니다. 다른 Player에서는 이벤트를 발생시키지 않습니다. 파라미터로는 다음의 4가지 문자열 가운데 하나를 제공합니다.

  • letterbox, stretch, zoom, none

Parameters:

  • scalemode String letterbox, stretch, zoom, none 가운데 하나입니다.

topmostchange V2

화면 최상위 설정 변경시 발생합니다.

controller.on('topmostchange', function(is_topmost) {
	// is_topmost가 true면 최상위 설정, false면 최상위 설정 해제입니다.
});


화면 최상위 설정은 V2 Player에만 존재하는 기능입니다. 다른 Player에서는 이벤트를 발생시키지 않습니다.

Parameters:

  • is_topmost Boolean true면 최상위 설정, false면 최상위 설정 해제입니다.

screenchange

전체, 일반화면 변경시 발생합니다.

  • IE10 이하의 브라우져의 경우, enable_fullscreen_button()이 활성화 되어 있는 상태라면, fullscreen 버튼 클릭시 실제 fullscreen/windowed 전환이 이루어 지지는 않지만 screenchange 이벤트는 정상적으로 반환이 됩니다.

    controller.on('screenchange', function(screen) {
	// ...
});

screen 파라미터는 다음의 2가지 문자열 가운데 하나를 제공합니다. screen: windowed, fullscreen

Parameters:

  • screen String windowed는 일반화면, fullscreen은 전체화면입니다.

volumechange

음량 변경시 발생합니다.

controller.on('volumechange', function(volume) {
	// volume의 범위는 0 <= volume <= 100 입니다.
});


Parameters:

  • volume Integer 변경된 음량입니다. 범위는 0 <= volume <= 100 입니다.

speedchange V2 V3 V4

배속 변경시 발생합니다. 배속 최대값은 Player의 설정에 따라 바뀔 수 있습니다.

controller.on('speedchange', function(speed) {
	// speed의 범위는 0.5 <= speed <= 4 입니다.
});


Parameters:

  • speed String 변경된 배속입니다. 범위는 0.5 <= speed <= 4 입니다. Javascript 언어 특성상 2.0은 2로 표기 되기 때문에, Integer형 대신에 String형을 사용해 제공합니다.

videosettingchange V2

비디오 속성 변경시 발생합니다.

controller.on('videosettingchange', function(videosetting) {
    // videosetting 파라미터는 다음의 형태로 표시되는 Object 타입입니다.
    //
    // {
        // "brightness": 0,
        // "contrast": 0,
        // "saturation": 0
    // }
});



비디오 속성 변경 기능은 V2 Player에만 존재하는 기능입니다. 다른 Player에서는 이벤트를 발생시키지 않습니다. 각 값의 범위는 모두 -50 <= value <= 50의 범위를 갖습니다. 사용자가 별도로 지정하지 않았을 경우 기본값은 0 입니다.

Parameters:

  • videosetting Object brightness(밝기), contrast(대비), saturation(채도)를 property로 갖는 object입니다.

jumpstepchange

ff, rw 메소드를 통해 이동할 시간값 변경시 발생합니다.

controller.on('jumpstepchange', function(jumpstep) {
	// jumpstep은 초단위입니다.
});



Parameters:

  • jumpstep Integer 변경된 이동할 시간값입니다. 초단위입니다.

html5_video_supported V3 V4

V3, V4 Player에서만 발생합니다. Player가 내부에서 HTML5 Video 재생기능을 사용할 수 있다고 판단하여 HTML5 Video Player를 로드할 경우 엔 true를, 전용 플레이어를 재생해야 한다고 판단할 경우엔 false를 리턴합니다. (http://caniuse.com/#feat=video 참조)

Parameters:

  • html5_video_supported Boolean Player가 HTML5 Player로 로드될 경우 true, 전용 플레이어로 로드될 경우는 false가 리턴됩니다.

error

Player가 재생오류를 반환하는 경우 발생합니다.

controller.on('error', function(error_code) {
	// ...
});


Parameters:

  • error_code Integer Kollus Player 에러 코드입니다.



  • No labels

Copyright © CATENOID, lnc. All Rights Reserved.
E-mail. jp_sales@catenoid.net | Tel. 03-4405-8462