Transport Bar API

`useTimelinePlayer` Hook

Manages playback state and controls for a <Timeline>. Attaches engine event listeners (play, paused, setTimeByTick) on mount and cleans them up on unmount.

function useTimelinePlayer(
  ref: React.RefObject<TimelineState>,
  options?: UseTimelinePlayerOptions,
): TimelinePlayerState;

`UseTimelinePlayerOptions`

Option	Type	Default	Description
`seekStep`	`number`	`5`	Number of seconds to jump when calling `rewind()` or `forward()`.
`loop`	`UseTimelinePlayerLoop`	`--`	Optional loop configuration. When provided, the hook handles the loop clock internally.

`UseTimelinePlayerLoop`

Property	Type	Description
`enabled`	`boolean`	Whether the loop is active. Safe to toggle while the timeline is playing.
`start`	`number`	Loop region start time in seconds. Must be less than `end`.
`end`	`number`	Loop region end time in seconds. Must be greater than `start`.

`TimelinePlayerState` (Returned)

Member	Type	Description
`isPlaying`	`boolean`	Whether the timeline is currently playing. Updated automatically from engine events.
`currentTime`	`number`	Current playback position in seconds. Updated on every engine tick — suitable for display.
`playRate`	`number`	Current playback rate multiplier (e.g. `1` = 1×, `2` = 2×).
`play()`	`() => void`	Start playback from the current position. Plays to the end of the timeline and then stops.
`pause()`	`() => void`	Pause playback at the current position.
`stop()`	`() => void`	Stop playback and reset the cursor to time `0`.
`toStart()`	`() => void`	Pause and jump the cursor back to time `0`.
`rewind()`	`() => void`	Jump backwards by `seekStep` seconds (clamped to 0).
`forward()`	`() => void`	Jump forwards by `seekStep` seconds.
`setTime(time)`	`(time: number) => void`	Jump to a specific time value (seconds).
`setPlayRate(rate)`	`(rate: number) => void`	Change the playback rate multiplier.

A pre-built professional playback controls UI. It renders transport controls (to-start, rewind, play/pause, forward, stop), a time display, playback rate buttons, and optionally a loop toggle with start/end inputs.

Props

Prop	Type	Description
`player`	`TimelinePlayerState`	(Required) The return value of `useTimelinePlayer()`. Provides all reactive state and control functions.
`loop`	`TransportBarLoopProps`	Optional loop controls. When provided, a loop toggle button appears, and start/end time inputs appear when the loop is active.
`playRates`	`number[]`	Playback rate options displayed as speed buttons. Default is `[0.25, 0.5, 1, 2, 4]`.
`formatDisplayTime`	`(seconds: number) => string`	Custom time format function. Receives the current time in seconds, should return a display string. Default produces `'M:SS.mm'` format.
`className`	`string`	Additional CSS class name for the transport bar root element.
`style`	`React.CSSProperties`	Inline styles for the transport bar root element.

`TransportBarLoopProps`

Property	Type	Description
`enabled`	`boolean`	Whether the loop is currently active. Controls the visual state of the loop button (lit vs. dim).
`start`	`number`	Loop region start time in seconds.
`end`	`number`	Loop region end time in seconds.
`onToggle`	`() => void`	Called when the user clicks the loop toggle button.
`onStartChange`	`(time: number) => void`	Called when the user edits the loop start input.
`onEndChange`	`(time: number) => void`	Called when the user edits the loop end input.

Basic Usage

import React, { useRef } from "react";
import {
  Timeline,
  TimelineState,
  TransportBar,
  useTimelinePlayer,
} from "@keplar-404/react-timeline-editor";

export const App = () => {
  const timelineRef = useRef<TimelineState>(null);
  const player = useTimelinePlayer(timelineRef);

  return (
    <div>
      <TransportBar player={player} />
      <Timeline ref={timelineRef} editorData={[]} effects={{}} />
    </div>
  );
};

`formatTime` Utility

Formats a time value in seconds to a M:SS.mm display string.

function formatTime(seconds: number): string;

formatTime(0); // '0:00.00'
formatTime(75.4); // '1:15.40'
formatTime(3661.1); // '61:01.10'