use-playback-source

Installation

npx shadcn add @limeplay/use-playback-source

Requires assetFeature registered in your createMediaKit.

Usage

Use PlaybackSourceController inside a block to normalize the block's source prop and pass it into useAsset().loadSource(...) after the Shaka player is ready.

import { PlaybackSourceController } from "@/hooks/limeplay/use-playback-source"

export function SourceController({ src }: { src?: string }) {
  return <PlaybackSourceController source={src} />
}

For typed assets, pass one asset or an asset array to source, then pass source resolution and recovery policies through loading.

import type { Asset } from "@/hooks/limeplay/use-asset"
import { PlaybackSourceController } from "@/hooks/limeplay/use-playback-source"

interface VideoAsset extends Asset {
  playbackUrl: string
  slug: string
}

export function VideoSource({ playlist }: { playlist: VideoAsset[] }) {
  return (
    <PlaybackSourceController
      source={playlist}
      loading={{
        getAssetId: (asset) => asset.slug,
        resolveSource: ({ asset }) => asset.playbackUrl,
      }}
    />
  )
}

Use sourceKey when the source is recreated often but represents the same logical media session.

<PlaybackSourceController
  source={playlist}
  sourceKey={playlist.map((item) => item.slug).join("|")}
/>

Feature Registration

use-playback-source is an opinionated controller helper, not a store feature. Register assetFeature with your media kit, then mount PlaybackSourceController inside the player tree.

lib/media.ts

"use client"

import { assetFeature } from "@/hooks/limeplay/use-asset"
import { playbackFeature } from "@/hooks/limeplay/use-playback"
import { playerFeature } from "@/hooks/limeplay/use-player"
import { playlistFeature } from "@/hooks/limeplay/use-playlist"
import { createMediaKit } from "@/components/limeplay/media-provider"

export const media = createMediaKit({
  features: [
    playerFeature(),
    playlistFeature(),
    playbackFeature(),
    assetFeature(),
  ] as const,
})

import type { Asset } from "@/hooks/limeplay/use-asset"
import type { UsePlaybackSourceOptions } from "@/hooks/limeplay/use-playback-source"
import { PlaybackSourceController } from "@/hooks/limeplay/use-playback-source"

export function Source<TAsset extends Asset>(
  props: UsePlaybackSourceOptions<TAsset>
) {
  return <PlaybackSourceController {...props} />
}

Store

State	Owner	Description
`source`	`UsePlaybackSourceOptions`	Source string, one asset, or asset array normalized by `PlaybackSourceController`.
`sourceKey`	`UsePlaybackSourceOptions`	Optional stable key used to avoid duplicate playlist loads.
`player`	`use-player`	The current Shaka player instance required before loading.

Actions

Action	Symbol	Description
Load source	`PlaybackSourceController`	Mounts a controller that calls `usePlaybackSource`.
Normalize options	`usePlaybackSource`	Converts a source string, one asset, or an asset array into a load session.
Load source	`loadSource` from `useAsset`	Receives the source plus `loading`, `initialIndex`, `sourceKey`, and `sourceType`.

Events

Event	Emitted by	Description
`playlistchange`	`use-playlist`	Fired after the normalized source is loaded into the queue and the active item changes.
`playerready`	`use-player`	The controller waits for a player instance before calling `loadSource`.
None	`use-playback-source`	The hook itself does not emit custom events.

API Reference

Prop

Type