# usePlayback

`usePlayback(program, options?)` returns stable component-owned controls plus
readonly status and current-time signals. Commands enter the next Begin phase;
outputs publish atomically in Commit; milestones arrive in Complete after
rendering. Removing the component releases registrations, writer leases,
callbacks, commands, and stepper state, leaving retained controls inert.

See the [animation contract](https://github.com/benlesh/pibbl/blob/main/docs/design/animation-contract.md).

Related types: [`PibblPlayback`](/reference/types/canvas-runtime/#pibblplayback),
[`PibblPlaybackOptions`](/reference/types/canvas-runtime/#pibblplaybackoptions), and
[`PibblAnimationProgram`](/reference/types/canvas-runtime/#pibblanimationprogram).

## API details from source

<span id="api-usePlayback"></span>

Creates one component-owned animation playback handle for a hook slot.

```ts
usePlayback: (programInput: SignalValue<PibblAnimationProgram>, optionsInput?: SignalValue<PibblPlaybackOptionsInput>) => PibblPlayback
```

Related API: [usePlayback](/reference/hooks/use-playback/), [SignalValue](/reference/types/signal-inputs/#signalvalue), [PibblAnimationProgram](/reference/types/canvas-runtime/#pibblanimationprogram), [PibblPlayback](/reference/types/canvas-runtime/#pibblplayback).

### Parameters

- **`programInput`** — Animation program, optionally supplied by a signal. See
[SignalValue](/reference/types/signal-inputs/#signalvalue) , [PibblAnimationProgram](/reference/types/canvas-runtime/#pibblanimationprogram) .

- **`optionsInput`** — Playback configuration, optionally supplied by a signal. See
[SignalValue](/reference/types/signal-inputs/#signalvalue) , `PibblPlaybackOptionsInput` .

### Returns

Stable mount-owned playback controls and reactive status/time values. See
[PibblPlayback](/reference/types/canvas-runtime/#pibblplayback) .

### See also

[SignalValue](/reference/types/signal-inputs/#signalvalue)

[PibblAnimationProgram](/reference/types/canvas-runtime/#pibblanimationprogram)

[PibblPlayback](/reference/types/canvas-runtime/#pibblplayback)

[View source — packages/core/src/lib/hooks/use-playback.ts:69](/source/packages/core/src/lib/hooks/use-playback-ts/#L69)

## Implementation guidance for agents

Read the [Animation and scheduling companion](/agents/topics/animation/) for ownership, adaptation, failure modes, and verification. [Agent start](/agents/) provides the version-selection workflow.

## Complete minimal examples

- [Tween playback controls](/minimal-examples/animation/tween/): Animate a signal and control the mounted playback with native buttons. [Plain source](/minimal/animation/tween.tsx)
## Interactive examples

- [Signals and animation](/examples/signals-and-animation/) · [Full page](/experience/signals-and-animation/)
- [Stirred Ink](/examples/stirred-ink/) · [Full page](/experience/stirred-ink/)
- [Energy Transitions](/examples/energy-transitions/) · [Full page](/experience/energy-transitions/)
## Documentation version

Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.