Pular navegação
Atualizado: 12.08.2026

Este componente incorpora o Kinescope Player em aplicações React. Ele usa um iframe e a IFrame API internamente. Repositório: kinescope/react-kinescope-player.

Instalação

npm install @kinescope/react-kinescope-player --save

Início rápido

import React from 'react'
import KinescopePlayer from '@kinescope/react-kinescope-player'

function Player() {
  return <KinescopePlayer videoId="VIDEO_ID" />
}

export default Player

Eventos

function onTimeUpdate({ currentTime }) {
  console.log(currentTime)
}

<KinescopePlayer videoId="VIDEO_ID" onTimeUpdate={onTimeUpdate} />

Métodos

Use uma ref:

const playerRef = React.createRef()

function handleMuteClick() {
  playerRef.current.mute()
}

<>
  <KinescopePlayer ref={playerRef} videoId="VIDEO_ID" />
  <button onClick={handleMuteClick}>Silenciar</button>
</>

Next.js

O componente usa APIs do navegador. Por isso, desative a renderização no servidor (SSR):

import dynamic from 'next/dynamic'

const KinescopePlayer = dynamic(
  () => import('@kinescope/react-kinescope-player'),
  { ssr: false }
)

export default function Player() {
  return <KinescopePlayer videoId="VIDEO_ID" />
}

Props

PropTipoPadrãoObrigatória
videoIdstring | string[]—sim
classNamestring—não
queryQuery—não
styleany—não
preloadboolean | 'none' | 'metadata' | 'auto'falsenão
titlestring—não
subtitlestring—não
posterstring—não
chaptersChapter[]—não
vttVtt[]—não
widthnumber | string100%não
heightnumber | string100%não
autoPlayboolean | 'viewable'falsenão
autoPauseboolean | 'reset'truenão
loopbooleanfalsenão
playsInlinebooleantruenão
mutedbooleanfalsenão
language'en' | 'ru'automáticonão
controlsbooleantruenão
mainPlayButtonbooleantruenão
playbackRateButtonbooleanfalsenão
textTrackboolean | stringtruenão
externalIdstring—não
drmAuthTokenstring—não
callToActionCallToAction[]—não
bookmarksBookmark[]—não
watermarkWatermark—não
playlistOptionsPlaylistOptions—não
themeTheme—não
localStorageLocalStoragetruenão

Tipos das props

Chapter

type Chapter = {
  position: number
  title: string
}

Query

type Query = {
  seek?: number
  duration?: number
  playerId?: string
}

LocalStorage

type LocalStorage =
  | boolean
  | {
      quality?: 'item' | 'global' | boolean
      time?: boolean
      textTrack?: 'item' | 'global' | boolean
    }

Vtt

type Vtt = {
  label: string
  src: string
  srcLang: string
}

CallToAction

type CallToAction = {
  id: string
  title: string
  description?: string
  skipable?: boolean
  buttonStyle?: object
  trigger: {
    percentages: number[]
    timePoints: number[]
    pause: boolean
  }
}

Bookmark

type Bookmark = {
  id: string
  time: number
  title?: string
}

Watermark

type Watermark =
  | string
  | {
      text: string
      mode?: 'random' | 'stripes'
      scale?: number
      displayTimeout?: number | { visible: number; hidden: number }
    }

PlaylistOptions

type PlaylistOptions = {
  autoSwitch?: boolean
  initialItem?: string
  loop?: boolean
}

Theme

type Theme = {
  subtitles?: {
    /** Base font size in em. */
    textScale: number
    textAlign: 'left' | 'center'
    textLength: 'auto' | number
  }
}

Eventos

EventoDados
onJSLoad—
onJSLoadError—
onInit{ playerId: string }
onInitErrorError
onReady{ currentTime, duration, quality }
onQualityChanged{ quality }
onCurrentTrackChanged{ item: { id?: string } }
onSeekChapter{ position: number }
onSizeChanged{ width, height }
onPlay—
onPlaying—
onWaiting—
onPause—
onEnded—
onTimeUpdate{ currentTime: number }
onProgress{ bufferedTime: number }
onDurationChange{ duration: number }
onVolumeChange{ muted, volume }
onPlaybackRateChange{ playbackRate: number }
onSeeked—
onFullscreenChange{ isFullscreen, video }
onPipChange{ isPip: boolean }
onCallAction{ id, title?, type }
onCallBookmark{ id, time, title? }
onError{ error: unknown }
onDestroy—

Métodos

Chame os métodos por uma ref, por exemplo, playerRef.current.play().

MétodoParâmetrosResultado
isPaused—Promise<boolean>
isEnded—Promise<boolean>
play—Promise<void>
pause—Promise<void>
stop—Promise<void>
getCurrentTime—Promise<number>
getDuration—Promise<number>
seekTo(time: number)Promise<void>
isMuted—Promise<boolean>
mute—Promise<void>
unmute—Promise<void>
getVolume—Promise<number>
setVolume(value: number)Promise<void>
getPlaybackRate—Promise<number>
setPlaybackRate(value: number)Promise<void>
getVideoQualityList—Promise<VideoQuality[]>
getVideoQuality—Promise<VideoQuality>
setVideoQuality(quality: VideoQuality)Promise<void>
enableTextTrack(lang: string)Promise<void>
disableTextTrack—Promise<void>
closeCTA—Promise<void>
isFullscreen—Promise<boolean>
setFullscreen(fullscreen: boolean)Promise<void>
isPip—Promise<boolean>
setPip(pip: boolean)Promise<void>
getPlaylistItem—Promise<{ id?: string } | undefined>
switchTo(id: string)Promise<void>
next—Promise<void>
previous—Promise<void>

Consulte Controlar o player para ver a lista completa de métodos da IFrame API.

Próximos passos