animate_it 0.1.0

data/config/routes.rb

@@ -0,0 +1,12 @@
+AnimateIt::Engine.routes.draw do
+  root "studio#index"
+
+  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/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
+  post "renders/:id/cancel", to: "renders#cancel", as: :cancel_render
+  get "renders/:id", to: "renders#show", as: :render
+end

data/exe/render_animate_it_video

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Render an AnimateIt composition: one Playwright browser pointed at the
+# filmstrip endpoint scrubs frames in-page, screenshots each, and FFmpeg
+# stitches them into a video.
+#
+# Run from your Rails app root (the app whose app/videos/ defines the
+# composition), with a Rails server already running at ANIMATE_IT_HOST:
+#
+#   bundle exec render_animate_it_video my-composition
+#   bundle exec render_animate_it_video my-composition tmp/my-composition.mp4
+#
+# Host resolution: ANIMATE_IT_HOST, then the legacy RAILS_MOTION_HOST, then
+# RAILS_HOST, then http://127.0.0.1:3000.
+
+env_path = File.expand_path("config/environment.rb", Dir.pwd)
+unless File.exist?(env_path)
+  abort "render_animate_it_video: run this from your Rails app root (no config/environment.rb in #{Dir.pwd})."
+end
+require env_path
+
+composition_id = ARGV[0]
+abort "Usage: render_animate_it_video <composition-id> [output-path]" if composition_id.to_s.empty?
+
+host = ENV["ANIMATE_IT_HOST"].to_s.dup
+host = ENV["RAILS_MOTION_HOST"].to_s if host.empty?
+host = ENV["RAILS_HOST"].to_s if host.empty?
+host = "http://127.0.0.1:3000" if host.empty?
+
+AnimateIt.load_compositions!
+composition = AnimateIt.registry.fetch(composition_id)
+
+extension = AnimateIt::VideoRenderer::EXTENSION_FOR_FORMAT.fetch(composition.output_format) || "mp4"
+output_path = ARGV[1] || Rails.root.join("tmp/animate_it/#{composition_id}.#{extension}").to_s
+
+puts "Rendering #{composition.id} (#{composition.width}x#{composition.height}, #{composition.fps}fps, #{composition.duration_in_frames} frames)"
+
+started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+output = AnimateIt::VideoRenderer.new(
+  composition:,
+  host:,
+  output_path:
+).render(
+  on_progress: lambda do |frame, total|
+    print "\r  frame #{frame} / #{total}"
+    $stdout.flush
+  end
+)
+puts ""
+elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at
+
+puts format("Wrote %<output>s in %<elapsed>.2fs", output: output, elapsed: elapsed)

data/lib/animate_it/animation.rb

@@ -0,0 +1,189 @@
+module AnimateIt
+  # ----- Per-animatable property declaration ----------------------------
+  # One CSS-driven animation slot on a `data-anim="..."` element. The
+  # framework turns these into both:
+  #   1. CSS variables on the wrapper (set per frame at render time), and
+  #   2. CSS rules of the form `[data-anim="name"] { property: var(--…); }`
+  #      injected into the rendered HTML so the HAML doesn't need a `:css`
+  #      block to bind variables to selectors.
+  AnimationProperty = Data.define(:css_property, :var_suffix, :unit, :default, :keyframes_to_values) do
+    def var_name(animatable_name)
+      "--#{animatable_name.to_s.tr("_", "-")}-#{var_suffix.to_s.tr("_", "-")}"
+    end
+  end
+
+  AnimatableElement = Data.define(:name, :properties)
+
+  class AnimationSet
+    attr_reader :elements
+
+    def initialize
+      @elements = {}
+    end
+
+    def add(name, builder_block)
+      builder = AnimatableBuilder.new(name)
+      builder.instance_eval(&builder_block) if builder_block
+      @elements[name.to_sym] = AnimatableElement.new(name: name.to_sym, properties: builder.properties)
+    end
+
+    # Compute the per-frame CSS variable hash for the entire set, given the
+    # current local_frame plus a beats registry to resolve symbolic ranges.
+    def vars_for(scene)
+      vars = {}
+      @elements.each_value do |element|
+        element.properties.each do |prop|
+          value = compute_value(prop, scene)
+          vars[var_key(element.name, prop.var_suffix)] = format_value(value, prop.unit)
+        end
+      end
+      vars
+    end
+
+    # Emit `<style>` block content with `[data-anim="name"] { … }` rules.
+    # Generated once per AnimationSet (memoized).
+    def css_rules
+      @css_rules ||= @elements.values.map { |element| rules_for(element) }.join("\n")
+    end
+
+    private
+
+    def var_key(name, suffix)
+      :"#{name}_#{suffix}"
+    end
+
+    def rules_for(element)
+      transforms = []
+      direct_props = []
+      element.properties.each do |prop|
+        var_ref = "var(#{prop.var_name(element.name)}, #{format_default(prop.default, prop.unit)})"
+        case prop.css_property
+        when :translate_y then transforms << "translateY(#{var_ref})"
+        when :translate_x then transforms << "translateX(#{var_ref})"
+        when :scale       then transforms << "scale(#{var_ref})"
+        when :rotate      then transforms << "rotate(#{var_ref})"
+        else
+          direct_props << "#{prop.css_property.to_s.tr("_", "-")}: #{var_ref};"
+        end
+      end
+      direct_props << "transform: #{transforms.join(" ")};" if transforms.any?
+      # HTML data attribute convention is hyphens, not underscores.
+      selector_name = element.name.to_s.tr("_", "-")
+      "[data-anim=\"#{selector_name}\"] { #{direct_props.join(" ")} transition: none; will-change: opacity, transform; }"
+    end
+
+    def compute_value(prop, scene)
+      keyframes = prop.keyframes_to_values.call(scene)
+      frames = keyframes.keys
+      values = keyframes.values
+      scene.interpolate(scene.local_frame, frames, values, easing: :ease_out, extrapolate_left: :clamp,
+                                                           extrapolate_right: :clamp).round(4)
+    end
+
+    def format_value(value, unit)
+      unit ? "#{value}#{unit}" : value
+    end
+
+    def format_default(default, unit)
+      unit ? "#{default}#{unit}" : default
+    end
+  end
+
+  # ----- Per-element DSL ------------------------------------------------
+  class AnimatableBuilder
+    attr_reader :properties
+
+    def initialize(name)
+      @name = name
+      @properties = []
+    end
+
+    # Opacity 0→1 over a frame range (or beat name, or keyframe hash).
+    def fade(during: nil, in: nil, out: nil, keyframes: nil, from: 0, to: 1)
+      add_property(:opacity, :opacity, nil, from,
+                   build_keyframes(during, binding.local_variable_get(:in), out, keyframes, from: from, to: to))
+    end
+
+    # Vertical translate `from`→`to` over a frame range.
+    def slide(during: nil, keyframes: nil, from: 16, to: 0, axis: :y, unit: "px")
+      css = axis == :y ? :translate_y : :translate_x
+      add_property(css, css, unit, from, build_keyframes(during, nil, nil, keyframes, from: from, to: to))
+    end
+
+    def scale(during: nil, keyframes: nil, from: 1, to: 1.05)
+      add_property(:scale, :scale, nil, from, build_keyframes(during, nil, nil, keyframes, from: from, to: to))
+    end
+
+    # Generic CSS property — when the named helpers (fade/slide/scale) don't
+    # cover what you need (max-height, height, color, etc.).
+    def css(property, from:, during: nil, keyframes: nil, to: nil, unit: nil)
+      kf = build_keyframes(during, nil, nil, keyframes, from: from, to: to.nil? ? from : to)
+      add_property(property, property, unit, from, kf)
+    end
+
+    private
+
+    def add_property(css_property, var_suffix, unit, default, keyframes_proc)
+      @properties << AnimationProperty.new(
+        css_property: css_property,
+        var_suffix: var_suffix,
+        unit: unit,
+        default: default,
+        keyframes_to_values: keyframes_proc
+      )
+    end
+
+    # Returns a Proc that, given a Scene with access to the composition's
+    # beats registry, resolves any symbolic ranges (beat names) into a
+    # frame→value Hash suitable for interpolation.
+    def build_keyframes(during, in_range, out_range, keyframes_arg, from:, to:)
+      lambda do |scene|
+        if keyframes_arg
+          resolve_keyframe_hash(keyframes_arg, scene)
+        elsif during
+          range = resolve_range(during, scene)
+          { range.first => from, range.last => to }
+        elsif in_range && out_range
+          a = resolve_range(in_range, scene)
+          b = resolve_range(out_range, scene)
+          { a.first => from, a.last => to, b.first => to, b.last => from }
+        elsif in_range
+          a = resolve_range(in_range, scene)
+          { a.first => from, a.last => to }
+        elsif out_range
+          b = resolve_range(out_range, scene)
+          { b.first => to, b.last => from }
+        else
+          { 0 => from }
+        end
+      end
+    end
+
+    def resolve_range(input, scene)
+      case input
+      when Range
+        Range.new(resolve_frame(input.first, scene), resolve_frame(input.last, scene))
+      when Symbol
+        scene.composition_class.beats.fetch(input).range
+      else
+        raise Error, "Don't know how to resolve range #{input.inspect}"
+      end
+    end
+
+    def resolve_keyframe_hash(hash, scene)
+      hash.each_with_object({}) do |(k, v), out|
+        out[resolve_frame(k, scene)] = v
+      end
+    end
+
+    def resolve_frame(value, scene)
+      case value
+      when Integer then value
+      when Float then value.to_i
+      when Symbol then scene.composition_class.beats.fetch(value).start_frame
+      else
+        AnimateIt::Units.frames(value, fps: scene.fps).to_i
+      end
+    end
+  end
+end

data/lib/animate_it/animation_helpers.rb

@@ -0,0 +1,86 @@
+module AnimateIt
+  module AnimationHelpers
+    def animation_vars(**properties)
+      Style.vars(**properties)
+    end
+
+    def fade(start_frame, end_frame, from: 0, to: 1, easing: :ease_out)
+      interpolate_range([start_frame, end_frame], [from, to], easing:)
+    end
+
+    def slide(start_frame, end_frame, from: 16, to: 0, easing: :ease_out)
+      interpolate_range([start_frame, end_frame], [from, to], easing:)
+    end
+
+    def press(start_frame, middle_frame, end_frame, from: 1.0, to: 1.08, easing: :ease_out)
+      interpolate_range([start_frame, middle_frame, end_frame], [from, to, from], easing:)
+    end
+
+    def pulse(start_frame, middle_frame, end_frame, from:, to:, back_to: from, easing: :ease_out)
+      interpolate_range([start_frame, middle_frame, end_frame], [from, to, back_to], easing:)
+    end
+
+    def interpolate_range(input_range, output_range, easing: :ease_out)
+      interpolate(
+        local_frame,
+        input_range,
+        output_range,
+        easing:,
+        extrapolate_left: :clamp,
+        extrapolate_right: :clamp
+      ).round(4)
+    end
+
+    def loop_frame(duration, frame: local_frame)
+      frame % AnimateIt::Units.frames(duration, fps:)
+    end
+
+    def loop_iteration(duration, frame: local_frame)
+      frame / AnimateIt::Units.frames(duration, fps:)
+    end
+
+    def freeze_frame(frozen_frame, active: true)
+      active.respond_to?(:call) && !active.call(local_frame) ? local_frame : frozen_frame
+    end
+
+    def act_local(beat_name)
+      local_frame - composition_class.beats.fetch(beat_name).start_frame
+    end
+
+    def at_act(beat_name, ranges, values, easing: :ease_out)
+      interpolate(
+        act_local(beat_name),
+        ranges,
+        values,
+        easing:,
+        extrapolate_left: :clamp,
+        extrapolate_right: :clamp
+      ).round(4)
+    end
+
+    def at_global(ranges, values, easing: :ease_out)
+      interpolate(
+        local_frame,
+        ranges,
+        values,
+        easing:,
+        extrapolate_left: :clamp,
+        extrapolate_right: :clamp
+      ).round(4)
+    end
+
+    def beat_frame(beat_name)
+      composition_class.beats.fetch(beat_name).start_frame
+    end
+
+    def beat_end(beat_name)
+      beat = composition_class.beats.fetch(beat_name)
+      beat.start_frame + beat.duration_frames
+    end
+
+    def beat_range(beat_name)
+      beat = composition_class.beats.fetch(beat_name)
+      [beat.start_frame, beat.start_frame + beat.duration_frames]
+    end
+  end
+end

data/lib/animate_it/asset_renderer.rb

@@ -0,0 +1,49 @@
+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).
+  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?
+
+      composition.outputs.map do |output|
+        render_output(composition, output, host: host, on_progress: on_progress, frame_range: frame_range)
+      end
+    end
+
+    def render_output(composition, output, host:, on_progress: nil, frame_range: nil)
+      effective_range = effective_range_for(output, frame_range)
+      return nil if effective_range == :skip
+
+      destination = output.absolute_path
+      FileUtils.mkdir_p(destination.dirname)
+
+      renderer = VideoRenderer.new(
+        composition: composition,
+        host: host,
+        output_path: destination,
+        format: output.format
+      )
+
+      renderer.render(frame_range: effective_range, on_progress: on_progress)
+      destination
+    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
+    # render the full composition.
+    def effective_range_for(output, frame_range)
+      if output.still?
+        return :skip if frame_range && !frame_range.cover?(output.frame)
+
+        output.frame..output.frame
+      else
+        frame_range
+      end
+    end
+  end
+end

data/lib/animate_it/beats.rb

@@ -0,0 +1,61 @@
+module AnimateIt
+  # A named time marker on a Composition's timeline. Beats let you give
+  # frame ranges meaningful names ("intro", "voice_note", "thinking") and
+  # reference them from animations:
+  #
+  #   beat :voice_note, at: "5.5s", length: "0.67s"
+  #   animate :step_2 do
+  #     fade in: :voice_note
+  #   end
+  Beat = Data.define(:name, :start_frame, :duration_frames) do
+    def end_frame
+      start_frame + duration_frames
+    end
+
+    # Inclusive: `range.last` is the last frame the beat covers.
+    def range
+      start_frame..end_frame
+    end
+
+    def first_half
+      half = duration_frames / 2
+      start_frame..(start_frame + half)
+    end
+
+    def second_half
+      half = duration_frames / 2
+      (start_frame + half)..end_frame
+    end
+  end
+
+  class Beats
+    def initialize(fps:)
+      @fps = fps
+      @beats = {}
+    end
+
+    def add(name, at:, length:)
+      @beats[name.to_sym] = Beat.new(
+        name: name.to_sym,
+        start_frame: AnimateIt::Units.frames(at, fps: @fps).to_i,
+        duration_frames: AnimateIt::Units.frames(length, fps: @fps).to_i
+      )
+    end
+
+    def fetch(name)
+      @beats.fetch(name.to_sym) do
+        raise Error, "Unknown beat: #{name.inspect}. Declared: #{@beats.keys.inspect}"
+      end
+    end
+
+    def [](name)
+      @beats[name.to_sym]
+    end
+
+    def all
+      @beats.values
+    end
+
+    delegate :empty?, to: :@beats
+  end
+end