animate_it 0.3.2 → 0.5.0

data/app/views/animate_it/frames/player.html.haml

@@ -0,0 +1,92 @@
+!!!
+%html{ lang: "en", data: {
+  animate_it_embedded: @embedded_player ? "true" : "false",
+  animate_it_host_navigation: @host_navigation ? "true" : "false"
+} }
+  %head
+    %title= "#{@composition.id} player (#{@composition.duration_in_frames} frames)"
+    %meta{ name: "viewport", content: "width=#{@composition.width}, initial-scale=1" }
+    - AnimateIt.config.render_stylesheets.each do |sheet|
+      = stylesheet_link_tag sheet, "data-turbo-track": "reload"
+    :css
+      html, body {
+        width: #{@composition.width}px;
+        height: #{@composition.height}px;
+        margin: 0;
+        overflow: hidden;
+        background: transparent;
+      }
+      body {
+        zoom: #{@composition.zoom};
+      }
+      body, main, .hero-render-canvas {
+        background-color: transparent !important;
+      }
+      *, *::before, *::after {
+        transition: none !important;
+      }
+      .animate-it-stage {
+        position: absolute;
+        inset: 0;
+        width: #{@composition.width}px;
+        height: #{@composition.height}px;
+        overflow: hidden;
+      }
+      .animate-it-layer {
+        position: absolute;
+        inset: 0;
+        display: none !important;
+        visibility: hidden;
+      }
+      .animate-it-layer.is-active {
+        display: block !important;
+        visibility: visible;
+      }
+      .animate-it-public-play {
+        position: fixed;
+        right: 16px;
+        bottom: 16px;
+        z-index: 2147483647;
+        border: 0;
+        border-radius: 999px;
+        padding: 10px 18px;
+        background: rgba(0, 0, 0, 0.78);
+        color: #fff;
+        font: 600 14px/1 system-ui, sans-serif;
+        cursor: pointer;
+      }
+      html[data-animate-it-host-navigation="true"] [data-animate-it-hide-when-embedded="true"] {
+        display: none !important;
+      }
+      html[data-animate-it-embedded="true"] .animate-it-public-play {
+        display: none !important;
+      }
+  %body
+    .animate-it-stage
+      = @composition.render_structure(self, props: @props)
+    - if respond_to?(:render_page_stylesheets)
+      = render_page_stylesheets
+    - if respond_to?(:render_component_stylesheets)
+      = render_component_stylesheets
+    - if @public_player
+      - @audio_segments.each_with_index do |segment, index|
+        %audio{ data: {
+                  from_frame: segment.from_frame,
+                  duration_frames: segment.duration_frames || (@composition.duration_in_frames - segment.from_frame),
+                  gain: segment.source[:gain],
+                  loop: segment.source[:loop] ? "true" : "false"
+                },
+                preload: "auto",
+                src: public_audio_path(index),
+                style: "display:none" }
+      %button.animate-it-public-play{ type: "button", data: { animate_it_play: true }, aria: { pressed: "false" } } Play
+    %script{ type: "application/json", data: {
+      animate_it_tracks: true,
+      animate_it_transport: @public_player ? "true" : "false",
+      animate_it_autoplay: @public_player_options&.fetch(:autoplay, false) ? "true" : "false",
+      animate_it_loop: @public_player_options&.fetch(:loop, true) ? "true" : "false"
+    } }
+      != ERB::Util.json_escape(@track_document.to_json)
+    %script{ type: "application/json", data: { animate_it_manifest: true } }
+      != ERB::Util.json_escape(@player_manifest.as_json.to_json)
+    = javascript_tag AnimateIt::Runtime.source.html_safe

data/app/views/animate_it/studio/_preview_pane.html.haml

@@ -10,7 +10,7 @@
   %turbo-frame#animate_it_preview.animate-it-preview
     %iframe#animate_it_frame{
       title: "#{composition.id} frame preview",
-      src: "#{frame_base_url}/0?pp=disable",
+      src: composition.client_driven? ? "#{player_url}?pp=disable" : "#{frame_base_url}/0?pp=disable",
       style: "width: min(100%, #{composition.width}px); aspect-ratio: #{composition.width} / #{composition.height};"
     }
 

data/app/views/animate_it/studio/_props_pane.html.haml

@@ -9,6 +9,7 @@
 
   %section.animate-it-renders
     %h3 Rendering jobs
-    = turbo_stream_from AnimateIt::RenderStore::CHANNEL
-    %p.animate-it-stream-status Turbo Stream connected for render progress.
+    - if respond_to?(:turbo_stream_from)
+      = turbo_stream_from AnimateIt::RenderStore::CHANNEL
+      %p.animate-it-stream-status Turbo Stream connected for render progress.
     = AnimateIt::RenderStore.html.html_safe

data/app/views/animate_it/studio/_studio_script.html.haml

@@ -4,6 +4,8 @@
     if (!studio) return;
 
     const frameBaseUrl = studio.dataset.frameBaseUrl;
+    const playerUrl = studio.dataset.playerUrl;
+    const clientDriven = studio.dataset.clientDriven === "true";
     const duration = Number(studio.dataset.duration);
     const fps = Number(studio.dataset.fps);
     const lastFrame = duration - 1;
@@ -15,10 +17,10 @@
     const speedInput = document.getElementById("animate_it_speed");
     const propsInput = document.getElementById("animate_it_props_json");
 
-    const clampFrame = (value) => Math.max(0, Math.min(lastFrame, Number(value) || 0));
+    const clampFrame = (value) => Math.max(0, Math.min(lastFrame, Math.round(Number(value) || 0)));
     const initialParams = new URLSearchParams(window.location.search);
     let frame = clampFrame(initialParams.get("frame"));
-    let timer = null;
+    let animationFrame = null;
 
     const syncFrameUrl = () => {
       const url = new URL(window.location.href);
@@ -103,11 +105,20 @@
         .catch(() => { if (token === paintToken) fullReload(n); });
     };
 
-    const renderFrame = (n) => {
+    const renderLegacyFrame = (n) => {
       if (docReady) paintFragment(n);
       else fullReload(n); // bootstrap (or recover) with the full document
     };
 
+    const renderFrame = (n) => {
+      if (clientDriven) {
+        const win = iframe.contentWindow;
+        if (win && win.__animateIt) win.__animateIt.setFrame(n);
+      } else {
+        renderLegacyFrame(n);
+      }
+    };
+
     const playheads = document.querySelectorAll("[data-animate-it-playhead]");
     const audios = Array.from(document.querySelectorAll("audio[data-from-frame]"));
 
@@ -120,18 +131,13 @@
       return { start, len };
     };
 
-    // Background beds loop to cover their (possibly file-shorter) window;
-    // one-shot SFX self-limit so a long file can't bleed past its few frames
-    // even when the frame loop lurches behind real time.
     audios.forEach((el) => {
       const { len } = audioWindow(el);
-      const isBed = el.dataset.track === "background";
-      el.loop = isBed;
+      const loops = el.dataset.loop === "true";
+      el.loop = loops;
       el.volume = Math.min(1, Math.max(0, Number(el.dataset.gain ?? 1)));
-      // currentTime is seeked to (frame - start)/fps, so it reads 0 at the
-      // window start; the clip is done once it passes the window length.
       el.addEventListener("timeupdate", () => {
-        if (isBed) return;
+        if (loops) return;
         if (el.currentTime >= len / fps && !el.paused) el.pause();
       });
     });
@@ -141,34 +147,32 @@
       playheads.forEach((el) => { el.style.left = `${pct}%`; });
     };
 
-    // Seeking before the clip's metadata has loaded doesn't stick — it would
-    // start at 0:00 regardless of the scrubbed position. Defer the seek
-    // (recomputed from the then-current frame) until metadata is available.
+    const audioTime = (el, localTime) => {
+      if (el.dataset.loop !== "true" || !Number.isFinite(el.duration) || el.duration <= 0) return localTime;
+      return localTime % el.duration;
+    };
+
     const startAudio = (el) => {
       const begin = () => {
-        if (timer === null) return; // stopped before metadata arrived
+        if (animationFrame === null) return;
         const { start, len } = audioWindow(el);
-        if (frame < start || frame >= start + len) return; // playhead left the window
-        el.currentTime = (frame - start) / fps;
+        if (frame < start || frame >= start + len) return;
+        el.currentTime = audioTime(el, (frame - start) / fps);
         el.play().catch(() => {});
       };
       if (el.readyState >= 1) begin();
       else el.addEventListener("loadedmetadata", begin, { once: true });
     };
 
-    // Audio is audible only while actually playing — seeking/scrubbing is
-    // silent. Each element plays only inside its own window, seeked to the
-    // matching offset, so you hear exactly what belongs at the current frame.
     const syncAudio = (currentFrame, isPlaying) => {
       for (const el of audios) {
         const { start, len } = audioWindow(el);
         const within = currentFrame >= start && currentFrame < start + len;
-        if (within && isPlaying) {
-          // Seek only on (re)start — when the clip is paused. Once it's
-          // playing, leave it on its own real-time clock: re-seeking every
-          // frame to chase the setInterval-driven frame counter (which lags
-          // real time) is what chops the audio.
-          if (el.paused) startAudio(el);
+        if (within) {
+          const time = audioTime(el, (currentFrame - start) / fps);
+          if (!isPlaying && el.readyState >= 1 && Math.abs(el.currentTime - time) > 0.05) el.currentTime = time;
+          if (isPlaying && el.paused) startAudio(el);
+          if (!isPlaying && !el.paused) el.pause();
         } else if (!el.paused) {
           el.pause();
         }
@@ -183,45 +187,64 @@
       renderFrame(frame);
       syncFrameUrl();
       updatePlayheads(frame);
-      syncAudio(frame, keepAudioState && timer !== null);
+      syncAudio(frame, keepAudioState && animationFrame !== null);
     };
 
     const stop = () => {
-      if (timer) window.cancelAnimationFrame(timer);
-      timer = null;
+      if (animationFrame !== null) window.cancelAnimationFrame(animationFrame);
+      animationFrame = null;
       playButton.textContent = "Play";
       audios.forEach((el) => { if (!el.paused) el.pause(); });
     };
 
-    // Wall-clock playback. The frame is derived from elapsed real time, so the
-    // picture skips frames it can't keep up with rather than the clock slipping
-    // behind — and audio (on its own real clock) stays in sync. Morphing the
-    // body in place is fast and needs no load-gating, so the loop stays simple.
     const play = () => {
       stop();
       playButton.textContent = "Pause";
       const speed = Number(speedInput.value) || 1;
-      const startFrame = frame >= lastFrame ? 0 : frame;
-      const startWall = performance.now();
-      const tick = () => {
-        if (timer === null) return;
-        const next = clampFrame(Math.floor(startFrame + ((performance.now() - startWall) / 1000) * fps * speed));
+      const startedAt = window.performance.now();
+      const startedFrame = frame >= lastFrame ? 0 : frame;
+      if (startedFrame !== frame) setFrame(startedFrame);
+      audios.forEach((el) => { el.playbackRate = speed; });
+      const tick = (now) => {
+        if (animationFrame === null) return;
+        const elapsedFrame = startedFrame + Math.floor(((now - startedAt) / 1000) * fps * speed);
+        if (elapsedFrame >= lastFrame) {
+          setFrame(lastFrame, { keepAudioState: true });
+          stop();
+          return;
+        }
+
+        const master = audios.find((el) => !el.paused && el.dataset.loop !== "true");
+        const next = master
+          ? clampFrame((Number(master.dataset.fromFrame) || 0) + Math.floor(master.currentTime * fps))
+          : clampFrame(elapsedFrame);
         if (next !== frame) setFrame(next, { keepAudioState: true });
-        if (next >= lastFrame) { stop(); return; }
-        timer = window.requestAnimationFrame(tick);
+        animationFrame = window.requestAnimationFrame(tick);
       };
-      timer = window.requestAnimationFrame(tick);
+      animationFrame = window.requestAnimationFrame(tick);
       syncAudio(frame, true);
     };
 
-    scrubber.addEventListener("input", (event) => setFrame(event.target.value));
-    frameInput.addEventListener("change", (event) => setFrame(event.target.value));
+    scrubber.addEventListener("input", (event) => {
+      stop();
+      setFrame(event.target.value);
+    });
+    frameInput.addEventListener("change", (event) => {
+      stop();
+      setFrame(event.target.value);
+    });
     propsInput?.addEventListener("change", () => {
-      fragmentCache.clear();
-      pending.clear();
-      setFrame(frame);
+      if (clientDriven) {
+        iframe.src = `${playerUrl}${propsQuery()}`;
+      } else {
+        fragmentCache.clear();
+        pending.clear();
+        setFrame(frame);
+      }
     });
 
+    if (clientDriven) iframe.addEventListener("load", () => renderFrame(frame));
+
     document.querySelectorAll("[data-motion-step]").forEach((button) => {
       button.addEventListener("click", () => {
         stop();
@@ -237,7 +260,7 @@
     });
 
     playButton.addEventListener("click", () => {
-      if (timer) {
+      if (animationFrame !== null) {
         stop();
       } else {
         play();
@@ -255,7 +278,7 @@
         // natively activate it on Space, double-toggling to a no-op.
         event.preventDefault();
         if (document.activeElement && document.activeElement.blur) document.activeElement.blur();
-        timer === null ? play() : stop();
+        animationFrame === null ? play() : stop();
         return;
       }
 

data/app/views/animate_it/studio/show.html.haml

@@ -2,12 +2,18 @@
 
 = render "studio_styles"
 
-%main.animate-it-studio{ data: { frame_base_url: @frame_base_url, duration: @composition.duration_in_frames, fps: @composition.fps } }
+%main.animate-it-studio{ data: {
+  frame_base_url: @frame_base_url,
+  player_url: @player_url,
+  client_driven: @composition.client_driven? ? "true" : "false",
+  duration: @composition.duration_in_frames,
+  fps: @composition.fps
+} }
   %aside.animate-it-sidebar
     %h1 Animate It
     = render "composition_list", compositions: @compositions
 
-  = render "preview_pane", composition: @composition, frame_base_url: @frame_base_url, last_frame: @last_frame
+  = render "preview_pane", composition: @composition, frame_base_url: @frame_base_url, player_url: @player_url, last_frame: @last_frame
   = render "props_pane", composition: @composition, props_json: @props_json
 
 - @composition.timeline.segments.select { |seg| seg.kind == :audio }.each_with_index do |seg, idx|
@@ -15,7 +21,8 @@
             from_frame: seg.from_frame,
             duration_frames: seg.duration_frames || 0,
             track: seg.track,
-            gain: seg.source[:gain]
+            gain: seg.source[:gain],
+            loop: seg.source[:loop] ? "true" : "false"
           },
           src: animate_it_path("/compositions/#{@composition.id}/audio/#{idx}"),
           preload: "auto" }

data/config/routes.rb

@@ -1,9 +1,19 @@
 AnimateIt::Engine.routes.draw do
+  get "assets/:version/embed.js", to: "embed_assets#javascript", as: :embed_javascript,
+                                  constraints: { version: /[0-9A-Za-z._-]+/ }
+  get "assets/:version/embed.css", to: "embed_assets#stylesheet", as: :embed_stylesheet,
+                                   constraints: { version: /[0-9A-Za-z._-]+/ }
+
   root "studio#index"
 
+  get "public/compositions/:id/player", to: "public_players#show", as: :public_composition_player
+  get "public/compositions/:id/audio/:index", to: "public_players#audio", as: :public_composition_audio,
+                                              constraints: { index: /\d+/ }
+
   get "compositions/:id", to: "studio#show", as: :composition
   get "compositions/:id/frame/:frame", to: "frames#show", as: :composition_frame, constraints: { frame: /-?\d+/ }
   get "compositions/:id/filmstrip", to: "frames#filmstrip", as: :composition_filmstrip
+  get "compositions/:id/player", to: "frames#player", as: :composition_player
   get "compositions/:id/audio/:index", to: "audio#show", as: :composition_audio, constraints: { index: /\d+/ }
   patch "compositions/:id/props", to: "props#update", as: :composition_props
   post "compositions/:id/renders", to: "renders#create", as: :composition_renders

data/lib/animate_it/asset_manifest.rb

@@ -0,0 +1,92 @@
+require "digest"
+require "pathname"
+require "yaml"
+
+module AnimateIt
+  # Validates source inputs that a host application needs to reproduce its
+  # compositions. Media remains owned by the host; the gem only defines the
+  # manifest contract and checksum/provenance preflight.
+  class AssetManifest
+    Result = Data.define(:checked, :errors) do
+      def success?
+        errors.empty?
+      end
+    end
+
+    attr_reader :root, :path
+
+    def initialize(root: Rails.root, path: nil)
+      @root = Pathname(root).expand_path
+      @path = Pathname(path || @root.join("config/animate_it_assets.yml"))
+    end
+
+    def validate
+      manifest = load_manifest
+      assets = manifest.fetch("assets")
+      errors = []
+      errors << "manifest version must be 1" unless manifest["version"] == 1
+      errors.concat(validate_assets(assets))
+      Result.new(assets.size, errors)
+    rescue Errno::ENOENT
+      Result.new(0, ["asset manifest not found: #{path}"])
+    rescue KeyError, Psych::Exception => e
+      Result.new(0, ["invalid asset manifest #{path}: #{e.message}"])
+    end
+
+    def validate!
+      result = validate
+      return result if result.success?
+
+      raise Error, "AnimateIt asset preflight failed:\n- #{result.errors.join("\n- ")}"
+    end
+
+    private
+
+    def load_manifest
+      YAML.safe_load_file(path, aliases: false).tap do |manifest|
+        raise KeyError, "top level must be a mapping" unless manifest.is_a?(Hash)
+        raise KeyError, "assets must be an array" unless manifest["assets"].is_a?(Array)
+      end
+    end
+
+    def validate_assets(assets)
+      errors = []
+      paths = assets.filter_map do |asset|
+        asset["path"] if asset.is_a?(Hash) && !asset["path"].to_s.empty?
+      end
+      paths.tally.each { |asset_path, count| errors << "duplicate asset path: #{asset_path}" if count > 1 }
+      assets.each_with_index { |asset, index| errors.concat(validate_asset(asset, index)) }
+      errors
+    end
+
+    def validate_asset(asset, index)
+      return ["asset ##{index + 1} must be a mapping"] unless asset.is_a?(Hash)
+
+      relative_path = asset["path"].to_s
+      label = relative_path.empty? ? "asset ##{index + 1}" : relative_path
+      provenance = asset["provenance"]
+      errors = []
+      errors << "#{label}: path is required" if relative_path.empty?
+      errors << "#{label}: sha256 must be 64 lowercase hex characters" \
+        unless asset["sha256"].to_s.match?(/\A[0-9a-f]{64}\z/)
+      errors << "#{label}: provenance.provider is required" \
+        unless provenance.is_a?(Hash) && !provenance["provider"].to_s.empty?
+      return errors if relative_path.empty?
+
+      absolute_path = root.join(relative_path).cleanpath
+      unless absolute_path.to_s.start_with?("#{root}#{File::SEPARATOR}")
+        errors << "#{label}: path must remain inside #{root}"
+        return errors
+      end
+      unless absolute_path.file?
+        errors << "#{label}: file is missing"
+        return errors
+      end
+
+      actual_sha = Digest::SHA256.file(absolute_path).hexdigest
+      errors << "#{label}: checksum mismatch (expected #{asset["sha256"]}, got #{actual_sha})" \
+        if actual_sha != asset["sha256"]
+      errors
+    end
+  end
+end

data/lib/animate_it/asset_renderer.rb

@@ -1,20 +1,38 @@
 module AnimateIt
   # Drives a composition through every Output it declared, writing each one
-  # to its absolute repo-relative path. One VideoRenderer per output (cheap —
-  # frames are captured once per output even when the same composition has
-  # several formats, because each format wants a different ffmpeg encode).
+  # to its absolute repo-relative path. Outputs covering the same frame range
+  # share one ordered browser capture; each format still gets its own encoder.
   module AssetRenderer
     module_function
 
     def render_composition(composition, host:, on_progress: nil, frame_range: nil)
       raise Error, "Composition #{composition.id} has no `outputs do ... end`" if composition.outputs.empty?
 
+      capture_dirs = {}
       composition.outputs.map do |output|
-        render_output(composition, output, host: host, on_progress: on_progress, frame_range: frame_range)
+        effective_range = effective_range_for(output, frame_range)
+        next if effective_range == :skip
+
+        capture_key = capture_key_for(composition, effective_range)
+        frames_dir = capture_dirs[capture_key]
+        reuse_captured_frames = capture_dirs.key?(capture_key)
+        frames_dir ||= frames_dir_for(composition, capture_key, primary: capture_dirs.empty?)
+        capture_dirs[capture_key] = frames_dir
+
+        render_output(
+          composition,
+          output,
+          host:,
+          on_progress:,
+          frame_range: effective_range,
+          frames_dir:,
+          reuse_captured_frames:
+        )
       end
     end
 
-    def render_output(composition, output, host:, on_progress: nil, frame_range: nil)
+    def render_output(composition, output, host:, on_progress: nil, frame_range: nil, frames_dir: nil,
+                      reuse_captured_frames: false)
       effective_range = effective_range_for(output, frame_range)
       return nil if effective_range == :skip
 
@@ -25,13 +43,27 @@ module AnimateIt
         composition: composition,
         host: host,
         output_path: destination,
-        format: output.format
+        format: output.format,
+        frames_dir:
       )
 
-      renderer.render(frame_range: effective_range, on_progress: on_progress)
+      renderer.render(frame_range: effective_range, on_progress:, reuse_captured_frames:)
       destination
     end
 
+    def capture_key_for(composition, frame_range)
+      range = frame_range || (0...composition.duration_in_frames)
+      [range.first, range.last]
+    end
+
+    def frames_dir_for(composition, capture_key, primary:)
+      base = Rails.root.join("tmp/animate_it/#{composition.id}")
+      return base if primary
+
+      start_frame, end_frame = capture_key
+      base.join("captures/#{start_frame}-#{end_frame}")
+    end
+
     # A still PNG output always renders its declared single frame; if the
     # caller-supplied range excludes that frame, skip the output entirely.
     # Animated outputs use the caller's range when provided, otherwise