animate_it 0.1.0

data/lib/animate_it/video_renderer.rb

@@ -0,0 +1,219 @@
+require "fileutils"
+require "json"
+require "open3"
+require "shellwords"
+require "tempfile"
+require "uri"
+# `playwright` is a development-only gem (deploy image runs `bundle install
+# --without development test`). Defer loading until a render is actually
+# requested so production boot / asset precompile can load this file
+# without the gem present.
+
+module AnimateIt
+  class VideoRenderer
+    DEFAULT_PLAYWRIGHT_CLI = "npx playwright".freeze
+
+    # Lazy: Rails.root is nil at gem-load time (Bundler.require runs before
+    # Rails::Application is fully initialized).
+    def self.audio_base
+      @audio_base ||= Rails.root.join("app/audio").freeze
+    end
+
+    EXTENSION_FOR_FORMAT = {
+      mp4: "mp4",
+      webm: "webm",
+      mov: "mov",
+      gif: "gif",
+      png_sequence: nil,
+      png: "png"
+    }.freeze
+
+    AUDIO_INCAPABLE_FORMATS = %i[gif png_sequence png].freeze
+
+    attr_reader :composition, :host, :output_path, :frames_dir, :playwright_cli, :output_format
+
+    def initialize(composition:, host:, output_path:, frames_dir: nil, playwright_cli: nil, format: nil)
+      @composition = composition
+      @output_format = format || composition.output_format
+      @host = host.delete_suffix("/")
+      @output_path = Pathname(output_path)
+      @frames_dir = Pathname(frames_dir || Rails.root.join("tmp/animate_it/#{composition.id}"))
+      @playwright_cli = playwright_cli || ENV.fetch("PLAYWRIGHT_CLI_EXECUTABLE_PATH", DEFAULT_PLAYWRIGHT_CLI)
+
+      return unless audio_segments.any? && AUDIO_INCAPABLE_FORMATS.include?(@output_format)
+
+      raise Error,
+            "Composition #{composition.id} declares audio but format=#{@output_format} doesn't support audio. Use :webm/:mp4/:mov."
+    end
+
+    class CancelledError < AnimateIt::Error; end
+
+    def render(frame_range: nil, every_nth_frame: 1, props: {}, on_progress: nil, cancel_check: nil)
+      FileUtils.mkdir_p(frames_dir)
+      FileUtils.mkdir_p(output_path.dirname)
+
+      frame_list = frames(frame_range:, every_nth_frame:)
+      capture_status = capture_frames(frame_list, props:, on_progress:, cancel_check:)
+
+      if capture_status == :cancelled || cancel_check&.call
+        frame_count = contiguous_frame_count
+        encode_video(frame_count:) if frame_count.positive?
+        raise CancelledError, "Render cancelled"
+      end
+
+      encode_video
+      output_path
+    end
+
+    private
+
+    def frames(frame_range:, every_nth_frame:)
+      range = frame_range || (0...composition.duration_in_frames)
+      range.step(every_nth_frame).to_a
+    end
+
+    # One Playwright browser, one navigation, N screenshots — all frames are
+    # rendered in a single filmstrip page and we just toggle which one is
+    # visible between captures via window.__animateIt.setFrame(n).
+    def capture_frames(frame_list, props:, on_progress:, cancel_check:)
+      require "playwright" # development-only gem; lazy-loaded so deploy image boot doesn't fail
+      cancelled = false
+
+      Playwright.create(playwright_cli_executable_path: playwright_cli) do |pw|
+        browser = pw.chromium.launch(headless: true, args: ["--disable-web-security"])
+        begin
+          context = browser.new_context(
+            viewport: { width: composition.width, height: composition.height }
+          )
+          page = context.new_page
+
+          page.goto(filmstrip_url(props:), waitUntil: "networkidle")
+          page.wait_for_function('document.documentElement.dataset.animateItReady === "1"')
+
+          frame_list.each_with_index do |frame, index|
+            if cancel_check&.call
+              cancelled = true
+              break
+            end
+
+            page.evaluate("(n) => window.__animateIt.setFrame(n)", arg: frame)
+            screenshot_path = frames_dir.join(format("frame-%05d.png", index))
+            page.screenshot(path: screenshot_path.to_s, omitBackground: true)
+
+            on_progress&.call(frame + 1, frame_list.size)
+          end
+        ensure
+          browser&.close
+        end
+      end
+
+      cancelled || cancel_check&.call ? :cancelled : :complete
+    end
+
+    def filmstrip_url(props:)
+      query = { pp: "disable" }
+      query[:props_json] = JSON.generate(props) if props.present?
+
+      "#{host}#{AnimateIt.config.mount_path}/compositions/#{composition.id}/filmstrip?#{URI.encode_www_form(query)}"
+    end
+
+    def encode_video(frame_count: nil)
+      return if output_format == :png_sequence # frames already on disk; nothing to encode
+
+      if output_format == :png
+        # Single-frame still: copy the captured PNG straight to output_path.
+        # frame_range: (n..n) was passed to capture_frames so frame-00000.png
+        # is the only one we need.
+        FileUtils.cp(frames_dir.join("frame-00000.png"), output_path)
+        return
+      end
+
+      command = ["ffmpeg", "-y", "-framerate", composition.fps.to_s,
+                 "-i", frames_dir.join("frame-%05d.png").to_s]
+
+      audios = audio_segments
+      audios.each { |seg| command += ["-i", resolve_audio_path!(seg.source[:path])] }
+
+      command += video_codec_args
+      command += ["-frames:v", frame_count.to_s] if frame_count
+
+      if audios.any?
+        command += ["-filter_complex", audio_filter_graph(audios), "-map", "0:v", "-map", "[aout]", "-shortest"]
+        command += audio_codec_args
+      else
+        command += ["-an"] # explicit no-audio so output containers like .mov stay clean
+      end
+
+      command << output_path.to_s
+
+      run!(command)
+    end
+
+    def video_codec_args
+      case output_format
+      when :mp4
+        ["-c:v", "libx264", "-pix_fmt", "yuv420p", "-movflags", "+faststart"]
+      when :webm
+        ["-c:v", "libvpx-vp9", "-pix_fmt", "yuva420p", "-b:v", "0", "-crf", "30", "-row-mt", "1"]
+      when :mov
+        ["-c:v", "prores_ks", "-profile:v", "4444", "-pix_fmt", "yuva444p10le"]
+      when :gif
+        ["-filter_complex",
+         "split[s0][s1];[s0]palettegen=reserve_transparent=1[p];[s1][p]paletteuse=alpha_threshold=128"]
+      else
+        raise Error, "Unsupported format #{output_format.inspect}"
+      end
+    end
+
+    def audio_codec_args
+      case output_format
+      when :mp4 then ["-c:a", "aac", "-b:a", "192k"]
+      when :webm then ["-c:a", "libopus", "-b:a", "160k"]
+      when :mov  then ["-c:a", "pcm_s16le"]
+      else            []
+      end
+    end
+
+    # Build an `adelay=...|...,volume=g[aN]` chain per audio input, then mix.
+    def audio_filter_graph(audios)
+      ms_per_frame = 1000.0 / composition.fps
+      legs = audios.each_with_index.map do |seg, i|
+        delay_ms = (seg.from_frame * ms_per_frame).round
+        gain = seg.source[:gain] || 1.0
+        "[#{i + 1}:a]adelay=#{delay_ms}|#{delay_ms},volume=#{gain}[a#{i}]"
+      end
+      mix = "#{audios.length.times.map { |i| "[a#{i}]" }.join}amix=inputs=#{audios.length}:duration=longest[aout]"
+      [legs, mix].flatten.join(";")
+    end
+
+    def audio_segments
+      composition.timeline.segments.select { |seg| seg.kind == :audio }
+    end
+
+    def resolve_audio_path!(path)
+      candidate = Pathname.new(path).absolute? ? Pathname.new(path) : self.class.audio_base.join(path)
+      raise Error, "Audio file not found: #{path}" unless candidate.file?
+
+      candidate.to_s
+    end
+
+    def contiguous_frame_count
+      count = 0
+      loop do
+        path = frames_dir.join(format("frame-%05d.png", count))
+        break unless path.exist?
+
+        count += 1
+      end
+      count
+    end
+
+    def run!(command)
+      stdout, stderr, status = Open3.capture3(*command)
+      return if status.success?
+
+      quoted = command.shelljoin
+      raise Error, "Command failed: #{quoted}\n#{stdout}\n#{stderr}"
+    end
+  end
+end

data/lib/animate_it/view_helpers.rb

@@ -0,0 +1,84 @@
+module AnimateIt
+  module ViewHelpers
+    def style(*rules, **properties)
+      Style.build(*rules, **properties)
+    end
+
+    def absolute_fill(class_name: nil, style: nil, **attributes, &block)
+      content = block.call
+
+      tag.div(
+        **attributes,
+        class: ["animate-it-absolute-fill", class_name].compact,
+        style: absolute_fill_style(style)
+      ) do
+        content
+      end
+    end
+
+    def render_template(template, assigns: {}, **)
+      view_context.render(template:, assigns:, layout: false, **)
+    end
+
+    def render_scene_template(name, assigns: {}, **)
+      render_template("#{sidecar_template_root}/#{name}", assigns:, **)
+    end
+
+    def render_partial(partial, locals: {}, **)
+      view_context.render(partial:, locals:, **)
+    end
+
+    def motion_asset(path)
+      view_context.asset_path(path)
+    end
+
+    def motion_image(path, **attributes)
+      tag.img(**attributes, src: motion_asset(path))
+    end
+
+    def build_factory(name, *traits, **attributes)
+      raise AnimateIt::Error, "FactoryBot is not available" unless defined?(FactoryBot)
+
+      FactoryBot.build(name, *traits, **attributes)
+    end
+
+    def build_stubbed(name, *traits, **attributes)
+      raise AnimateIt::Error, "FactoryBot is not available" unless defined?(FactoryBot)
+
+      FactoryBot.build_stubbed(name, *traits, **attributes)
+    end
+
+    # Define singleton methods on `object` from a {name => value} hash.
+    # Non-callable values are auto-wrapped in a lambda that ignores its
+    # args, so `stub_methods(match, finished_state?: false)` works the
+    # same way as `stub_methods(match, finished_state?: -> { false })`.
+    # The wrapping lambda accepts `*args` so arity-bearing methods like
+    # `user_has_reviewed?(user)` don't raise ArgumentError on the
+    # value-shortcut form.
+    def stub_methods(object, **stubs)
+      stubs.each do |name, value|
+        body = value.respond_to?(:call) ? value : ->(*) { value }
+        object.define_singleton_method(name) { |*args| body.call(*args) }
+      end
+      object
+    end
+
+    private
+
+    def sidecar_template_root
+      context.composition.name.underscore
+    end
+
+    def absolute_fill_style(extra_style)
+      style(
+        "position: absolute",
+        "inset: 0",
+        "width: 100%",
+        "height: 100%",
+        "display: flex",
+        "flex-direction: column",
+        extra_style
+      )
+    end
+  end
+end

data/lib/animate_it.rb

@@ -0,0 +1,93 @@
+require_relative "animate_it/version"
+require_relative "animate_it/errors"
+require_relative "animate_it/frame_duration"
+require_relative "animate_it/units"
+require_relative "animate_it/style"
+require_relative "animate_it/easing"
+require_relative "animate_it/timing"
+require_relative "animate_it/animation_helpers"
+require_relative "animate_it/view_helpers"
+require_relative "animate_it/frame_context"
+require_relative "animate_it/props_schema"
+require_relative "animate_it/timeline"
+require_relative "animate_it/registry"
+require_relative "animate_it/render_store"
+require_relative "animate_it/beats"
+require_relative "animate_it/animation"
+require_relative "animate_it/scene"
+require_relative "animate_it/configuration"
+require_relative "animate_it/composition"
+require_relative "animate_it/output"
+require_relative "animate_it/video_renderer"
+require_relative "animate_it/asset_renderer"
+# Controllers (app/controllers/animate_it/*) and AnimateIt::RenderJob
+# (app/jobs/animate_it/render_job.rb) autoload via Rails — the engine's
+# `isolate_namespace AnimateIt` wires `app/` paths into the autoloader.
+
+module AnimateIt
+  class << self
+    delegate :register, to: :registry
+
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield(config)
+    end
+
+    def registry
+      @registry ||= Registry.new
+    end
+
+    def compositions
+      registry.all
+    end
+
+    def reset!
+      @registry = Registry.new
+    end
+
+    # Boot-time + dev-reload entry point. Wired by the engine's
+    # `to_prepare` initializer, which fires once at boot and on every
+    # autoloader reload after a watched file changes.
+    #
+    # The host's `app/videos` is in `config.autoload_paths` (set by the
+    # engine), so Zeitwerk owns the constants. On reload Zeitwerk has
+    # already `remove_const`'d every composition by the time we run, so
+    # `eager_load_dir` re-defines them fresh and the `inherited` hook
+    # fires — guaranteeing a clean Timeline / @beats / @outputs per
+    # reload (no stale segments accumulating across edits).
+    def load_compositions!
+      return unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+      videos_dir = Rails.root.join("app/videos")
+      return unless videos_dir.directory?
+
+      if defined?(Rails.autoloaders) && Rails.autoloaders.main.respond_to?(:eager_load_dir)
+        Rails.autoloaders.main.eager_load_dir(videos_dir.to_s)
+      else
+        # Fallback for environments without Zeitwerk eager_load_dir
+        # (older Rails / non-Zeitwerk autoloaders). `load` re-runs the
+        # file each time which is fine here because compositions are
+        # idempotent re-openable classes.
+        videos_dir.glob("**/*.rb").sort.each { |path| load(path.to_s) }
+      end
+
+      # After every composition class is loaded, give each one a chance
+      # to auto-mount its single nested Scene class (the single-scene
+      # shorthand). Idempotent: skips comps that already declared a
+      # `scene`/`series`/`audio`.
+      compositions.each(&:auto_mount_single_scene!)
+    end
+
+    # Dev-reload alias — clears the registry so a renamed or deleted
+    # composition id doesn't linger, then re-loads everything.
+    def reload_compositions!
+      registry.reset!
+      load_compositions!
+    end
+  end
+end
+
+require_relative "animate_it/engine" if defined?(Rails::Engine)

data/lib/generators/animate_it/install/install_generator.rb

@@ -0,0 +1,40 @@
+require "rails/generators/base"
+
+module AnimateIt
+  module Generators
+    # Installs AnimateIt into the host app:
+    #   bin/rails generate animate_it:install
+    #
+    # 1. Copies an opinionated initializer that owns engine config.
+    # 2. Inserts a `mount AnimateIt::Engine` line into config/routes.rb,
+    #    placed AFTER `devise_for` if Devise is in use (so warden serializers
+    #    register correctly — see config/routes.rb in the host app).
+    class InstallGenerator < ::Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      desc "Install AnimateIt: copy initializer and mount the engine in routes"
+
+      def copy_initializer
+        template "animate_it.rb", "config/routes.rb".sub("routes.rb", "initializers/animate_it.rb")
+      end
+
+      def add_route
+        routes_path = Rails.root.join("config/routes.rb")
+        contents = File.exist?(routes_path) ? File.read(routes_path) : ""
+
+        return say_status(:exists, "AnimateIt::Engine already mounted in config/routes.rb") if contents.include?("AnimateIt::Engine")
+
+        snippet = <<~ROUTE.chomp
+          \n  # AnimateIt engine — mount AFTER devise_for so warden serializers register correctly.
+            mount AnimateIt::Engine, at: AnimateIt.config.mount_path if Rails.env.local?
+        ROUTE
+
+        if contents.include?("devise_for")
+          inject_into_file "config/routes.rb", snippet, after: /devise_for[^\n]*\n/
+        else
+          route "mount AnimateIt::Engine, at: AnimateIt.config.mount_path if Rails.env.local?"
+        end
+      end
+    end
+  end
+end

data/lib/generators/animate_it/install/templates/animate_it.rb

@@ -0,0 +1,8 @@
+# AnimateIt configuration. The engine is loaded by Bundler from the
+# `gem "animate_it"` line in the Gemfile, so no manual require here.
+#
+# Change `mount_path` to relocate the Studio UI; `config/routes.rb` mounts
+# the engine at `AnimateIt.config.mount_path` (development/test only).
+AnimateIt.configure do |config|
+  config.mount_path = "/animate_it"
+end

data/lib/tasks/animate_it_tasks.rake

@@ -0,0 +1,83 @@
+def animate_it_render_host
+  # Prefer ANIMATE_IT_HOST; fall back to the legacy RAILS_MOTION_HOST, then
+  # RAILS_HOST, then localhost.
+  ENV["ANIMATE_IT_HOST"].presence ||
+    ENV["RAILS_MOTION_HOST"].presence ||
+    ENV["RAILS_HOST"].presence ||
+    "http://127.0.0.1:3000"
+end
+
+namespace :animate_it do
+  desc <<~DESC
+    Render a single composition's declared outputs to their asset paths.
+
+    Usage:
+      bin/rails 'animate_it:render[<composition-id>]'
+      bin/rails 'animate_it:render[<composition-id>,<start>..<end>]'   # render a subset of frames
+      bin/rails 'animate_it:render[<composition-id>,<start>-<end>]'    # same, dash-separated
+
+    When a frame range is given, animated outputs (mp4/webm/gif) are
+    encoded from just those frames — the result is a clipped preview
+    starting at frame <start>. Still PNG outputs still render at their
+    declared `frame:` and are skipped if that frame is outside the range.
+  DESC
+  task :render, %i[id frames] => :environment do |_t, args|
+    raise "Usage: bin/rails 'animate_it:render[<composition-id>,(<start>..<end>)?]'" if args[:id].blank?
+
+    AnimateIt.load_compositions!
+    composition = AnimateIt.registry.fetch(args[:id])
+    host = animate_it_render_host
+    frame_range = parse_frame_range(args[:frames], composition)
+    puts "Rendering frames #{frame_range.first}..#{frame_range.last} of #{composition.duration_in_frames}" if frame_range
+    written = AnimateIt::AssetRenderer.render_composition(
+      composition, host: host, on_progress: progress_logger, frame_range: frame_range
+    )
+    puts ""
+    written.compact.each { |path| puts "  → #{path.relative_path_from(Rails.root)}" }
+  end
+
+  desc "Render every registered composition's declared outputs"
+  task render_all: :environment do
+    AnimateIt.load_compositions!
+    host = animate_it_render_host
+
+    AnimateIt.compositions.each do |composition|
+      next if composition.outputs.empty?
+
+      label = "output#{"s" unless composition.outputs.size == 1}"
+      puts "Rendering #{composition.id} (#{composition.outputs.size} #{label})"
+      written = AnimateIt::AssetRenderer.render_composition(composition, host: host, on_progress: progress_logger)
+      puts ""
+      written.each { |path| puts "  → #{path.relative_path_from(Rails.root)}" }
+    end
+  end
+
+  # Parse `30..120` / `30-120` / `30` (single frame) into a Range. Returns
+  # nil for blank input, meaning "use the whole composition".
+  def parse_frame_range(raw, composition)
+    return nil if raw.blank?
+
+    if raw.match?(/\A\d+\z/)
+      n = raw.to_i
+      return n..n
+    end
+
+    match = raw.match(/\A(\d+)\s*(?:\.\.|-)\s*(\d+)\z/)
+    raise "Invalid frame range #{raw.inspect}. Use `start..end`, `start-end`, or a single frame number." unless match
+
+    start_frame = match[1].to_i
+    end_frame   = match[2].to_i
+    raise "Frame range start (#{start_frame}) must be <= end (#{end_frame})." if start_frame > end_frame
+
+    max = composition.duration_in_frames - 1
+    end_frame = max if end_frame > max
+    start_frame..end_frame
+  end
+
+  def progress_logger
+    lambda do |frame, total|
+      print "\r  frame #{frame} / #{total}"
+      $stdout.flush
+    end
+  end
+end

metadata

@@ -0,0 +1,120 @@
+--- !ruby/object:Gem::Specification
+name: animate_it
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- growth-constant
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 8.1.3
+description: |
+  AnimateIt is a mountable Rails engine for building videos as code. Declare a
+  composition (size, fps, duration, beats, audio), describe each frame with a
+  Ruby + HAML scene, preview it in the bundled Studio UI, and render it to
+  MP4/WebM/MOV/GIF with a headless Chromium (Playwright) frame capture piped
+  through FFmpeg.
+executables:
+- render_animate_it_video
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- MIT-LICENSE
+- README.md
+- app/controllers/animate_it/application_controller.rb
+- app/controllers/animate_it/audio_controller.rb
+- app/controllers/animate_it/frames_controller.rb
+- app/controllers/animate_it/props_controller.rb
+- app/controllers/animate_it/renders_controller.rb
+- app/controllers/animate_it/studio_controller.rb
+- app/jobs/animate_it/application_job.rb
+- app/jobs/animate_it/render_job.rb
+- app/views/animate_it/frames/filmstrip.html.haml
+- app/views/animate_it/frames/fragment.html.haml
+- app/views/animate_it/frames/show.html.haml
+- app/views/animate_it/props/_form.html.haml
+- app/views/animate_it/props/update.html.haml
+- app/views/animate_it/renders/create.html.haml
+- app/views/animate_it/renders/show.html.haml
+- app/views/animate_it/studio/_composition_list.html.haml
+- app/views/animate_it/studio/_preview_pane.html.haml
+- app/views/animate_it/studio/_props_pane.html.haml
+- app/views/animate_it/studio/_studio_script.html.haml
+- app/views/animate_it/studio/_studio_styles.html.haml
+- app/views/animate_it/studio/_timeline_lanes.html.haml
+- app/views/animate_it/studio/index.html.haml
+- app/views/animate_it/studio/show.html.haml
+- app/views/layouts/animate_it/application.html.haml
+- config/routes.rb
+- exe/render_animate_it_video
+- lib/animate_it.rb
+- lib/animate_it/animation.rb
+- lib/animate_it/animation_helpers.rb
+- lib/animate_it/asset_renderer.rb
+- lib/animate_it/beats.rb
+- lib/animate_it/composition.rb
+- lib/animate_it/configuration.rb
+- lib/animate_it/easing.rb
+- lib/animate_it/engine.rb
+- lib/animate_it/errors.rb
+- lib/animate_it/frame_context.rb
+- lib/animate_it/frame_duration.rb
+- lib/animate_it/output.rb
+- lib/animate_it/props_schema.rb
+- lib/animate_it/registry.rb
+- lib/animate_it/render_store.rb
+- lib/animate_it/scene.rb
+- lib/animate_it/style.rb
+- lib/animate_it/timeline.rb
+- lib/animate_it/timing.rb
+- lib/animate_it/units.rb
+- lib/animate_it/version.rb
+- lib/animate_it/video_renderer.rb
+- lib/animate_it/view_helpers.rb
+- lib/generators/animate_it/install/install_generator.rb
+- lib/generators/animate_it/install/templates/animate_it.rb
+- lib/tasks/animate_it_tasks.rake
+homepage: https://github.com/growth-constant/animate_it
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/growth-constant/animate_it
+  source_code_uri: https://github.com/growth-constant/animate_it
+  changelog_uri: https://github.com/growth-constant/animate_it/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/growth-constant/animate_it/issues
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Declarative, frame-driven video compositions for Rails, rendered with Playwright
+  + FFmpeg
+test_files: []