# packages/core/src/lib/hooks/use-playback.ts This is the source snapshot used to build these API details. [View this revision on GitHub](https://github.com/benlesh/pibbl/blob/272a94aaf62e0bd6ad8726a4c607a76a9ec44ca1/packages/core/src/lib/hooks/use-playback.ts#L69). [Back to reference](/reference/hooks/use-playback/)
1 import {
2   createAnimationPlaybackController,
3   normalizeAnimationPlaybackCandidate,
4   type AnimationPlaybackController,
5 } from '../animation/playback.js';
6 import type {
7   PibblAnimationProgram,
8   PibblPlayback,
9   PibblPlaybackEvent,
10   PibblPlaybackOptions,
11 } from '../animation/types.js';
12 import { GLOBAL_STATE } from '../global-state.js';
13 import { isSignal } from '../signals/graph.js';
14 import { resolveSignalValue } from '../signals/resolve-signal-value.js';
15 import type { SignalValue } from '../signals/types.js';
16 import type { PibblComponentRefs, PibblInstance } from '../types.js';
17 import { requireHookContext, useHookSlot } from './hook-slot.js';
18 
19 type PibblPlaybackOptionsInput = {
20   readonly [K in keyof PibblPlaybackOptions]: SignalValue<PibblPlaybackOptions[K]>;
21 };
22 
23 interface PibblPlaybackHookSlot {
24   readonly controller: AnimationPlaybackController;
25   readonly componentRefs: PibblComponentRefs<any>;
26   readonly pibblInstance: PibblInstance;
27   latestOptions: PibblPlaybackOptions;
28   mountSettled: boolean;
29   readonly onError: (error: unknown) => void;
30   readonly onEvent: (event: PibblPlaybackEvent) => void;
31   renderRevision: number;
32 }
33 
34 function isCurrentSlot(slot: PibblPlaybackHookSlot): boolean {
35   return !slot.componentRefs.teardowns.closed &&
36     !slot.pibblInstance.mainTeardowns.closed &&
37     GLOBAL_STATE.pibblInstances.get(slot.pibblInstance.canvas) === slot.pibblInstance &&
38     slot.pibblInstance.refs.get(slot.componentRefs.id) === slot.componentRefs;
39 }
40 
41 function controllerOptions(
42   candidate: PibblPlaybackOptions,
43   onEvent: (event: PibblPlaybackEvent) => void,
44   onError: (error: unknown) => void,
45 ): PibblPlaybackOptions {
46   return {
47     ...candidate,
48     onEvent: typeof candidate.onEvent === 'function' ?
49       onEvent : candidate.onEvent,
50     onError: typeof candidate.onError === 'function' ?
51       onError : candidate.onError,
52   };
53 }
54 
55 /**
56  * Creates one component-owned animation playback handle for a hook slot.
57  *
58  * @param programInput - Animation program, optionally supplied by a signal. See
59  * {@link SignalValue} , {@link PibblAnimationProgram} .
60  * @param optionsInput - Playback configuration, optionally supplied by a signal. See
61  * {@link SignalValue} , {@link PibblPlaybackOptionsInput} .
62  * @returns Stable mount-owned playback controls and reactive status/time values. See
63  * {@link PibblPlayback} .
64  *
65  * @see {@link SignalValue}
66  * @see {@link PibblAnimationProgram}
67  * @see {@link PibblPlayback}
68  */
69 export function usePlayback(
70   programInput: SignalValue<PibblAnimationProgram>,
71   optionsInput: SignalValue<PibblPlaybackOptionsInput> = {},
72 ): PibblPlayback {
73   const { componentRefs, pibblInstance } = requireHookContext();
74   const program = resolveSignalValue(programInput);
75   const options = resolvePlaybackOptions(optionsInput);
76   const candidate = normalizeAnimationPlaybackCandidate(program, options);
77   const candidateOptions = candidate.options;
78   const slot = useHookSlot<PibblPlaybackHookSlot>('playback', teardowns => {
79     let value!: PibblPlaybackHookSlot;
80     const controller = createAnimationPlaybackController(
81       candidate.program,
82       candidateOptions,
83     );
84     controller.setDeferredStatusCommandOwner(pibblInstance.mainTeardowns);
85     const onEvent = (event: PibblPlaybackEvent): void => {
86       if (isCurrentSlot(value)) value.latestOptions.onEvent?.(event);
87     };
88     const onError = (error: unknown): void => {
89       if (isCurrentSlot(value)) value.latestOptions.onError?.(error);
90     };
91     value = {
92       controller,
93       componentRefs,
94       pibblInstance,
95       latestOptions: {},
96       mountSettled: false,
97       onError,
98       onEvent,
99       renderRevision: 0,
100     };
101     controller.adopt(
102       candidate.program,
103       controllerOptions(candidateOptions, onEvent, onError),
104     );
105     teardowns.add(() => controller.dispose());
106     return value;
107   }).value;
108   const revision = ++slot.renderRevision;
109   const transaction = GLOBAL_STATE.renderTransaction;
110   if (!transaction) {
111     throw new Error('usePlayback requires an active Pibbl render transaction.');
112   }
113   transaction.onFinish(success => {
114     if (!success || revision !== slot.renderRevision || !isCurrentSlot(slot)) return;
115     slot.controller.adopt(
116       candidate.program,
117       controllerOptions(candidateOptions, slot.onEvent, slot.onError),
118     );
119     slot.latestOptions = candidateOptions;
120     if (!slot.mountSettled) {
121       slot.mountSettled = true;
122       if (candidateOptions.autoplay === true) slot.controller.handle.play();
123     }
124   });
125   return slot.controller.handle;
126 }
127 
128 function resolvePlaybackOptions(
129   input: SignalValue<PibblPlaybackOptionsInput>,
130 ): PibblPlaybackOptions {
131   const source = resolveSignalValue(input);
132   let resolved: Record<PropertyKey, unknown> | undefined;
133   for (const key in source) {
134     const value = source[key as keyof PibblPlaybackOptionsInput];
135     if (!isSignal(value)) continue;
136     resolved ??= { ...source };
137     resolved[key] = resolveSignalValue(value as SignalValue<unknown>);
138   }
139   return (resolved ?? source) as PibblPlaybackOptions;
140 }
141
## Documentation version Documentation built with @pibbl/core 0.0.2, revision 272a94a. ALPHA — NOT FOR PRODUCTION USE.