🎬 ReactZotonicPlayer

A React hook for frame-based animations with easing, looping, triggers, and optional custom ticker support.

✨ Features

• ▶️ Play, ⏸️ pause, ⏹️ stop, and 🔍 seek animations by frame
• 🎢 Supports multiple easing functions (linear, easeInQuad, easeOutQuad, easeInOutQuad, steps)
• 🔁 Loop animations from any frame
• ⚙️ Custom ticker support (to sync animation with external tickers)
• 🚦 Trigger callbacks for animation start and end events
• 📊 Returns interpolated animated values grouped by animation ID

📦 Installation

npm i @busyexplore/zotonic-player

🚀 Usage

import React, { useEffect } from "react";
import ReactZotonicPlayer from "@busyexplore/zotonic-player"


const animations = [
  {
    id: 1,
    startTime: 0,
    duration: 24,
    data: { x: 0, y: 0 },
    ease: "easeInOutQuad",
  },
  {
    id: 1,
    startTime: 24,
    duration: 24,
    data: { x: 100, y: 100 },
    ease: "linear",
  },
];

function AnimatedComponent() {
  const {
    cursor,
    animatedValue,
    isPlaying,
    play,
    pause,
    stop,
    seek,
    loadAnimation,
    setLoopEnabled,
    setTriggerCallback,
  } = ReactZotonicPlayer();

  useEffect(() => {
    loadAnimation(animations);
  }, []);

  useEffect(() => {
    setTriggerCallback((events) => {
      events.forEach(({ id, type, frame }) => {
        console.log(`Animation ${id} ${type} at frame ${frame}`);
      });
    });
  }, []);

  return (
    <div>
      <button onClick={() => play()}>▶️ Play</button>
      <button onClick={pause}>⏸️ Pause</button>
      <button onClick={stop}>⏹️ Stop</button>
      <button onClick={() => seek(12)}>🔍 Seek to frame 12</button>
      <label>
        🔁 Loop:
        <input type="checkbox" onChange={e => setLoopEnabled(e.target.checked)} />
      </label>
      <div>🎞️ Frame: {cursor}</div>
      <pre>{JSON.stringify(animatedValue, null, 2)}</pre>
    </div>
  );
}

🛠️ API

ReactZotonicPlayer(options?)

| Option | Type | Default | Description | |-------------------|------------|---------|------------------------------------------------| | useCustomTicker | boolean | false | Use a custom ticker function instead of RAF. | | ticker | function | () => {} | Custom ticker function called each frame if enabled. Receives a callback to advance the frame. |

Returned Object

| Property | Type | Description | |---------------------|------------|------------------------------------------------| | cursor | number | Current frame number. | | totalDuration | number | Total animation duration in frames. | | animatedValue | Array | Array of { id, props } objects for current frame. | | isPlaying | boolean | Indicates if the animation is playing. | | setLoopEnabled | function | Enable or disable looping. | | setTriggerCallback| function | Set callback for animation start/end triggers. Receives an array of trigger events. | | play(fromFrame?) | function | Start playing optionally from a specific frame.| | pause() | function | Pause animation playback. | | stop() | function | Stop and reset animation to frame 0. | | seek(frame) | function | Jump to a specific frame number. | | loadAnimation(data) | function | Load animation keyframe data. |

🎨 Animation Data Structure

The animation data is an array of keyframe objects:

[
  {
    id: number,          // unique animation id
    startTime: number,   // start frame
    duration: number,    // duration in frames
    data: object,        // properties to animate, e.g., { x: 0, y: 0 }
    ease: string,        // easing function ("linear", "easeInOutQuad", "steps", etc.)
    steps?: number,      // number of steps for "steps" easing
    triggerOnlyWhenStartAndEnd?: boolean // enable trigger events for this keyframe
  }
]

🎢 Easing Functions & Usage

The hook supports the following easing functions. Specify the easing in your animation keyframe objects using the ease property:

| Easing Name | Description | Usage Example | |----------------|-----------------------------------------------|---------------------------| | linear | Straight linear interpolation, no easing. | { ease: "linear" } | | easeInQuad | Accelerating from zero velocity (quadratic). | { ease: "easeInQuad" } | | easeOutQuad | Decelerating to zero velocity (quadratic). | { ease: "easeOutQuad" } | | easeInOutQuad| Accelerates until halfway, then decelerates. | { ease: "easeInOutQuad" }| | steps | Discrete steps instead of smooth interpolation. Requires steps parameter specifying number of steps. | { ease: "steps", steps: 5 } |

Example animation keyframe with easing:

const animation = [
  {
    id: 1,
    startTime: 0,
    duration: 24,
    data: { x: 0, opacity: 0 },
    ease: "easeInOutQuad",
  },
  {
    id: 1,
    startTime: 24,
    duration: 24,
    data: { x: 100, opacity: 1 },
    ease: "steps",
    steps: 4,
  },
];

📋 Notes

• The default frame rate is fixed at 24 FPS when using the internal RAF ticker.
• Looping will restart the animation from the last seek frame.
• Triggers only fire on animations with triggerOnlyWhenStartAndEnd enabled.
• Custom ticker mode allows integrating with external animation loops or libraries.

If you have any questions or want to contribute, feel free to open an issue or pull request!

Happy animating! 🎨✨