use-timeline

Installation

npx shadcn add @limeplay/use-timeline

import React from "react"

import { usePlaybackStates } from "@/hooks/limeplay/use-playback"
import { usePlayerStates } from "@/hooks/limeplay/use-player"
import { useTimelineStates } from "@/hooks/limeplay/use-timeline"

export const PlayerHooks = React.memo(() => {
  usePlayerStates()
  usePlaybackStates()
  useTimelineStates() 

  return null
})

import { createPlaybackStore, PlaybackStore } from "@/hooks/limeplay/use-playback"
import { createPlayerStore, PlayerStore } from "@/hooks/limeplay/use-player"
import {
  createTimelineStore,
  TimelineStore,
} from "@/hooks/limeplay/use-timeline"


export type TypeMediaStore = PlaybackStore &
  PlayerStore &
  TimelineStore &
  {}

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

Example Usage

Use the useTimeline() hook to implement seeking functionality.

import { useTimeline } from "@/hooks/limeplay/use-timeline"
import { useMediaStore } from "@/components/limeplay/media-provider"

export function TimelineSlider() {
  const duration = useMediaStore((state) => state.duration)
  const currentTime = useMediaStore((state) => state.currentTime)
  const { seek, getTimeFromEvent } = useTimeline()

  return (
    <div
      onPointerDown={(e) => {
        const time = getTimeFromEvent(e)
        seek(time)
      }}
    >
      <div style={{ width: `${(currentTime / duration) * 100}%` }} />
    </div>
  )
}

Understanding

The use-timeline hook provides comprehensive timeline management following the Event & Action Bridge pattern:

• Event Bridge: useTimelineStates() polls media state (default 500ms) and listens to durationchange, progress, and Shaka Player events to update currentTime, duration, progress, and buffered ranges
• Action Bridge: useTimeline() provides seek(), setHoveringTime(), and getTimeFromEvent() functions for timeline interactions

Live Stream Support

The hook automatically handles live streams:

• Uses Shaka Player's seekRange() for proper DVR seeking
• Calculates live latency
• Adjusts progress calculation for sliding window streams
• Provides isLive and liveLatency state

Buffered Ranges

The hook provides processBufferedRanges() function that supports three variants:

• default - Shows all buffered ranges as-is
• combined - Combines all ranges into a single range
• from-zero - Shows ranges starting from 0

API Reference

useTimelineStates

Sets up polling and event listeners for timeline state updates.

Parameters

useTimeline()

Returns control functions for timeline interactions.

Returns

Store State

The timeline store provides the following state accessed via useMediaStore: