use-captions

Installation

npx shadcn add @limeplay/use-captions

Usage

Basic Setup

Import the useCaptionsStates hook in your existing PlayerHooks component to enable captions functionality.

components/limeplay/player-hooks.tsx

import React from "react"

import { useCaptionsStates } from "@/hooks/limeplay/use-captions"

import { usePlayerStates } from "@/hooks/limeplay/use-player"
import { useShakaPlayer } from "@/hooks/limeplay/use-shaka-player"

export const PlayerHooks = React.memo(() => {
  useShakaPlayer()
  usePlayerStates()
  useCaptionsStates() 

  return null
})

Store Integration

Add the captions store to your media store configuration.

lib/create-media-store.ts

import { create } from "zustand"

import {
  CaptionsStore,
  createCaptionsStore,
} from "@/hooks/limeplay/use-captions"
import { createPlayerStore, PlayerStore } from "@/hooks/limeplay/use-player"
import { createVolumeStore, VolumeStore } from "@/hooks/limeplay/use-volume"

export type TypeMediaStore = PlayerStore & VolumeStore & CaptionsStore & {} 

export function createMediaStore(initProps?: Partial<CreateMediaStoreProps>) {
  const mediaStore = create<TypeMediaStore>()((...etc) => ({
    ...createPlayerStore(...etc),
    ...createVolumeStore(...etc),
    ...createCaptionsStore(...etc),
    ...initProps,
  }))
  return mediaStore
}

API Reference

useCaptionsStates()

Sets up event listeners for text track changes and visibility updates. This hook should be called once in your PlayerHooks component.

useCaptions()

Returns captions control functions for managing text tracks.

Returns

Property	Type	Description
`toggleCaptionVisibility`	`() => void`	Toggles the visibility of captions. Automatically selects a default track if none is active.

Store State

The captions store provides the following state:

Property	Type	Description
`activeTextTrack`	`shaka.extern.TextTrack \| null`	Currently active text track
`textTracks`	`shaka.extern.TextTrack[] \| undefined`	Available text tracks
`textTrackVisible`	`boolean`	Whether captions are currently visible
`textTrackContainerElement`	`HTMLDivElement \| null`	Container element for text track rendering
`setTextTrackContainerElement`	`(element: HTMLDivElement \| null) => void`	Sets the container element for text tracks

Understanding

The use-captions hook provides comprehensive text track management for Shaka Player. It automatically:

Detects available text tracks when media loads
Manages text track visibility state
Provides automatic track selection based on device language
Handles container element setup for proper text rendering

The hook integrates seamlessly with Shaka Player's text track system and provides a clean API for caption controls in your player interface.

On this page