Timeline tied to clock (#654)

* clock can update delta

* tidy

* fix missing arg

* timeline tied to clock

* usePlayheadScrub

* better setting of clock on play

* better loop logic and fixed duration

* use clamped value for clock with goTo

* usePlayheadScrub improvements

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Author: funwithtriangles

apps/clock-test-app/src/App.tsx

@@ -106,6 +106,10 @@ function App() {
     clockRef.current?.sendTempoTap()
   }
 
+  const onDeltaSliderChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    clockRef.current!.beatDelta = Number(e.target.value)
+  }
+
   return (
     <>
       <section>
@@ -147,6 +151,9 @@ function App() {
           </form>
         </div>
       </section>
+      <section className="grid">
+        <input type="range" min={0} max={64} step={0.001} onChange={onDeltaSliderChange}></input>
+      </section>
       <section className="grid">
         <div className="circle"></div>
         <code>

packages/clock/src/index.ts

@@ -56,18 +56,22 @@ export class Clock {
       this._beatDelta += deltaInc
       this._beatPulseComparisonDelta += deltaInc
 
-      const newBeatCount = Math.floor(this._beatDelta % 4)
-      if (newBeatCount !== this._beatCount) {
-        this._onNewBeat?.(newBeatCount)
-        this._beatCount = newBeatCount
-      }
+      this.updateBeatCount()
 
       requestAnimationFrame(this.tick)
 
       this._lastTimestamp = timestamp
     }
   }
 
+  private updateBeatCount = () => {
+    const newBeatCount = Math.floor(this._beatDelta % 4)
+    if (newBeatCount !== this._beatCount) {
+      this._onNewBeat?.(newBeatCount)
+      this._beatCount = newBeatCount
+    }
+  }
+
   /**
    * Sets the BPM
    * @param bpm Beats per minute.
@@ -103,6 +107,23 @@ export class Clock {
     return this._beatDelta
   }
 
+  /**
+   * Sets the beat delta for external manual control (e.g. timelines)
+   * @param value The new beat delta
+   */
+  set beatDelta(value: number) {
+    this._beatDelta = value
+    this.updateBeatCount()
+  }
+
+  /**
+   * Sets the beat delta using a millisecond value, factoring in the current BPM
+   * @param deltaMs The new beat delta in milliseconds
+   */
+  set beatDeltaMs(deltaMs: number) {
+    this.beatDelta = (deltaMs / MS_IN_MINUTE) * this._bpm
+  }
+
   /**
    * Gets the current beat count.
    * @returns The current beat count

packages/lfo-input/src/LFOInput.ts

@@ -128,6 +128,8 @@ export class LFOInput implements IPlugin {
 
   private inputLatches: Record<string, boolean> = {}
 
+  private lastClockBeatDelta: number = -1
+
   private handleShot: ShotHandler = ({ delta, input, engine }) => {
     const val = Math.sin(delta)
 
@@ -188,11 +190,13 @@ export class LFOInput implements IPlugin {
 
     const tick = () => {
       requestAnimationFrame(() => {
-        if (!clock.isRunning) {
+        if (clock.beatDelta === this.lastClockBeatDelta) {
           tick()
           return
         }
 
+        this.lastClockBeatDelta = clock.beatDelta
+
         const storeState = store.getState()
         handleEachInput<typeof this.optionNodesConfig>(
           storeState,

packages/timeline/package.json

@@ -36,6 +36,7 @@
     "vite-tsconfig-paths": "^5.1.4"
   },
   "dependencies": {
+    "@hedron-gl/clock": "^1.0.0-alpha.4",
     "@hedron-gl/engine": "^1.0.0-alpha.4",
     "@hedron-gl/ui-core": "^1.0.0-alpha.4"
   },

packages/timeline/src/TimelineInput.ts

@@ -5,7 +5,7 @@ import {
   isEqual,
   OptionNodesFromConfigs,
 } from '@hedron-gl/engine'
-import { DEFAULT_TIMELINE_ID } from './constants'
+import { DEFAULT_TIMELINE_ID, TIMELINE_DURATION } from './constants'
 import { TimelineManager } from './TimelineManager'
 import { getTimelineTracks } from './selectors/getTimelineTracks'
 import { TimelineManagerKeyframeTrack } from './types'
@@ -56,10 +56,13 @@ export class TimelineInput implements IPlugin {
 
     this.timelineManagers.set(
       DEFAULT_TIMELINE_ID,
-      new TimelineManager({
-        durationMs: 60000,
-        tracks: [],
-      }),
+      new TimelineManager(
+        {
+          durationMs: TIMELINE_DURATION,
+          tracks: [],
+        },
+        engine.clock,
+      ),
     )
 
     this.timelineManagers.forEach((manager, timelineId) => {

packages/timeline/src/TimelineManager.ts

@@ -1,3 +1,4 @@
+import { Clock } from '@hedron-gl/clock'
 import type {
   TimelineManagerData,
   TimelineManagerTrack,
@@ -20,9 +21,11 @@ export class TimelineManager {
   private sortedKeyframesCache: Map<string, Keyframe[]> = new Map()
   private audioCache: Map<string, HTMLAudioElement> = new Map()
   private lastKeyframeIndex: Map<string, number> = new Map()
+  private clock: Clock | null = null
 
-  constructor(timeline: TimelineManagerData) {
+  constructor(timeline: TimelineManagerData, clock?: Clock) {
     this.timelineData = timeline
+    this.clock = clock ?? null
     this.buildCache()
   }
 
@@ -111,27 +114,30 @@ export class TimelineManager {
     if (this.lastFrameTime !== null) {
       const delta = now - this.lastFrameTime
       this.position = Math.min(this.position + delta, this.timelineData.durationMs)
+
+      if (this.clock) {
+        this.clock.beatDeltaMs = this.position
+      }
     }
     this.lastFrameTime = now
 
     this.emitUpdate()
 
     if (this.position >= this.timelineData.durationMs) {
-      this.playing = false
-      this.lastFrameTime = null
-      this.resetKeyframeIndexes()
-      return
+      this.goTo(0)
     }
 
     this.rafId = requestAnimationFrame(this.tick)
   }
 
   play() {
     if (this.playing) return
-    if (this.position >= this.timelineData.durationMs) {
-      this.position = 0
-      this.resetKeyframeIndexes()
+
+    if (this.clock) {
+      this.clock.beatDeltaMs = this.position
+      this.clock.continue()
     }
+
     this.playing = true
     this.lastFrameTime = null
     this.rafId = requestAnimationFrame(this.tick)
@@ -146,6 +152,11 @@ export class TimelineManager {
   pause() {
     this.playing = false
     this.lastFrameTime = null
+
+    if (this.clock) {
+      this.clock.stop()
+    }
+
     if (this.rafId !== null) {
       cancelAnimationFrame(this.rafId)
       this.rafId = null
@@ -163,6 +174,10 @@ export class TimelineManager {
     this.resetKeyframeIndexes()
     this.emitUpdate()
 
+    if (this.clock) {
+      this.clock.beatDeltaMs = this.position
+    }
+
     // Seek audio tracks
     for (const { audio } of this.getAudioTracksWithAudio()) {
       audio.currentTime = this.position / 1000

packages/timeline/src/components/Timeline/Timeline.tsx

@@ -1,8 +1,9 @@
-import { useCallback, useEffect, useRef, useState } from 'react'
+import { useEffect, useRef, useState } from 'react'
 import c from './Timeline.module.css'
 import '@hedron-gl/ui-core/base.css'
 import '@hedron-gl/ui-core/fonts.css'
 import { TrackKeyframes } from './TrackKeyframes'
+import { usePlayheadScrub } from './usePlayheadScrub'
 import { TimelineManagerTrack } from '@/types'
 
 export interface TimelineProps {
@@ -29,7 +30,7 @@ export function Timeline({
   onKeyframeInsert,
 }: TimelineProps) {
   const { durationMs, tracks } = timeline
-  const trackAreaRef = useRef<HTMLDivElement>(null)
+  const rulerAreaRef = useRef<HTMLDivElement>(null)
   const [selectedTrack, setSelectedTrack] = useState<string | null>(null)
   const [selectedKeyframe, setSelectedKeyframe] = useState<string | null>(null)
 
@@ -47,21 +48,7 @@ export function Timeline({
     return () => window.removeEventListener('keydown', handleKeyDown)
   }, [selectedKeyframe, onKeyframeDelete, selectedTrack, playheadPositionMs, onKeyframeInsert])
 
-  const handleTrackClick = useCallback(
-    (e: React.MouseEvent<HTMLDivElement>) => {
-      if (!trackAreaRef.current || !onPlayheadChange) return
-      const rect = trackAreaRef.current.getBoundingClientRect()
-      const headerWidth = parseFloat(
-        getComputedStyle(trackAreaRef.current).getPropertyValue('--trackHeaderWidth'),
-      )
-      const trackWidth = rect.width - headerWidth
-      const x = e.clientX - rect.left - headerWidth
-      if (x < 0) return
-      const time = (x / trackWidth) * durationMs
-      onPlayheadChange(Math.max(0, Math.min(durationMs, time)))
-    },
-    [durationMs, onPlayheadChange],
-  )
+  usePlayheadScrub(durationMs, rulerAreaRef, playheadPositionMs, onPlayheadChange)
 
   const playheadPercent = (playheadPositionMs / durationMs) * 100
 
@@ -85,8 +72,10 @@ export function Timeline({
           {(playheadPositionMs / 1000).toFixed(1)}s / {durationSec}s
         </span>
       </div>
-      <div className={c.body} ref={trackAreaRef} onClick={handleTrackClick}>
-        <div className={c.ruler}>{rulerMarks}</div>
+      <div className={c.body}>
+        <div className={c.ruler} ref={rulerAreaRef}>
+          {rulerMarks}
+        </div>
         {tracks.map((track) => {
           const isSelected = selectedTrack === track.id
           return (

packages/timeline/src/components/Timeline/usePlayheadScrub.ts

@@ -0,0 +1,55 @@
+import { useElementScrub } from '@hedron-gl/ui-core'
+import { useCallback, useEffect, useRef } from 'react'
+
+export const usePlayheadScrub = (
+  durationMs: number,
+  playheadAreaRef: React.RefObject<HTMLDivElement>,
+  playheadPositionMs: number,
+  onPlayheadChange?: (time: number) => void,
+) => {
+  // We need this as a ref for useElementScrub to work properly
+  const playheadPositionRef = useRef(0)
+
+  useEffect(() => {
+    playheadPositionRef.current = playheadPositionMs
+  }, [playheadPositionMs])
+
+  const clampTime = useCallback(
+    (time: number) => Math.max(0, Math.min(durationMs, time)),
+    [durationMs],
+  )
+
+  const onPlayheadAreaScrub = useCallback(
+    ({ x }: { x: number }) => {
+      const newTime = clampTime(playheadPositionRef.current + x * durationMs)
+
+      onPlayheadChange?.(newTime)
+      playheadPositionRef.current = newTime
+    },
+    [clampTime, durationMs, onPlayheadChange],
+  )
+
+  const onRulerMouseDown = useCallback(
+    (e: MouseEvent) => {
+      if (!playheadAreaRef.current || !onPlayheadChange) return
+      const rect = playheadAreaRef.current.getBoundingClientRect()
+      if (rect.width <= 0) return
+
+      const x = Math.max(0, Math.min(rect.width, e.clientX - rect.left))
+      const time = clampTime((x / rect.width) * durationMs)
+      onPlayheadChange(time)
+      playheadPositionRef.current = time
+    },
+    [clampTime, durationMs, onPlayheadChange, playheadAreaRef],
+  )
+
+  useEffect(() => {
+    const current = playheadAreaRef.current
+    current?.addEventListener('mousedown', onRulerMouseDown)
+    return () => {
+      current?.removeEventListener('mousedown', onRulerMouseDown)
+    }
+  }, [onRulerMouseDown, playheadAreaRef])
+
+  useElementScrub(playheadAreaRef, onPlayheadAreaScrub, 'ew-resize')
+}

packages/timeline/src/components/TimelineGlobalPanel/useTimelineData.tsx

@@ -2,11 +2,9 @@ import { useMemo } from 'react'
 
 import { useEngineStoreDeepEqual } from '@hedron-gl/ui-core'
 
-import { DEFAULT_TIMELINE_ID } from '@/constants'
+import { DEFAULT_TIMELINE_ID, TIMELINE_DURATION } from '@/constants'
 import { getTimelineTracks } from '@/selectors/getTimelineTracks'
 
-const TIMELINE_DURATION = 10000
-
 export const useTimelineData = () => {
   const tracks = useEngineStoreDeepEqual((state) => getTimelineTracks(state, DEFAULT_TIMELINE_ID))
 

packages/timeline/src/constants.ts

@@ -1,3 +1,5 @@
 export const DEFAULT_TIMELINE_ID = 'default-timeline'
 
 export const DEFAULT_AUDIO_TRACK_ID = 'default-audio-track'
+
+export const TIMELINE_DURATION = 10000