animate_it 0.3.2 → 0.4.0

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,14 @@
 AnimateIt::Engine.routes.draw do
   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

data/lib/animate_it/composition.rb

@@ -14,6 +14,8 @@ module AnimateIt
         subclass.instance_variable_set(:@zoom, 1.0)
         subclass.instance_variable_set(:@duration_in_frames, 30)
         subclass.instance_variable_set(:@output_format, :webm)
+        subclass.instance_variable_set(:@verification_props, [{}].freeze)
+        subclass.instance_variable_set(:@public_player_options, nil)
         super
       end
 
@@ -65,6 +67,81 @@ module AnimateIt
         AnimateIt.register(self)
       end
 
+      # Opt in to the seekable browser runtime. Legacy compositions continue
+      # rendering individual frames on the server.
+      def client_driven!
+        @client_driven = true
+      end
+
+      def client_driven?
+        @client_driven == true
+      end
+
+      # Explicitly expose this composition through the production-safe public
+      # player endpoint. Studio, frame, filmstrip, props, and render endpoints
+      # remain local-only. Public playback always uses schema-default props.
+      def public_player!(autoplay: false, loop: true)
+        client_driven!
+        @public_player_options = { autoplay: autoplay == true, loop: loop == true }.freeze
+      end
+
+      def public_player?
+        @public_player_options.present?
+      end
+
+      def public_player_options
+        @public_player_options || { autoplay: false, loop: true }.freeze
+      end
+
+      def verification_props(*variants)
+        return @verification_props if variants.empty?
+
+        raise ArgumentError, "verification_props entries must be hashes" unless variants.all?(Hash)
+
+        @verification_props = variants.map(&:deep_symbolize_keys).freeze
+      end
+
+      def structure_epochs(*frames)
+        return @structure_epochs || [] if frames.empty?
+
+        @structure_epochs = frames.map(&:to_i).sort.uniq
+      end
+
+      def structure_layers
+        timeline.segments.each_with_index.flat_map do |segment, segment_index|
+          next [] unless segment.kind == :scene
+
+          segment_end = segment.duration_frames ? segment.from_frame + segment.duration_frames : duration_in_frames
+          epochs = structure_epochs.select { |frame| frame > segment.from_frame && frame < segment_end }
+          bounds = ([segment.from_frame] + epochs).sort.uniq
+          bounds.each_with_index.map do |from_frame, index|
+            Tracks::Layer.new(
+              segment:,
+              segment_index:,
+              from_frame:,
+              to_frame: bounds[index + 1] || segment_end
+            )
+          end
+        end
+      end
+
+      def render_structure(view_context, props: {})
+        resolved_props = props_schema.resolve(props)
+        rendered_layers = structure_layers.map do |layer|
+          context = frame_context(frame: layer.from_frame, props: resolved_props, segment: layer.segment)
+          view_context.tag.div(
+            render_segment(view_context, layer.segment, context),
+            class: "animate-it-layer",
+            data: { animate_layer: layer.key }
+          )
+        end
+        view_context.safe_join(rendered_layers)
+      end
+
+      def track_document(props: {})
+        Tracks::Recorder.new(self, props:).call
+      end
+
       def fps(value = nil)
         return @fps if value.nil?
 
@@ -140,12 +217,16 @@ module AnimateIt
       # ----- Audio DSL --------------------------------------------------
       # Loop a track for the full duration (or a slice). Background music.
       def audio_loop(path, duration: nil, from: 0, name: nil, gain: 1.0, track: :background)
-        # Simplest implementation: place the same source once at `from`
-        # for the requested length. The renderer's audio mixer handles
-        # truncation if the underlying file is longer than the segment.
         length = duration || (@duration_in_frames - Units.frames(from, fps: fps))
-        audio(path, duration: length, from: from, name: name || "loop-#{File.basename(path.to_s)}", track: track,
-                    gain: gain)
+        audio(
+          path,
+          duration: length,
+          from:,
+          name: name || "loop-#{File.basename(path.to_s)}",
+          track:,
+          gain:,
+          loop: true
+        )
       end
 
       # Play a voice-over clip at a named beat (or time/frame). The clip's
@@ -212,14 +293,21 @@ module AnimateIt
       # Place an audio segment on its own track. The renderer doesn't draw
       # audio; the studio plays it via <audio> tags synced to the scrubber, and
       # ffmpeg muxes it into the final encode.
-      def audio(path, duration: nil, from: 0, start_at: nil, name: nil, track: :audio, gain: 1.0)
+      def audio(path, duration: nil, from: 0, start_at: nil, name: nil, track: :audio, gain: 1.0, loop: false)
+        begin
+          gain = Float(gain)
+        rescue TypeError, ArgumentError
+          raise ArgumentError, "Audio gain must be a number between 0.0 and 1.0"
+        end
+        raise ArgumentError, "Audio gain must be between 0.0 and 1.0" unless gain.between?(0.0, 1.0)
+
         timeline.add_segment(
           name: name || File.basename(path.to_s),
           from_frame: Units.frames(start_at || from, fps:),
           duration_frames: Units.frames(duration, fps:),
           kind: :audio,
           track:,
-          source: { path: path.to_s, gain: gain.to_f },
+          source: { path: path.to_s, gain:, loop: },
           show_in_timeline: true
         )
       end
@@ -246,14 +334,17 @@ module AnimateIt
         )
       end
 
-      def render_frame(view_context, frame:, props: {})
+      def render_frame(view_context, frame:, props: {}, segment_origins: false)
         resolved_props = props_schema.resolve(props)
         segments = timeline.active_segments(frame.to_i, kind: :scene)
         return "" if segments.empty?
 
         rendered_segments = segments.map do |segment|
           context = frame_context(frame:, props: resolved_props, segment:)
-          render_segment(view_context, segment, context)
+          content = render_segment(view_context, segment, context)
+          next content unless segment_origins
+
+          view_context.tag.div(content, data: { animate_it_segment_origin: segment.from_frame })
         end
         view_context.safe_join(rendered_segments)
       end

data/lib/animate_it/embed_helper.rb

@@ -0,0 +1,22 @@
+module AnimateIt
+  module EmbedHelper
+    def animate_it_player(composition_id, title: nil, **attributes)
+      AnimateIt.load_compositions!
+      composition = AnimateIt.registry.fetch(composition_id)
+      raise ArgumentError, "AnimateIt composition #{composition_id.inspect} is not public" unless composition.public_player?
+
+      prefix = respond_to?(:request) && request ? request.script_name.to_s : ""
+      source = "#{prefix}#{AnimateIt.config.mount_path}/public/compositions/" \
+               "#{ERB::Util.url_encode(composition.id)}/player"
+      defaults = {
+        src: source,
+        title: title || composition.id,
+        loading: "lazy",
+        allow: "autoplay; fullscreen",
+        allowfullscreen: true,
+        style: "border:0;width:100%;aspect-ratio:#{composition.width}/#{composition.height}"
+      }
+      tag.iframe(**defaults, **attributes)
+    end
+  end
+end

data/lib/animate_it/engine.rb

@@ -27,5 +27,9 @@ module AnimateIt
         AnimateIt.reload_compositions!
       end
     end
+
+    initializer "animate_it.embed_helper" do
+      ActiveSupport.on_load(:action_view) { include AnimateIt::EmbedHelper }
+    end
   end
 end