`useViewerAnimations`

Controls animation playback for GLB/GLTF models that contain embedded animations.

Usage


import { useViewerAnimations } from "@liveroom/react-immersive";
 
const {
  clips,
  currentClip,
  isPlaying,
  speed,
  time,
  duration,
  play,
  pause,
  stop,
  setSpeed,
  seek,
  handleAnimationsReady,
} = useViewerAnimations();
 
<ModelViewer
  onAnimationsReady={handleAnimationsReady}
  ...
/>

Returns

Name	Type	Description
`clips`	`string[]`	Animation clip names found in the GLB/GLTF file
`currentClip`	`string \| null`	Name of the currently playing clip, or `null`
`isPlaying`	`boolean`	`true` while an animation is playing (not paused or stopped)
`speed`	`number`	Current playback speed (default `1`)
`time`	`number`	Live playback position of the current clip in seconds (updates while playing)
`duration`	`number`	Length of the current clip in seconds
`play`	`(clipName: string) => void`	Starts a clip by name; resumes if the same clip is paused
`pause`	`() => void`	Pauses the currently playing clip at its current time
`stop`	`() => void`	Stops the current clip and resets it
`setSpeed`	`(speed: number) => void`	Changes the playback speed
`seek`	`(time: number) => void`	Scrubs the current clip to an absolute time in seconds (works while playing or paused), clamped to the clip length
`handleAnimationsReady`	`(controls: AnimationControls) => void`	Callback to pass to `onAnimationsReady`

Playback Controls Example


const { clips, currentClip, isPlaying, play, pause, stop, setSpeed } =
  useViewerAnimations();
 
// Play/pause toggle
<button onClick={() => isPlaying ? pause() : play(currentClip ?? clips[0])}>
  {isPlaying ? "Pause" : "Play"}
</button>
 
// Stop
<button onClick={stop}>Stop</button>
 
// Speed slider
<input
  type="range"
  min="0.1"
  max="3"
  step="0.1"
  defaultValue="1"
  onChange={(e) => setSpeed(Number(e.target.value))}
/>
 
// Clip selector
{clips.map((name) => (
  <button key={name} onClick={() => play(name)}>
    {name} {currentClip === name && isPlaying ? "▶" : ""}
  </button>
))}

onAnimationsReady is called even when the model has no animations — with an empty clips array and no-op control functions.