use-captions

Installation

Install the hook

npx shadcn add @limeplay/use-captions

Add Event & Action Bridge

Import the useCaptionsStates hook in your existing PlayerHooks component.

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

Add the Store States

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
}

Example Usage

Use the useCaptions() hook to control captions in your components.

components/player/captions-control-button.tsx

import { useCaptions } from "@/hooks/limeplay/use-captions"
import { useMediaStore } from "@/components/limeplay/media-provider"

export function CaptionsControlButton() {
  const textTrackVisible = useMediaStore((state) => state.textTrackVisible)
  const { toggleCaptionVisibility } = useCaptions()

  return (
    <button onClick={toggleCaptionVisibility}>
      {textTrackVisible ? "Hide" : "Show"} Captions
    </button>
  )
}

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.

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

On this page