Web Player Controller

Notice

This document is a machine-translated draft and is currently undergoing review. Some content may be inaccurate or differ from the original Korean version. For the most precise information, refer to the Korean documentation.

Web Player Controller (formerly VG Controller) is a JavaScript library that communicates with the Kollus Player embedded via iframe on a customer's website, enabling you to control playback state or receive real-time events.

Key features

Unified control: Control all player types with a single specification.
Standalone operation: Operates independently without any external library dependencies.
Event-driven architecture: Supports method calls and real-time event listener structures.

Terminology

Definitions of key technical terms and player notation used in this document. (Learn more: Kollus Player Types)

Term	Description
Video Gateway	A server that delivers playback data and authentication information upon viewer request
Player ID	Unique ID of the Kollus Player
Hardware ID	A hardware-specific unique ID provided when an identifiable value exists, such as in Windows environments
HLS Fragment	The minimum unit media segment file that divides the entire video during playback based on the HLS (HTTP Live Streaming) protocol
v3	HTML5 Player for PC (hybrid): A hybrid HTML5 player applied when playing encrypted content on Microsoft Edge or Chrome 45 and above
v4	HTML5 Player for All: A plugin-less HTML5 player exclusively for standard (unencrypted) content
v5	Web Player: A next-generation integrated web player combining the advantages of both installed and plugin-less players

Library installation and initialization

Load the client script, then specify the control target (iframe) to create an instance.

Basic implementation example

<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>

Notes

Target specification: The target_window property must receive the contentWindow object of the iframe element.
Browser compatibility: This library uses the window.postMessage API for communication. Operation is limited in browsers that do not support this API.
Multiple player control: If multiple players (iframe) exist on a page, a separate instance must be created for each iframe ID.

Exception codes

Error codes that may occur during initialization and communication.

Code	Message	Description
`-99`	This browser does not support postMessage API	Browser does not support postMessage API
`-98`	Player type must be one of v2, v3, v4 and v5	Invalid player type (only v2, v3, v4, and v5 are supported)
`-97`	Event listener is not callable	Event listener is not callable (not a valid function)
`-96`	Target window is not found	Target Window object not found
`-95`	Custom skin is not supported	Custom skin is not supported
`-1`	*	Other postMessage API exceptions

CDN path

Web Player Controller is provided via CDN.

Script path change

'VG Controller' has been renamed to 'Web Player Controller'. While the legacy path will remain supported, new feature updates will be limited. We recommend updating to the new path to ensure ongoing support for the latest features and improvements.

Legacy Path: https://file.kollus.com/vgcontroller/vg-controller-client.{version}.min.js
New Path: https://file.kollus.com/wpcontroller/web-player-controller-client.{version}.min.js

Auto-apply latest version

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

Pin a specific version

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

Security hardening (SRI)

It is recommended to use the SRI (Subresource Integrity) attribute to prevent library tampering.

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

Version-specific integrity codes

Version	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=

Event listening

Use the controller.on() method to receive player state changes and playback events in real time.

Listener registration methods

Single listener

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

Multiple listeners

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

You can implement consecutive event registration with concise code.

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

Listener execution order

Due to the nature of the JavaScript asynchronous environment, the execution order of multiple listeners registered for the same event is not guaranteed.

Recommendation: Write logic that requires a strict execution order sequentially within a single listener.

Event list

Playback status events

Event	Description	Supported players
`loaded`	Fired when the player components have finished loading	v3, v4, v5
`ready`	Fired when playback data has been received from the server and the player is ready to play	v3, v4, v5
`play`	Fired when playback starts for the first time or resumes after being paused	v3, v4, v5
`pause`	Fired when playback is paused	v3, v4, v5
`done`	Fired when the playback position reaches the end of the total length (`duration`)	v3, v4, v5
`waiting`	Fired at 1-second intervals until recovery when additional buffering is required due to network conditions	v4, v5

Progress events

Caution

Depending on HTML5 browser performance and network conditions, the progress event may have a margin of approximately 0.1–0.5 seconds rather than firing at exactly 1-second intervals.

Event	Description	Supported players
`progress`	Fired at approximately 1-second intervals during playback, delivering the current playback position	v3, v4, v5

Progress parameter details

Parameter	Type	Description
`percent`	`integer`	Current playback progress (0 to 100)
`position`	`number`	Current playback position (sec)
`duration`	`number`	Total content duration (sec)

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

Seek events

Event	Description	Supported players
`seeking`	Fired when the user starts moving the playback position	v4, v5
`seeked`	Fired when the playback position move is complete	v4, v5
`seek_start`	Fired at the first moment a playback position move is detected	v4, v5
`jumpstepchange`	Fired when the time unit for seek (fast-forward/rewind) changes	v3, v4, v5

Audio events

Event	Description	Supported players
`muted`	Fired when the mute state (on/off) changes	v3, v4, v5
`volumechange`	Fired when the volume level changes	v3, v4, v5

Muted parameter details

Parameter	Type	Description
`is_muted`	`boolean`	`true`: Mute applied `false`: Mute released

Volumechange parameter details

Parameter	Type	Description
`volume`	`integer`	Changed volume level (0 to 100)

playback speed events

Event	Description	Supported players
`speedchange`	Fired when the playback speed changes	v3, v4, v5
`playbackrateschange`	Fired when the available playback speed group changes	v3, v4, v5

Speedchange parameter details

Parameter	Type	Description
`speed`	`string`	Changed playback speed (0.5 to 4)

Screen and UI events

Event	Description	Supported players
`screenchange`	Fired when switching between fullscreen mode and normal mode	v3, v4, v5
`picture_in_picture_entered`	Fired when PIP (Picture-in-Picture) mode is entered	v3, v4, v5
`picture_in_picture_leaved`	Fired when PIP mode is exited	v3, v4, v5
`device_orientation_changed`	Fired when the mobile screen orientation (landscape/portrait) changes	v4, v5
`user_active_changed`	Fired when the control bar activation/deactivation state changes due to user interaction	v4, v5
`custom_skin_changed`	Fired when the custom skin is changed	v4, v5

Screenchange parameter details

Parameter	Type	Description
`screen`	`string`	`windowed`: Normal mode `fullscreen`: Fullscreen mode

Device_orientation_changed parameter details

Parameter	Type	Description
`orientation`	`string`	`Portrait`: Portrait orientation `Landscape`: Landscape orientation

Subtitle events

Event	Description	Supported players
`subtitle_load_done`	Fired when subtitle file loading is complete	v3, v4, v5
`subtitle_list_change`	Fired when the main subtitle list changes	v5
`subtitle_sub_list_change`	Fired when the sub subtitle list changes	v5
`subtitle_cue_data_change`	Fired when subtitle Cue data changes	v5
`subtitlevisibilitychange`	Fired when main subtitle visibility (on/off) changes	v3, v4, v5
`subtitle_sub_visibilitychange`	Fired when sub subtitle visibility (on/off) changes	v3, v4, v5
`subtitle_sizechange`	Fired when main subtitle font size changes	v3, v4, v5
`subtitle_sub_sizechange`	Fired when sub subtitle font size changes	v3, v4, v5
`subtitle_shadow_rect_change`	Fired when main subtitle background style changes	v3, v4, v5
`subtitle_sub_shadow_rect_change`	Fired when sub subtitle background style changes	v3, v4, v5

Streaming events

Event	Description	Supported players
`streaming_manifest_loaded`	Fired when HLS or DASH manifest file loading is complete	v5
`hls_manifest_loaded`	Fired when HLS manifest file loading is complete (recommended to use `streaming_manifest_loaded`)	v4, v5
`dash_manifest_loaded`	Fired when DASH manifest file loading is complete (recommended to use `streaming_manifest_loaded`)	v4, v5
`streaming_frag_changed`	Fired when streaming fragment changes	v5
`hlsfragchange`	Fired when HLS fragment changes (recommended to use `streaming_frag_changed`)	v4, v5
`bitrate_data_loaded`	Fired when bitrate data loading is complete (sorted in ascending order)	v4, v5

Bitrate_data format example

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

Other events

Event	Description	Supported players
`error`	Called when a system error occurs during playback	v3, v4, v5
`html5_video_supported`	Called when checking whether the browser supports HTML5 Video	v3, v4, v5
`repeat_stat_change`	Fired when the section repeat status changes	v3, v4, v5
`bookmark_change`	Fired when a bookmark is added or modified (also triggered on deletion for v3)	v3, v4, v5
`next_episode_auto_change`	Fired when the auto-play next episode setting changes	v3, v4, v5
`next_episode_requested`	Fired when a next episode callback is requested	v3, v4, v5
`chapter_data_change`	Fired when chapter data changes	v5

Repeat_stat_change example

controller.on('repeat_stat_change', function (data) {
  // - end: Section repeat end point (sec)
  // - start: Section repeat start point (sec)
  // - status: Section repeat status
});

Method usage

You can directly control the player's behavior using the object created through the Controller instance.

Basic call method

Control commands that do not require separate arguments call the method directly.

controller.play();

Parameter passing method

Control commands that require configuration values pass parameters as method arguments.

controller.set_volume(90);

Method list

Event listener methods

Method	Description	Supported players
`on(event_name, callback)`	Register an event listener Parameters `event_name` (`string`): event name `callback` (`function`): function to be called when the event is fired Return value: `WebPlayerControllerClient` instance	v3, v4, v5
`once(event_name, callback)`	Register an event listener that executes only once	v3, v4, v5
`off(event_name)`	Remove all listeners registered for a specific event at once	v3, v4, v5

Playback methods

Method	Description	Supported players
`play([start_at])`	Start playback Parameters (optional) `start_at` (`integer`, sec): Start playback immediately from the specified position Call examples Start playback: `controller.play();` Play from 10 seconds: `controller.play(10);`	v3, v4, v5
`pause()`	Pause the currently playing content	v3, v4, v5
`get_progress()`	Return current playback information (`percent, position, duration`)	v3, v4, v5
`get_next_episode_auto()`	Returns whether autoplay for the next episode is enabled (`boolean`)	v3, v4, v5
`set_next_episode_auto(is_auto)`	Set whether to enable autoplay for the next episode Parameters `is_auto` (`boolean`): whether to enable autoplay	v3, v4, v5

Seek methods

Method	Description	Supported players
`ff()`	Move forward by the `jumpstep` value set with the `set_jumpstep` method from the current playback position (fast forward, default: 10 seconds)	v3, v4, v5
`rw()`	Move backward by the `jumpstep` value set with the `set_jumpstep` method from the current playback position (rewind, default: 10 seconds)	v3, v4, v5
`set_current_time(time)`	Move to the specified position while maintaining the current playback state Parameters `time` (`integer`, sec): position to move to	v3, v4, v5
`get_current_time()`	Return the current playback position	v3, v4, v5
`set_jumpstep(jumpstep)`	Set the time interval to move when `ff()` or `rw()` is called Parameters `jumpstep` (`integer`, sec): time interval to move	v3, v4, v5
`get_jumpstep()`	Return the currently configured `jumpstep` value	v3, v4, v5
`set_keyframe_seek_default(is_default)`	Set keyframe-based seeking as the default Parameters `is_default` (`boolean`): whether to set as default	v2

Comparison: play([start_at]) vs set_current_time(time)

play(10): Move to the 10-second position and start playback immediately
set_current_time(10): Move to the 10-second position, but maintain the current play/pause state

Audio methods

Method	Description	Supported players
`get_volume()`	Return the current volume level	v3, v4, v5
`set_volume(volume)`	Set volume Parameters `volume` (`integer`, 0 to 100): volume to set	v3, v4, v5
`mute()`	Toggle mute state (on/off)	v3, v4, v5

Screen methods

Method	Description	Supported players
`toggle_pip()`	Toggle PIP(Picture-in-Picture) mode activation state	v3, v4, v5
`get_screen()`	Return the current screen mode Return value `windowed`: Normal mode `fullscreen`: Fullscreen mode	v3, v4, v5
`set_screen()`	Toggle between fullscreen mode and normal mode (not supported in Firefox)	v3, v4, v5
`set_fullscreen_element(element)`	Sets the target DOM element for switching to fullscreen Parameters `element` (`string`):Target HTML element for fullscreen transition	v3, v4, v5
`enable_virtual_fullscreen()`	When the fullscreen button is clicked, toggles the UI and triggers only the `screenchange` event without actually entering fullscreen mode (This feature is disabled when `set_fullscreen_element()` is executed)	v5
`get_video_visibility()`	Return the current visibility state of the video display	v3, v4, v5
`set_video_visibility(visibility)`	Show or hide the video display (audio playback continues) `visibility` parameter details `true`: Show `false`: Hide	v3, v4, v5
`set_ratio(type)`	Set the screen zoom and aspect ratio mode `type` parameter details `contain`: Fit within the screen while maintaining the aspect ratio `fill`: Fill the entire screen regardless of aspect ratio `enlargement`: Fit based on the vertical height (horizontal scrolling may occur)	v3, v4, v5

Deprecated

The following methods are no longer maintained. Please use the alternative methods.

enable_fullscreen_button() ➔ enable_virtual_fullscreen()

Control bar methods

Method	Description	Supported players
`set_control_visibility(visibility)`	Set whether the built-in control bar is visible	v3, v4, v5
`get_control_visibility()`	Return the current visibility state of the built-in control bar	v3, v4, v5
`set_controls_inactive_time(time)`	Set the auto-hide wait time for the control bar (`0`: always visible)	v3, v4, v5
`get_controls_inactive_time()`	Return the configured auto-hide wait time for the control bar	v3, v4, v5
`set_controls_activity(activity)`	Set whether the control bar is active	v3, v4, v5
`get_controls_activity()`	Return the activation state of the control bar	v3, v4, v5
`set_controlbar_progress_only(enable)`	Show only the progress bar and hide all other control buttons	v3, v4, v5
`get_controlbar_progress_only()`	Return whether the progress bar is shown exclusively	v3, v4, v5
`set_controlbar_hide_playing(enable)`	Set whether the control bar is automatically hidden during playback	v4, v5
`get_controlbar_hide_playing()`	Return whether the control bar auto-hide during playback is enabled	v4, v5
`hide_controlbar_button(value)`	Hide a button from the control bar (recommended to call after the `ready` event) `value` parameter details `play`: play `rewind`: rewind `forward`: fast forward `repeat`: loop section `currenttime`: current playback time `durationtime`: total playback time `quality`: video quality `playbackrate`: playback speed `mute`: mute `volume`: volume graph `subtitle`: subtitle `setting`: settings `fullscreen`: full screen mode `chat`: chatting `pip`: PIP mode `bigplay`: center play button (Kollus Web Player) `seekcontainer`: mobile left/right rewind/fast forward (Kollus Web Player)	v3, v4, v5
`set_setting_panel_activity(activity)`	Set whether to display the settings panel and specify the panel `activity` parameter details `true`: show `false`: hide `panel name`: show the panel with the specified name	v3, v4, v5

Hide_controlbar_button method call example

Hides the full screen mode and settings buttons from the control bar.

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

playback speed methods

Method	Description	Supported players
`set_speed(speed)`	Set playback speed in increments of 0.1 within the range of 0.5–4	v3, v4, v5
`get_speed()`	Return the currently applied playback speed as a string	v3, v4, v5
`set_playback_rates(rates)`	Set the playback speed group displayed in the player UI (refer to the method call example below)	v3, v4, v5
`get_playback_rates()`	Return the currently configured playback speed group as a string	v3, v4, v5

Set_playback_rates method call examples

Single array: Configure playback speed options in a single row.

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

Double array: [playback speed array, number of rows to display]

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

Note

When watching via HLS on iOS, only up to 2x playback speed is supported due to OS policies and technical specifications.

loop section methods

Method	Description	Supported players
`set_repeat_start([position])`	Sets the loop section start point (if the argument is omitted, the current playback position is used)	v3, v4, v5
`set_repeat_end([position])`	Sets the loop section end point (if the argument is omitted, the current playback position is used)	v3, v4, v5
`unset_repeat()`	Deactivates the active loop section setting and switches to normal playback mode	v3, v4, v5
`get_repeat()`	Returns the current loop section status information (`status, start, end`)	v3, v4, v5

Set_repeat method call examples

Sets the 10-second point as the loop start point.

controller.set_repeat_start(10);

Sets the 20-second point as the loop end point.

controller.set_repeat_end(20);

Bookmark methods

Method	Description	Supported players
`refresh_bookmark()`	Synchronizes and updates the latest bookmark list from the server	v3, v4, v5
`get_bookmark_count()`	Returns the number of all bookmarks, official bookmarks, and my bookmarks (`all, index, user`)	v3, v4, v5
`set_bookmark_add_activity(activation)`	Sets whether the add bookmark button is enabled	v3, v4, v5
`set_bookmark_update_activity(activation)`	Sets whether the edit bookmark button is enabled	v3, v4, v5

Deprecated

The following methods are no longer maintained. Please use the alternative methods.

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)

Subtitle methods

Method	Description	Supported players
`set_subtitle(value)`	Directly set subtitle data (VTT URL or RawData)	v3, v4, v5
`get_subtitles_list(type)`	Return the full main subtitle list	v3, v4, v5
`set_current_subtitle(index, type)`	Switch to the main subtitle at the specified index	v3, v4, v5
`set_subtitle_visibility(visibility, type)`	Sets subtitle visibility `visibility`: `true` (show subtitle), `false` (hide subtitle) `type`: `'main'` (main subtitle, default), `'sub'` (sub subtitle)	v3, v4, v5
`get_subtitle_font_size(type)`	Return the current subtitle text size `type` parameter details `'main'` (default): main subtitle `'sub'`: sub subtitle	v3, v4, v5
`set_subtitle_font_size(size, type)`	Set subtitle text size (px)	v3, v4, v5
`get_subtitle_shadow_rect(type)`	Return the current subtitle background style value Return value `true`: opaque rectangle `false`: text outline shadow	v3, v4, v5
`set_subtitle_shadow_rect(is_rect, type)`	Set subtitle background style `is_rect` parameter details `true`: opaque rectangle `false`: text outline shadow `type` parameter details `'main'` (default): main subtitle `'sub'`: sub subtitle	v3, v4, v5
`get_subtitle_activity()`	Return subtitle display position	v3, v4, v5
`set_subtitle_activity(activity)`	Set subtitle display position	v3, v4, v5

Deprecated

The following methods are no longer maintained. Please use the alternative methods.

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)

Chapter methods

Method	Description	Supported players
`set_chapter_data(data)`	Set chapter data	v5
`get_chapter_data()`	Return the currently configured chapter data	v5

The data parameter of set_chapter_data(data) only accepts URL String or JSON format. When chapter data is changed, the Other events event is fired.

// 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"
});

Bitrate methods

Method	Description	Supported players
`set_bitrate(index)`	Switch to the bitrate at the specified index. When requesting an actual change with the `set_bitrate()` method, you must pass the array index +1 as the argument. (`0`: auto)	v4, v5
`get_bitrate_data()`	Return the list of available bitrates. The index of the array returned by `get_bitrate_data()` starts at 0.	v4, v5

Player information methods

Method	Description	Supported players
`get_player_type()`	Returns the current running player type Return value `v3`: HTML5 Player for PC (hybrid) `v4`: HTML5 Player for All	v3, v4, v5
`get_player_id()`	Returns the Kollus Player ID (can be called after the `ready` event)	v3, v4, v5
`get_hardware_id()`	Returns the hardware ID (can be called after the `ready` event)	v3
`get_agent_version()`	Returns the player agent version (can be called after the `ready` event, only valid for encrypted content playback)	v5
`get_video_info()`	Returns content resolution and bitrate information (`width, height, bitrate`) (can be called after the `ready` event)	v3, v4, v5
`get_lms_data(callback)`	Returns LMS data Parameter `callback` (`function`): Callback function that receives the LMS data (`data` object)	v3, v4, v5
`get_streaming_frag_data()`	Returns HLS/DASH Fragment-related data	v5
`get_streaming_manifest_data()`	Returns HLS/DASH Manifest-related data	v5
`dispose()`	Releases player instance and resources	v4, v5

Deprecated

The following methods are no longer maintained. Please use the alternative methods.

get_hls_frag_data() ➔ get_streaming_frag_data()

Custom skin methods

Method	Description	Supported players
`get_custom_skin()`	Returns the custom skin settings (JSON) currently applied to the player (can be called after the `ready` event)	v4, v5
`set_custom_skin(json_data)`	Changes the custom skin by injecting JSON-format settings data (can be called after the `ready` event)	v4, v5

Set_custom_skin method call example

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

Error methods

Method	Description	Supported players
`get_error_detail()`	Returns detailed information (`code, message, param`) about the current error	v3, v4, v5
`set_custom_error(code, message, param)`	Displays developer-defined custom error codes and messages in the player UI instead of the default error screen	v3, v4, v5

Chat methods

Method	Description	Supported players
`set_chat_config(value)`	Apply chat-related settings (recommended to call after the `ready` event)	v3, v4, v5
`notify_visibleheight_changed(height)`	Pass the screen height change value caused by keyboard activation in Android WebView environments	v3, v4, v5

Set_chat_config method call example

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

Note

Security policy: Only URLs with the https protocol are allowed when injecting external pages.
Script restrictions: script tags within content passed via the html attribute are restricted from execution for security reasons.

Close event methods

Method	Description	Supported players
`set_enable_close_event()`	Activate browser close (`close`) detection and callback feature	v3, v4, v5
`set_close_callback_fn(fn)`	Register a custom callback function to execute when the browser is closed	v3, v4, v5
`get_enable_close_event()`	Return whether the browser close (`close`) callback is activated	v3, v4, v5
`set_close_button(enable, fn)`	Create a mobile close button and configure the click event (recommended to call after the `ready` event)	v4, v5

Other methods

Method	Description	Supported players
`set_vr_overlay(options)`	Configure permission request overlay for VR content playback in iOS environments	v3, v4, v5
`debug()`	Output player debug log data to the console	v5
`set_short_key(enable)`	Enable or disable player shortcuts	v2
`get_topmost()`	Return whether the player window is set to display on top	v2
`set_topmost(topmost)`	Set whether the player window is displayed on top	v2
`set_lms_check()`	Configure LMS data transfer completion check when the browser closes	v2

Notes for mobile vr content playback

Due to security policies in mobile browsers and technical constraints of the iframe environment, the following points must be confirmed when playing VR (360°) content.

Android: Due to orientation data synchronization issues within iframe, the left/right control direction of VR video may operate in the opposite direction from the actual device movement.
iOS: Starting from iOS 13, user approval is required to access DeviceMotion (accelerometer/gyro) data for enhanced security. However, due to browser security policies, permission request popups cannot be triggered inside an iframe, causing VR control functionality to not work.

Solution

Use Web Player Controller version 1.1.10 or higher.
In iOS environments, you must call the set_vr_overlay() method.

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

For iOS 13.4 and above, the rotationRate value of the DeviceMotion API is not returned correctly due to Apple's privacy policy.

Key features​

Terminology​

Library installation and initialization​

Basic implementation example​

Notes​

Exception codes​

CDN path​

Auto-apply latest version​

Pin a specific version​

Security hardening (SRI)​

Event listening​

Listener registration methods​

Single listener​

Multiple listeners​

Method chaining​

Event list​

Playback status events​

Progress events​

Progress parameter details​

Seek events​

Audio events​

Muted parameter details​

Volumechange parameter details​

playback speed events​

Speedchange parameter details​

Screen and UI events​

Screenchange parameter details​

Device_orientation_changed parameter details​

Subtitle events​

Streaming events​

Bitrate_data format example​

Other events​

Repeat_stat_change example​

Method usage​

Basic call method​

Parameter passing method​

Method list​

Event listener methods​

Playback methods​

Seek methods​

Comparison: play([start_at]) vs set_current_time(time)​

Audio methods​

Screen methods​

Control bar methods​

Hide_controlbar_button method call example​

playback speed methods​

Set_playback_rates method call examples​

loop section methods​

Set_repeat method call examples​

Bookmark methods​

Subtitle methods​

Chapter methods​

Bitrate methods​

Player information methods​

Custom skin methods​

Set_custom_skin method call example​

Error methods​

Chat methods​

Set_chat_config method call example​

Close event methods​

Other methods​

Notes for mobile vr content playback​

Solution​

Key features

Terminology

Library installation and initialization

Basic implementation example

Notes

Exception codes

CDN path

Auto-apply latest version

Pin a specific version

Security hardening (SRI)

Event listening

Listener registration methods

Single listener

Multiple listeners

Method chaining

Event list

Playback status events

Progress events

Progress parameter details

Seek events

Audio events

Muted parameter details

Volumechange parameter details

playback speed events

Speedchange parameter details

Screen and UI events

Screenchange parameter details

Device_orientation_changed parameter details

Subtitle events

Streaming events

Bitrate_data format example

Other events

Repeat_stat_change example

Method usage

Basic call method

Parameter passing method

Method list

Event listener methods

Playback methods

Seek methods

Comparison: play([start_at]) vs set_current_time(time)

Audio methods

Screen methods

Control bar methods

Hide_controlbar_button method call example

playback speed methods

Set_playback_rates method call examples

loop section methods

Set_repeat method call examples

Bookmark methods

Subtitle methods

Chapter methods

Bitrate methods

Player information methods

Custom skin methods

Set_custom_skin method call example

Error methods

Chat methods

Set_chat_config method call example

Close event methods

Other methods

Notes for mobile vr content playback

Solution