API Reference

// Direct usage (advanced — usually use usePlaybackStore instead)
import { PlaybackEngine } from '@elah/core'

const engine = new PlaybackEngine({ fps: 30 })

engine.play()
engine.pause()
engine.seek(frame)

// Subscribe to playback ticks
const unsub = engine.subscribe((snapshot) => {
  console.log(snapshot.frame, snapshot.isPlaying)
})

import { resolveTimeline, type Scene } from '@elah/core'

const scene: Scene = resolveTimeline(currentFrame, project)

// Scene shape:
interface Scene {
  frame: number
  fps: number
  stage: { width: number; height: number }
  videos: ActiveVideoClip[]
  audios: ActiveAudioClip[]
  texts: ActiveTextClip[]
  images: ActiveImageClip[]
  shapes: ActiveShapeClip[]
  freehand: ActiveFreehandClip[]
  transitions: ActiveTransition[]
}

// Fields shared by every active clip:
interface ActiveClipBase {
  id: string
  trackId: string
  name: string
  sourceFrame: number      // source-asset frame at the current playhead
  opacity: number          // 0..1, modified by transitions
  zIndex: number           // higher = closer to viewer (front)
  transform?: Transform    // undefined → renderer default (contain-fit)
}

// Each ActiveVideoClip adds:
interface ActiveVideoClip extends ActiveClipBase {
  type: 'video'
  src: string
  volume: number           // 0..1, after track mute
}

import { GpuRenderer, type Renderer } from '@elah/core'

// The Renderer interface
interface Renderer {
  mount(container: HTMLElement): void
  resize(cssWidth: number, cssHeight: number, dpr?: number): void
  render(scene: Scene): void
  prewarm?(scene: Scene): void   // optional decode look-ahead
  dispose(): void
}

// Direct usage (usually consumed through <Preview>)
// The constructor takes RendererOptions — the stage size comes from the
// Scene each tick, not the constructor. Pass a demuxerFactory to enable
// the real WebCodecs decode pipeline.
const renderer = new GpuRenderer({
  demuxerFactory: () => createMediabunnyBackend(mediabunny),
})

renderer.mount(containerEl)      // attach to the DOM once
renderer.resize(1920, 1080, window.devicePixelRatio)
renderer.render(scene)           // called each RAF tick
renderer.dispose()               // cleanup on unmount

// Time
type FrameCount = number // always integer

type ClipType = 'video' | 'audio' | 'text' | 'image' | 'shape' | 'freehand'
type TrackKind = 'video' | 'audio' | 'elements'

// Core data types
interface Project {
  id: string
  fps: number
  stage: { width: number; height: number }
  tracks: Track[]
  // Clips are stored keyed by trackId, NOT nested on Track.
  clips: Record<string, Clip[]>
  transitions: Transition[]
  version: number
  masterVolume?: number   // 0..2, linear
}

interface Track {
  id: string
  name: string
  kind: TrackKind
  order: number           // lower = closer to top of timeline
  height: number          // px
  locked: boolean
  disabled: boolean
  muted: boolean
  solo: boolean
  volume?: number         // 0..2, linear
  protected?: boolean     // the user cannot remove this track
  pinned?: 'bottom'       // addTrack keeps this lane below every non-pinned track
}

interface Clip {
  id: string
  trackId: string
  type: ClipType
  name: string
  startFrame: FrameCount        // position on the timeline
  durationFrames: FrameCount    // length on the timeline
  sourceStartFrame: FrameCount  // trim in-point into the source
  sourceDurationFrames: FrameCount
  src?: string
  assetId?: string
  transform?: Transform
  opacity?: number              // 0..1
  volume?: number               // 0..1
  speed?: number                // video only; 0.25..4, default 1
  cornerRadius?: number         // video/image; 0..0.5 of the shorter side
  crop?: { x: number; y: number; width: number; height: number } // 0..1 of the source
  locked?: boolean
  disabled?: boolean
  // Text clips (flat fields, not a nested object):
  content?: string
  fontSize?: number
  color?: string
  fontFamily?: string
  fontWeight?: 'normal' | 'bold'
  textAlign?: 'left' | 'center' | 'right'
  textAnimation?: TextAnimation
  shapeAnimation?: TextAnimation
  // Shape / freehand clips have their own shape*/stroke*/pathData fields.
}

interface Transform {
  x: number        // 0..1, normalized to stage width
  y: number        // 0..1, normalized to stage height
  scale: number    // 1 = native size
  scaleX?: number  // extra horizontal stretch on top of scale; omitted = 1
  scaleY?: number  // extra vertical stretch on top of scale; omitted = 1
  rotation: number // radians, positive = clockwise
  anchor: { x: number; y: number } // 0..1 within the clip box
}

// Entry/exit ramp for text (and shape) clips.
type TextAnimationKind = 'fade' | 'spin' | 'slide-up' | 'slide-down' | 'slide-left' | 'slide-right'

interface TextAnimation {
  in?: TextAnimationKind
  out?: TextAnimationKind
  durationFrames: number
  // Layered motion. When present it replaces in / out; used by text templates.
  inMotion?: MotionSpec
  outMotion?: MotionSpec
}

// One end of a layered animation: the state at the FAR end of the ramp.
// The near end is always the clip's resting state. Omitted channels stay at rest.
interface MotionSpec {
  opacity?: number       // 0..1
  offsetX?: number       // fraction of stage width
  offsetY?: number       // fraction of stage height
  scale?: number         // multiplier on the authored scale
  rotation?: number      // radians
  ease?: TextAnimationEasing        // geometry channels
  opacityEase?: TextAnimationEasing // default 'linear'
}

interface Transition {
  id: string
  kind: 'fade' | 'slide' | 'wipe'
  fromClipId: string
  toClipId: string
  trackId: string
  startFrame: FrameCount   // = toClip.startFrame - durationFrames / 2
  durationFrames: FrameCount
  direction?: 'left' | 'right' | 'up' | 'down'
  easing?: 'linear' | 'ease-in' | 'ease-out'
}

// Export — fps is read from project.fps; the export worker uses
// mediabunny directly, so there is no demuxerFactory here.
type ExportVideoCodec = 'avc' | 'vp9' | 'vp8'
type ExportAudioCodec = 'aac' | 'opus'

interface ExportOptions {
  videoCodec?: ExportVideoCodec   // default 'avc'
  audioCodec?: ExportAudioCodec
  videoBitrate?: number           // bits/s, default 8 Mbps
  audioBitrate?: number           // bits/s, default 128 kbps
  outputHeight?: number           // target SHORT edge in px (1080 = 1080p in either
                                  // orientation); other edge is rounded to even.
                                  // Default = the stage's own short edge
  onProgress?: (p: ExportProgress) => void
  signal?: AbortSignal
}

interface ExportProgress {
  frame: number
  totalFrames: number
}