Video player API for JavaScript
Control the Kinescope player embedded on your page: play, seek, change speed and quality, switch subtitles and playlists, and react to what the viewer does.
Quick start
Install @kinescope/player-iframe-api-loader and control your first video. Code from the package README and the API types.
-
Install the loader
The loader fetches the IFrame API and ships TypeScript types for every method and event.
npm install @kinescope/player-iframe-api-loader -
Create the player
Pass an element or its ID and the video link.
sizeandbehaviorare optional.import * as iframeApiLoader from '@kinescope/player-iframe-api-loader'; const factory = await iframeApiLoader.load(); const player = await factory.create('player', { url: 'https://kinescope.io/VIDEO_ID', size: { width: '100%', height: 400 }, }); -
Call methods and listen to events
Every method returns a Promise. Subscribe with
on,onceandoff.player.on(player.Events.Ended, () => { console.log('Lesson finished'); }); await player.seekTo(90); await player.setPlaybackRate(1.5); await player.play();
Control the player from your code
A real Kinescope player. Each button calls an IFrame Player API method, the panel shows the code that ran, and the log shows the events the player sends back.
- currentTime
- 0
- paused
- true
- playbackRate
- 1
- quality
- —
- volume
- 1
- muted
- false
Playback
Speed
Quality
Sound
Subtitles
import { load } from '@kinescope/player-iframe-api-loader'; const factory = await load(); const player = await factory.create('player', { url: 'https://kinescope.io/56Jg27MqvvttAwHcrCzEA4', size: { width: '100%', height: '100%' }, }); player.on(player.Events.TimeUpdate, ({ data }) => { console.log(data.currentTime, data.percent); });// Click a button on the left to run a call
- Events appear here once the player loads.
Every method and event is in the IFrame Player API docs.
Methods you’ll use most
Method
What it does
Returns
play() · pause()Start or pause playback.
Promise
seekTo(time)Jump to a second, for example to resume a lesson.
Promise
getCurrentTime()Where the viewer is now, in seconds.
Promise<number>
getDuration()Length of the video, in seconds.
Promise<number>
setPlaybackRate(value)Change speed, for example 1.5.
Promise
setVideoQuality(q)Fix a quality, such as 720p.
Promise
enableTextTrack(lang)Turn on subtitles in a language.
Promise
setFullscreen(on)Enter or leave fullscreen.
Promise
switchTo(id) · next()Change the video in a playlist.
Promise
setOptions(options)Change player options on the fly, such as the watermark.
Promise
All 33 methods
Events
Event
When it fires
Use it to
LoadedThe player and video are ready.
Call methods safely after it.
Play · PauseThe viewer starts or pauses.
Sync your own buttons.
TimeUpdatePlayback position changes.
Save lesson progress.
EndedThe video reaches the end.
Mark a lesson as watched, open the next one.
QualityChangedThe quality switches.
Log what viewers actually get.
CallActionA viewer clicks a call to action.
Count clicks or open a form.
ErrorPlayback fails.
Show your own message or report it.
Subscribe
player.on(Events.Ended, fn)Also
once and off.Documentation and code
FAQ
Can’t find the answer you need? Check out our Player docs.
A JavaScript API for a video player embedded in an iframe: your page calls methods such as play, seek or change quality, and the player sends back events such as playing, paused or ended. It is how you build custom controls, lesson progress tracking or interactive video on top of an embedded player.
Install
@kinescope/player-iframe-api-loader, call load() to get the player factory, create the player with factory.create(element, { url }), then call its methods and subscribe to events with player.on(player.Events.Ended, handler). The quick start on this page has the code.Yes. Listen to
Ended for the end of the video and to TimeUpdate for the current position, then save progress on your backend. getCurrentTime() and getDuration() return the values on demand.No. The loader replaces the
onKinescopeIframeAPIReady callback and adds TypeScript types. If the IFrame API script is already on the page, use window.Kinescope.IframePlayer directly; the types are available on their own from @kinescope/player-iframe-api-loader/types.Yes. The React, Vue and Angular player components wrap the same API with props and events; see the React and Vue SDK pages linked above. On iOS, Android and Flutter, use the native SDKs.
The Player API comes with the player at no extra cost. You pay for video hosting and delivery: a free plan to start, then paid plans from €10 a month.