@px-petals/roku.motion-web 0.0.0-stage → 1.1.0

package/player/player.js

@@ -0,0 +1,421 @@
+/**
+ * The canvas and its clock: fits the animation into the canvas, steps time
+ * with requestAnimationFrame (a timer where there is none), and draws each
+ * frame as vector or from raster sheets, with its text overlays on top.
+ *
+ * Vector drawing costs more on a weak device than a sheet's drawImage. With
+ * `adaptive`, an animation whose frames take too long moves to its sheets,
+ * when it has them.
+ *
+ * A bundle with layers, blends or cross-fades is shown as a mixed media: the
+ * clock then belongs to its stage, which says what every layer plays, and the
+ * mixer draws the poses together (mixer/). Such media draw vector only.
+ */
+
+import { dueCues } from '../audio/audio.cues.js'
+import { fitMatrix as fitInto } from './player.fit.js'
+import { drawOverlays, mixOverlays } from './overlay/overlay.js'
+
+/** @import { Animation } from '../lottie/lottie.js' */
+/** @import { Cue } from '../audio/audio.cues.js' */
+/** @import { RasterAnimation } from './player.raster.js' */
+/** @import { Matrix } from '../lottie/lottie.paths.js' */
+/** @import { Mixer } from '../mixer/mixer.js' */
+/** @import { createStage } from '../mixer/mixer.stage.js' */
+
+/** Vector frames measured before deciding whether to keep drawing them */
+const SAMPLE_FRAMES = 20
+/** A vector frame slower than this, at the median, moves to the sheets */
+const SLOW_FRAME_MS = 20
+
+/**
+ * @typedef {object} Media
+ * @property {Animation | null}                                      vector
+ * @property {RasterAnimation | null}                                raster
+ * @property {number}                                                width   the animation's own size
+ * @property {number}                                                height
+ * @property {number}                                                fps     the Lottie's frame rate
+ * @property {number}                                                frames  its length in frames
+ * @property {any[]}                                                 texts   its text overlays
+ * @property {Cue[]}                                                 cues    its audio cues, in frame order
+ * @property {() => { sid: string, rgb: number[], alpha: number }[]} tints   live tint colours, for its sheets
+ * @property {Mixed | null}                                          [mixed] set when the stage and mixer play it
+ */
+
+/** Times a finished mixed media applies its poses when its inputs move: Rive keeps applying a blend until its weights stop mattering */
+const SETTLE_PASSES = 8
+
+/**
+ * @typedef {object} Mixed
+ * @property {Mixer}                          mixer
+ * @property {ReturnType<typeof createStage>} stage
+ * @property {() => Record<string, any>}      values the machine's inputs, which blends read
+ * @property {(id: string) => any[]}          texts  an animation's text overlays
+ * @property {(id: string) => number}         fps
+ * @property {(id: string) => Cue[]}          cues   an animation's audio cues
+ * @property {(id: string) => Media | null}   item   an animation's own media, whose properties a write-back reads
+ */
+
+/**
+ * @typedef {object} Overlay
+ * @property {Record<string, any>}    values
+ * @property {Record<string, string>} families
+ * @property {Record<string, string>} inputOf
+ */
+
+/**
+ * @param {HTMLCanvasElement}                                  canvas
+ * @param {object}                                             options
+ * @param {boolean}                                            options.adaptive
+ * @param {(playback: string) => void}                         options.onPlayback
+ * @param {(layer: number) => void}                            options.onFinished
+ * @param {() => Overlay}                                      options.overlay
+ * @param {() => { fit: string, alignment: [number, number] }} [options.placement]      how the animation fits the canvas, read on every frame
+ * @param {(media: Media) => number}                          [options.artboardWidth]  the artboard's width when it is not the media's own (a layout blended between two bands), else 0; read on every frame
+ * @param {(media: Media) => number}                          [options.artboardHeight] the artboard's height when it is not the media's own (a layout sized to the canvas), else 0; read on every frame
+ * @param {() => void}                                         [options.onTick]         time has passed on a mixed media
+ * @param {() => boolean}                                      [options.isPinned]       the animation must stay vector: pointer listeners hit-test its drawn shapes
+ * @param {(cue: Cue) => void}                                 options.onCue            an audio cue the timeline passed
+ * @param {(media: Media, frame: number) => void}              [options.onFrame]        after a vector frame is drawn, with the animation's frame
+ * @param {(seconds: number) => void}                          [options.tick]           moves what runs beside the animation (nested machines) on by a frame
+ * @param {(media: Media) => void}                             [options.prepare]        called before each frame is drawn
+ * @param {() => boolean}                                      [options.keepAlive]      whether to keep stepping after the animation has finished
+ * @param {boolean}                                            [options.manual]         a test hook: no clock of its own; time moves only by `advance`
+ */
+export function createPlayer(canvas, options) {
+  const ctx = canvas.getContext('2d')
+  if (!ctx) throw new Error('this browser has no 2D canvas')
+
+  /** @type {Media | null} */
+  let media = null
+  let useRaster = false
+  let loops = false
+  let control = 'play'
+  let playback = 'none'
+  let elapsed = 0
+  /** Frame up to which audio cues have sounded; -1 before the first, which is at frame 0 */
+  let heard = -1
+  let last = 0
+  let frameHandle = 0
+  /** @type {number[]} */
+  let timings = []
+  let lastDrawMs = 0
+
+  const raf = window.requestAnimationFrame ? (/** @type {FrameRequestCallback} */ f) => window.requestAnimationFrame(f) : (/** @type {FrameRequestCallback} */ f) => window.setTimeout(() => f(Date.now()), 16)
+  const caf = window.cancelAnimationFrame ? (/** @type {number} */ h) => window.cancelAnimationFrame(h) : (/** @type {number} */ h) => window.clearTimeout(h)
+  const now = () => (window.performance && window.performance.now ? window.performance.now() : Date.now())
+
+  /** @param {string} next */
+  function setPlayback(next) {
+    if (playback === next) return
+    playback = next
+    options.onPlayback(next)
+  }
+
+  /**
+   * @param {Media}   next
+   * @param {boolean} nextLoops
+   * @param {boolean} preferRaster
+   */
+  function show(next, nextLoops, preferRaster) {
+    media = next
+    loops = nextLoops
+    useRaster = !next.mixed && ((preferRaster && !!next.raster) || !next.vector)
+    elapsed = 0
+    heard = -1
+    timings = []
+    if (control === 'stop') {
+      render()
+      setPlayback('stopped')
+      return
+    }
+    setPlayback(control === 'pause' ? 'paused' : 'playing')
+    render()
+    schedule()
+  }
+
+  /**
+   * Swaps in another version of what is showing, such as another layout
+   * band, at the same moment.
+   *
+   * @param {Media} next
+   */
+  function replace(next) {
+    if (!media) return
+    media = next
+    useRaster = (useRaster && !!next.raster) || !next.vector
+    render()
+  }
+
+  /** @param {string} next play, loop, pause or stop */
+  function setControl(next) {
+    control = next
+    if (next === 'stop') {
+      elapsed = 0
+      if (media && media.mixed) media.mixed.stage.rewind()
+      render()
+      setPlayback('stopped')
+      return
+    }
+    if (next === 'pause') {
+      setPlayback('paused')
+      return
+    }
+    if (next === 'loop') {
+      loops = true
+      if (media && media.mixed) media.mixed.stage.setLoops(true)
+    }
+    // play after the end starts over, as Roku's re-sent play does
+    if (playback === 'finished' || playback === 'stopped') {
+      elapsed = 0
+      if (media && media.mixed) media.mixed.stage.rewind()
+      heard = -1
+    }
+    setPlayback('playing')
+    schedule()
+  }
+
+  function schedule() {
+    if (frameHandle || !media) return
+    if (options.manual) return
+    last = now()
+    frameHandle = raf(tick)
+  }
+
+  /**
+   * A mixed media's frame: the stage moves on, the machine and what runs
+   * beside it (nested machines) hear of it, and a layer that ran out is reported.
+   *
+   * @param {number} seconds
+   */
+  function stepMixed(seconds) {
+    const mixed = /** @type {Mixed} */ (/** @type {Media} */ (media).mixed)
+    const done = mixed.stage.advance(seconds)
+    const swept = mixed.stage.sweeps(mixed.values())
+    for (let n = 0; n < swept.length; n++) {
+      const cues = mixed.cues(swept[n].animation)
+      if (!cues.length) continue
+      const fps = mixed.fps(swept[n].animation)
+      const due = dueCues(cues, swept[n].from * fps, swept[n].to * fps)
+      for (let k = 0; k < due.length; k++) options.onCue(due[k])
+    }
+
+    if (options.tick) options.tick(seconds)
+    if (options.onTick) options.onTick()
+    render()
+    for (let n = 0; n < done.length; n++) options.onFinished(done[n])
+
+    if (!media) return
+    const isBeside = !!options.keepAlive && options.keepAlive()
+    if (playback === 'playing' && mixed.stage.isIdle()) setPlayback('finished')
+    // a finished stage still has nested machines to move
+    const isRunning = playback === 'playing' || (playback === 'finished' && isBeside)
+    if (isRunning && !frameHandle && !options.manual) frameHandle = raf(tick)
+  }
+
+  /** Something entered a state while the clock was stopped at the end: run again. */
+  function wake() {
+    if (!media || !media.mixed || control === 'stop' || control === 'pause') return
+    setPlayback('playing')
+    schedule()
+  }
+
+  function tick() {
+    frameHandle = 0
+    const time = now()
+    const seconds = (time - last) / 1000
+    last = time
+    step(seconds)
+  }
+
+  /**
+   * Moves time on and draws.
+   *
+   * @param {number} seconds
+   */
+  function step(seconds) {
+    const isBesideFinished = playback === 'finished' && !!options.keepAlive && options.keepAlive()
+    if (!media || (playback !== 'playing' && !isBesideFinished)) return
+    if (media.mixed) {
+      stepMixed(seconds)
+      return
+    }
+
+    if (options.tick) options.tick(seconds)
+    if (isBesideFinished) {
+      // what runs beside a finished animation keeps going
+      render()
+      if (!options.manual) frameHandle = raf(tick)
+      return
+    }
+
+    elapsed += seconds
+    const duration = media.frames / media.fps
+    const isPastEnd = elapsed >= duration
+    if (isPastEnd && !loops) {
+      sound(media.frames)
+      elapsed = Math.max(0, duration - 1 / media.fps)
+      render()
+      setPlayback('finished')
+      options.onFinished(0)
+      if (!options.manual && options.keepAlive && options.keepAlive()) frameHandle = raf(tick)
+      return
+    }
+    if (isPastEnd) {
+      sound(media.frames)
+      elapsed %= duration
+      heard = -1
+    }
+    sound(elapsed * media.fps)
+
+    render()
+    if (!options.manual) frameHandle = raf(tick)
+  }
+
+  /**
+   * Sounds the audio cues between where the last tick left off and a frame.
+   *
+   * @param {number} frame
+   */
+  function sound(frame) {
+    if (!media) return
+    const due = dueCues(media.cues, heard, frame)
+    heard = frame
+    for (let n = 0; n < due.length; n++) options.onCue(due[n])
+  }
+
+  /** The animation's space onto the canvas's, as the bundle's fit and alignment say. */
+  function fitMatrix() {
+    // between two layout bands that blend the artboard is as big as the canvas, which only a vector picture can be drawn at
+    const shown = /** @type {Media} */ (media)
+    const blended = !useRaster && options.artboardWidth ? options.artboardWidth(shown) : 0
+    const blendedHeight = !useRaster && options.artboardHeight ? options.artboardHeight(shown) : 0
+    const width = blended || (/** @type {Media} */ (media)).width || canvas.width
+    const height = blendedHeight || (/** @type {Media} */ (media)).height || canvas.height
+    const placement = options.placement ? options.placement() : { fit: 'contain', alignment: /** @type {[number, number]} */ ([ 0, 0 ]) }
+    const ratio = canvas.clientWidth > 0 ? canvas.width / canvas.clientWidth : 1
+    // an artboard `layout` does not size to the canvas (it holds its own size) draws at the layout's scale, as Rive's does
+    const isHeld = placement.fit === 'layout' && !blended && !blendedHeight
+    return fitInto(isHeld ? 'none' : placement.fit, placement.alignment, width, height, canvas.width, canvas.height, ratio)
+  }
+
+  function render() {
+    if (!media || !ctx) return
+    const matrix = fitMatrix()
+    if (options.prepare) options.prepare(media)
+    ctx.setTransform(1, 0, 0, 1, 0, 0)
+    ctx.clearRect(0, 0, canvas.width, canvas.height)
+
+    if (media.mixed) {
+      const mixed = media.mixed
+      const started = now()
+      const poses = mixed.stage.poses(mixed.values())
+      mixed.mixer.draw(ctx, poses, matrix, mixed.stage.frame, playback === 'finished' ? SETTLE_PASSES : 1)
+      lastDrawMs = now() - started
+
+      const lead = mixed.stage.lead()
+      const overlay = options.overlay()
+      if (poses.length > 1 && mixed.texts(poses[0].animation).length) {
+        // several animations at once: their texts mix as their shapes do
+        const shown = poses.map((pose) => ({ texts: mixed.texts(pose.animation), frame: pose.time * mixed.fps(pose.animation), weight: pose.weight }))
+        drawOverlays(ctx, mixOverlays(shown), 0, overlay.values, overlay.families, matrix, overlay.inputOf)
+      } else if (lead) {
+        drawOverlays(ctx, mixed.texts(lead.animation), lead.time * mixed.fps(lead.animation), overlay.values, overlay.families, matrix, overlay.inputOf)
+      }
+      // a write-back reads the lead animation's own property, not the mix
+      const leadItem = lead ? mixed.item(lead.animation) : null
+      if (options.onFrame && lead && leadItem && leadItem.vector) options.onFrame(leadItem, leadItem.vector.inPoint + lead.time * mixed.fps(lead.animation))
+      return
+    }
+
+    if (useRaster && media.raster) {
+      media.raster.draw(ctx, elapsed * media.raster.fps, matrix, media.tints())
+    } else if (media.vector) {
+      const started = now()
+      media.vector.draw(ctx, media.vector.inPoint + elapsed * media.fps, matrix)
+      measure(now() - started)
+      if (options.onFrame) options.onFrame(media, media.vector.inPoint + elapsed * media.fps)
+    }
+
+    const overlay = options.overlay()
+    drawOverlays(ctx, media.texts, elapsed * media.fps, overlay.values, overlay.families, matrix, overlay.inputOf)
+  }
+
+  /**
+   * Moves a slow vector animation to its sheets, once enough frames are timed.
+   *
+   * @param {number} ms
+   */
+  function measure(ms) {
+    if (!options.adaptive || !media || !media.raster || timings.length >= SAMPLE_FRAMES) return
+    if (options.isPinned && options.isPinned()) return
+    timings.push(ms)
+    if (timings.length < SAMPLE_FRAMES) return
+    const sorted = timings.slice().sort((a, b) => a - b)
+    if (sorted[Math.floor(sorted.length / 2)] > SLOW_FRAME_MS) useRaster = true
+  }
+
+  /** Matches the canvas's pixels to its displayed size. */
+  function resize() {
+    const ratio = window.devicePixelRatio || 1
+    const width = Math.round(canvas.clientWidth * ratio)
+    const height = Math.round(canvas.clientHeight * ratio)
+    const hasSize = width > 0 && height > 0
+    if (hasSize && (canvas.width !== width || canvas.height !== height)) {
+      canvas.width = width
+      canvas.height = height
+    }
+    render()
+  }
+
+  return {
+    show,
+    replace,
+    wake,
+    setControl,
+    render,
+    /** Shows changed values: on the frame already coming while it plays, else at once, so values set many times a frame draw once */
+    redraw() {
+      // a finished animation keeps drawing while something beside it runs (scripts, nested machines)
+      const isDrawing = playback === 'playing' || (playback === 'finished' && !!options.keepAlive && options.keepAlive())
+      const isFrameComing = !!frameHandle && isDrawing
+      if (!isFrameComing) render()
+    },
+    resize,
+    /** Steps once more, though the animation has finished, for something beside it that has work (a script that reads a value that changed) */
+    nudge() {
+      if (!media || frameHandle || options.manual || playback !== 'finished') return
+      last = now()
+      frameHandle = raf(tick)
+    },
+    /** The frame of the vector animation showing: where its slots' properties are read */
+    get frame() {
+      return media && media.vector ? media.vector.inPoint + elapsed * media.fps : 0
+    },
+    /** With `manual`, moves time on by these seconds and draws. */
+    advance(/** @type {number} */ seconds) {
+      if (options.manual) step(seconds)
+    },
+    destroy() {
+      if (frameHandle) caf(frameHandle)
+      frameHandle = 0
+      media = null
+    },
+    get playback() {
+      return playback
+    },
+    /** Where the last vector frame drew the shapes pointer listeners target; null when it drew none */
+    get hits() {
+      if (!media || useRaster) return null
+      const drawn = media.mixed ? media.mixed.mixer.animation : media.vector
+      return drawn ? drawn.hits : null
+    },
+    get renderer() {
+      return useRaster ? 'raster' : 'vector'
+    },
+    /** How long the last mixed frame took to draw, in ms */
+    get drawMs() {
+      return lastDrawMs
+    },
+  }
+}

package/player/player.raster.js

@@ -0,0 +1,127 @@
+/**
+ * An animation's raster sheets, as lottie-roku renders them: frames packed
+ * row by row into one or more sheets, plus a white coverage mask per colour
+ * slot, laid out the same, which is tinted with the slot's live colour. A
+ * `source-in` fill over the mask is what Roku's blendColor does to it.
+ */
+
+import { fileUrl, loadImage } from '../bundle/bundle.js'
+
+/** @import { Bundle } from '../bundle/bundle.js' */
+/** @import { Matrix } from '../lottie/lottie.paths.js' */
+
+/**
+ * @typedef {object} RasterAnimation
+ * @property {number}                                                                                                                         width  the animation's own size, which frames are drawn at
+ * @property {number}                                                                                                                         height
+ * @property {number}                                                                                                                         fps    the sheets' frame rate
+ * @property {number}                                                                                                                         frames how many frames the sheets hold
+ * @property {Promise<void>}                                                                                                                  ready
+ * @property {(ctx: CanvasRenderingContext2D, frame: number, matrix: Matrix, tints: { sid: string, rgb: number[], alpha: number }[]) => void} draw
+ */
+
+/**
+ * @param   {any}             animation one of motion.json's animations
+ * @param   {Bundle}          bundle
+ * @returns {RasterAnimation}
+ */
+export function createRaster(animation, bundle) {
+  const raster = animation.raster
+  const sheets = /** @type {{ uri: string, columns: number, frameCount: number }[]} */ (raster.sheets || [])
+  /** @type {HTMLImageElement[]} */
+  const images = []
+  /** @type {Record<string, HTMLImageElement[]>} */
+  const masks = {}
+
+  const pending = sheets.map((sheet, n) => loadImage(fileUrl(bundle, sheet.uri)).then((image) => {
+    images[n] = image
+  }))
+  for (let t = 0; t < (raster.tints || []).length; t++) {
+    const tint = raster.tints[t]
+    masks[tint.sid] = []
+    for (let n = 0; n < tint.sheets.length; n++) {
+      pending.push(loadImage(fileUrl(bundle, tint.sheets[n])).then((image) => {
+        masks[tint.sid][n] = image
+      }))
+    }
+  }
+
+  let scratch = /** @type {CanvasRenderingContext2D | null} */ (null)
+  const frames = sheets.reduce((sum, sheet) => sum + sheet.frameCount, 0)
+
+  return {
+    width: animation.width,
+    height: animation.height,
+    fps: raster.fps,
+    frames,
+    ready: Promise.all(pending).then(() => undefined),
+    draw(ctx, frame, matrix, tints) {
+      const cell = locate(sheets, Math.max(0, Math.min(frames - 1, Math.floor(frame))))
+      if (!cell || !images[cell.sheet]) return
+
+      ctx.save()
+      ctx.setTransform(matrix[0], matrix[1], matrix[2], matrix[3], matrix[4], matrix[5])
+      const source = [ cell.column * raster.frameWidth, cell.row * raster.frameHeight, raster.frameWidth, raster.frameHeight ]
+      ctx.drawImage(images[cell.sheet], source[0], source[1], source[2], source[3], 0, 0, animation.width, animation.height)
+
+      for (let n = 0; n < tints.length; n++) {
+        const mask = masks[tints[n].sid] && masks[tints[n].sid][cell.sheet]
+        if (!mask) continue
+        scratch = scratch || newScratch()
+        if (!scratch) break
+        drawTinted(ctx, scratch, mask, source, tints[n], animation)
+      }
+      ctx.restore()
+    },
+  }
+}
+
+/**
+ * Which sheet holds a frame, and where in it.
+ *
+ * @param {any[]}  sheets
+ * @param {number} frame
+ */
+function locate(sheets, frame) {
+  let before = 0
+  for (let n = 0; n < sheets.length; n++) {
+    const sheet = sheets[n]
+    if (frame < before + sheet.frameCount) {
+      const index = frame - before
+      return { sheet: n, column: index % sheet.columns, row: Math.floor(index / sheet.columns) }
+    }
+    before += sheet.frameCount
+  }
+  return null
+}
+
+/**
+ * A mask's frame filled with the tint's colour, then drawn over the frame.
+ *
+ * @param {CanvasRenderingContext2D}          ctx
+ * @param {CanvasRenderingContext2D}          scratch
+ * @param {HTMLImageElement}                  mask
+ * @param {number[]}                          source  the frame's rectangle in the sheet
+ * @param {{ rgb: number[], alpha: number }}  tint
+ * @param {{ width: number, height: number }} size
+ */
+function drawTinted(ctx, scratch, mask, source, tint, size) {
+  const canvas = scratch.canvas
+  if (canvas.width !== source[2] || canvas.height !== source[3]) {
+    canvas.width = source[2]
+    canvas.height = source[3]
+  }
+  scratch.globalCompositeOperation = 'source-over'
+  scratch.clearRect(0, 0, canvas.width, canvas.height)
+  scratch.drawImage(mask, source[0], source[1], source[2], source[3], 0, 0, source[2], source[3])
+  scratch.globalCompositeOperation = 'source-in'
+  const channel = (/** @type {number} */ value) => Math.round(Math.max(0, Math.min(1, value)) * 255)
+  scratch.fillStyle = 'rgba(' + channel(tint.rgb[0]) + ',' + channel(tint.rgb[1]) + ',' + channel(tint.rgb[2]) + ',' + Math.max(0, Math.min(1, tint.alpha)) + ')'
+  scratch.fillRect(0, 0, canvas.width, canvas.height)
+  ctx.drawImage(canvas, 0, 0, size.width, size.height)
+}
+
+/** @returns {CanvasRenderingContext2D | null} */
+function newScratch() {
+  return document.createElement('canvas').getContext('2d')
+}