animate_it 0.3.2 → 0.5.0

data/lib/animate_it/video_renderer.rb

@@ -39,34 +39,49 @@ module AnimateIt
       @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)
+    def render(frame_range: nil, every_nth_frame: 1, props: {}, on_progress: nil, cancel_check: nil,
+               reuse_captured_frames: false)
       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 reuse_captured_frames
+        validate_captured_frames!(frame_list.size)
+        capture_status = :complete
+      else
+        clear_captured_frames!
+        capture_status = capture_frames(frame_list, props:, on_progress:, cancel_check:)
+      end
 
       if capture_status == :cancelled || cancel_check&.call
         frame_count = contiguous_frame_count
-        encode_video(frame_count:) if frame_count.positive?
+        encode_video(frame_count:, start_frame: frame_list.first) if frame_count.positive?
         raise CancelledError, "Render cancelled"
       end
 
-      encode_video
+      encode_video(frame_count: frame_list.size, start_frame: frame_list.first)
       output_path
     end
 
     private
 
+    def clear_captured_frames!
+      Dir.glob(frames_dir.join("frame-*.png")).each { |path| FileUtils.rm_f(path) }
+    end
+
+    def validate_captured_frames!(frame_count)
+      missing = frame_count.times.find do |index|
+        !frames_dir.join(format("frame-%05d.png", index)).file?
+      end
+      return unless missing
+
+      raise Error, "Captured frame not found: #{frames_dir.join(format("frame-%05d.png", missing))}"
+    end
+
     def frames(frame_range:, every_nth_frame:)
       range = frame_range || (0...composition.duration_in_frames)
       range.step(every_nth_frame).to_a
@@ -87,7 +102,7 @@ module AnimateIt
           )
           page = context.new_page
 
-          page.goto(filmstrip_url(props:), waitUntil: "networkidle")
+          page.goto(page_url(props:), waitUntil: "networkidle")
           page.wait_for_function('document.documentElement.dataset.animateItReady === "1"')
 
           frame_list.each_with_index do |frame, index|
@@ -110,15 +125,19 @@ module AnimateIt
       cancelled || cancel_check&.call ? :cancelled : :complete
     end
 
-    def filmstrip_url(props:)
+    def page_url(props:)
       query = { pp: "disable" }
       query[:props_json] = JSON.generate(props) if props.present?
+      endpoint = composition.client_driven? ? "player" : "filmstrip"
 
-      "#{host}#{AnimateIt.config.mount_path}/compositions/#{composition.id}/filmstrip?#{URI.encode_www_form(query)}"
+      "#{host}#{AnimateIt.config.mount_path}/compositions/#{composition.id}/#{endpoint}?#{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
+    def encode_video(frame_count: nil, start_frame: 0)
+      if output_format == :png_sequence
+        publish_png_sequence(frame_count || contiguous_frame_count)
+        return
+      end
 
       if output_format == :png
         # Single-frame still: copy the captured PNG straight to output_path.
@@ -131,14 +150,24 @@ module AnimateIt
       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])] }
+      clip_frame_count = frame_count || composition.duration_in_frames
+      audios = audio_capable? ? audio_segments(start_frame:, frame_count: clip_frame_count) : []
+      audios.each do |segment|
+        command += ["-stream_loop", "-1"] if segment.source[:loop]
+        command += ["-i", resolve_audio_path!(segment.source[:path])]
+      end
 
       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 += [
+          "-filter_complex",
+          audio_filter_graph(audios, start_frame:, frame_count: clip_frame_count),
+          "-map", "0:v",
+          "-map", "[aout]",
+          "-shortest"
+        ]
         command += audio_codec_args
       else
         command += ["-an"] # explicit no-audio so output containers like .mov stay clean
@@ -149,6 +178,19 @@ module AnimateIt
       run!(command)
     end
 
+    def publish_png_sequence(frame_count)
+      FileUtils.mkdir_p(output_path)
+      Dir.glob(output_path.join("frame-*.png")).each { |path| FileUtils.rm_f(path) }
+
+      frame_count.times do |index|
+        filename = format("frame-%05d.png", index)
+        source = frames_dir.join(filename)
+        raise Error, "Captured frame not found: #{source}" unless source.file?
+
+        FileUtils.cp(source, output_path.join(filename))
+      end
+    end
+
     def video_codec_args
       case output_format
       when :mp4
@@ -174,23 +216,44 @@ module AnimateIt
       end
     end
 
-    # Build an `adelay=...|...,volume=g[aN]` chain per audio input, then mix.
-    def audio_filter_graph(audios)
+    # Trim each source to its timeline window before delaying and mixing it.
+    def audio_filter_graph(audios, start_frame: 0, frame_count: composition.duration_in_frames)
       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}]"
+      clip_end_frame = start_frame + frame_count
+      legs = audios.each_with_index.map do |segment, index|
+        segment_end_frame = segment.duration_frames ? segment.from_frame + segment.duration_frames : composition.duration_in_frames
+        overlap_start_frame = [segment.from_frame, start_frame].max
+        overlap_end_frame = [segment_end_frame, clip_end_frame].min
+        source_start_seconds = (overlap_start_frame - segment.from_frame).fdiv(composition.fps)
+        overlap_seconds = (overlap_end_frame - overlap_start_frame).fdiv(composition.fps)
+        delay_ms = ((overlap_start_frame - start_frame) * ms_per_frame).round
+        gain = segment.source[:gain] || 1.0
+        "[#{index + 1}:a]atrim=start=#{source_start_seconds}:duration=#{overlap_seconds}," \
+          "asetpts=PTS-STARTPTS," \
+          "adelay=#{delay_ms}|#{delay_ms},volume=#{gain}[a#{index}]"
       end
       # normalize=0: amix's default rescales every input by 1/N, which
       # silently buries a voice-over under a music bed the moment a second
       # track is declared. Declared gains are the only intended scaling.
-      mix = "#{audios.length.times.map { |i| "[a#{i}]" }.join}amix=inputs=#{audios.length}:duration=longest:normalize=0[aout]"
+      clip_seconds = frame_count.fdiv(composition.fps)
+      mix = "#{audios.length.times.map { |i| "[a#{i}]" }.join}" \
+            "amix=inputs=#{audios.length}:duration=longest:normalize=0," \
+            "apad=whole_dur=#{clip_seconds},atrim=duration=#{clip_seconds}[aout]"
       [legs, mix].flatten.join(";")
     end
 
-    def audio_segments
-      composition.timeline.segments.select { |seg| seg.kind == :audio }
+    def audio_segments(start_frame: 0, frame_count: composition.duration_in_frames)
+      clip_end_frame = start_frame + frame_count
+      composition.timeline.segments.select do |segment|
+        next false unless segment.kind == :audio
+
+        segment_end_frame = segment.duration_frames ? segment.from_frame + segment.duration_frames : composition.duration_in_frames
+        segment.from_frame < clip_end_frame && segment_end_frame > start_frame
+      end
+    end
+
+    def audio_capable?
+      AUDIO_INCAPABLE_FORMATS.exclude?(output_format)
     end
 
     def resolve_audio_path!(path)

data/lib/animate_it/view_helpers.rb

@@ -4,9 +4,14 @@ module AnimateIt
       Style.build(*rules, **properties)
     end
 
-    def absolute_fill(class_name: nil, style: nil, **attributes, &block)
+    def absolute_fill(class_name: nil, style: nil, vars: nil, **attributes, &block)
       content = block.call
 
+      if vars
+        style = [style.presence, animation_vars(vars)].compact.join("; ")
+        attributes = { data: { animate_vars: vars } }.deep_merge(attributes)
+      end
+
       tag.div(
         **attributes,
         class: ["animate-it-absolute-fill", class_name].compact,
@@ -16,6 +21,11 @@ module AnimateIt
       end
     end
 
+    def animate_text(key, tag_name: :span, **attributes)
+      attributes = { data: { animate_text: key } }.deep_merge(attributes)
+      tag.public_send(tag_name, evaluate_text_track(key).to_s, **attributes)
+    end
+
     def render_template(template, assigns: {}, **)
       view_context.render(template:, assigns:, layout: false, **)
     end

data/lib/animate_it.rb

@@ -1,3 +1,6 @@
+require "active_support"
+require "active_support/core_ext"
+
 require_relative "animate_it/version"
 require_relative "animate_it/errors"
 require_relative "animate_it/frame_duration"
@@ -13,13 +16,27 @@ 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/chapters"
 require_relative "animate_it/animation"
+require_relative "animate_it/text_effects"
 require_relative "animate_it/scene"
 require_relative "animate_it/configuration"
 require_relative "animate_it/composition"
+require_relative "animate_it/tracks/layer"
+require_relative "animate_it/tracks/document"
+require_relative "animate_it/tracks/recorder"
+require_relative "animate_it/track_document_schema"
+require_relative "animate_it/player_manifest"
+require_relative "animate_it/embed_styles"
+require_relative "animate_it/chapter_navigation"
+require_relative "animate_it/embed_runtime"
+require_relative "animate_it/runtime"
+require_relative "animate_it/embed_helper"
 require_relative "animate_it/output"
 require_relative "animate_it/video_renderer"
+require_relative "animate_it/verification"
 require_relative "animate_it/asset_renderer"
+require_relative "animate_it/asset_manifest"
 # 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.

data/lib/tasks/animate_it_tasks.rake

@@ -1,3 +1,5 @@
+require "json"
+
 def animate_it_render_host
   # Prefer ANIMATE_IT_HOST; fall back to the legacy RAILS_MOTION_HOST, then
   # RAILS_HOST, then localhost.
@@ -8,6 +10,12 @@ def animate_it_render_host
 end
 
 namespace :animate_it do
+  desc "Validate source assets and provenance required by AnimateIt compositions"
+  task preflight: :environment do
+    result = AnimateIt::AssetManifest.new.validate!
+    puts "AnimateIt asset preflight passed (#{result.checked} assets)."
+  end
+
   desc <<~DESC
     Render a single composition's declared outputs to their asset paths.
 
@@ -52,6 +60,61 @@ namespace :animate_it do
     end
   end
 
+  desc <<~DESC
+    Pixel-diff a composition's client-driven /player page against the legacy
+    /filmstrip. Samples every <step>-th frame (default 10; use 1 for the full
+    gate) plus structural layer boundaries and adjacent frames.
+
+    Requires a running Rails server.
+
+    Usage:
+      bin/rails 'animate_it:verify[<composition-id>]'
+      bin/rails 'animate_it:verify[<composition-id>,1]'
+      ANIMATE_IT_PROPS_JSON='{"title":"Variant"}' bin/rails 'animate_it:verify[<composition-id>,1]'
+      ANIMATE_IT_PROPS_MATRIX_JSON='[{}, {"title":"Variant"}]' bin/rails 'animate_it:verify[<composition-id>,1]'
+
+    Set ANIMATE_IT_READY_TIMEOUT_MS to override the 30000ms readiness timeout.
+  DESC
+  task :verify, %i[id step] => :environment do |_task, args|
+    raise "Usage: bin/rails 'animate_it:verify[<composition-id>,(<step>)?]'" if args[:id].blank?
+
+    AnimateIt.load_compositions!
+    composition = AnimateIt.registry.fetch(args[:id])
+    verify_composition!(
+      composition,
+      host: animate_it_render_host,
+      step: (args[:step] || 10).to_i,
+      props_variants: verification_props_variants(composition)
+    )
+  end
+
+  desc <<~DESC
+    Every-frame verification gate for every client-driven composition and each
+    composition's declared `verification_props` variant.
+
+    Requires a running Rails server.
+
+    Usage:
+      bin/rails animate_it:verify_all
+      ANIMATE_IT_PROPS_MATRIX_JSON='[{}, {"title":"Variant"}]' bin/rails animate_it:verify_all
+  DESC
+  task verify_all: :environment do
+    AnimateIt.load_compositions!
+    compositions = AnimateIt.compositions.select(&:client_driven?)
+    raise "No client-driven AnimateIt compositions are registered" if compositions.empty?
+
+    compositions.each do |composition|
+      verify_composition!(
+        composition,
+        host: animate_it_render_host,
+        step: 1,
+        props_variants: verification_props_variants(composition)
+      )
+    end
+
+    puts "Verified #{compositions.size} client-driven compositions at every frame."
+  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)
@@ -80,4 +143,74 @@ namespace :animate_it do
       $stdout.flush
     end
   end
+
+  def verification_props_variants(composition)
+    matrix_json = ENV.fetch("ANIMATE_IT_PROPS_MATRIX_JSON", nil)
+    single_json = ENV.fetch("ANIMATE_IT_PROPS_JSON", nil)
+    return parse_props_matrix(matrix_json) if matrix_json.present?
+    return [parse_props(single_json, "ANIMATE_IT_PROPS_JSON")] if single_json.present?
+
+    composition.verification_props
+  end
+
+  def parse_props_matrix(raw)
+    variants = JSON.parse(raw)
+    valid_matrix = variants.is_a?(Array) && variants.present? && variants.all?(Hash)
+    raise "ANIMATE_IT_PROPS_MATRIX_JSON must contain a non-empty JSON array of objects" unless valid_matrix
+
+    variants.map(&:deep_symbolize_keys)
+  rescue JSON::ParserError => e
+    raise "ANIMATE_IT_PROPS_MATRIX_JSON must contain a JSON array of objects: #{e.message}"
+  end
+
+  def parse_props(raw, name)
+    props = JSON.parse(raw)
+    raise "#{name} must contain a JSON object" unless props.is_a?(Hash)
+
+    props.deep_symbolize_keys
+  rescue JSON::ParserError => e
+    raise "#{name} must contain a JSON object: #{e.message}"
+  end
+
+  def verify_composition!(composition, host:, step:, props_variants:)
+    props_variants.each_with_index do |props, variant_index|
+      output_dir = Rails.root.join("tmp/animate_it/verify/#{composition.id}/variant-#{variant_index + 1}")
+      verification = AnimateIt::Verification.new(
+        composition:,
+        host:,
+        step:,
+        props:,
+        output_dir:,
+        ready_timeout: ENV.fetch("ANIMATE_IT_READY_TIMEOUT_MS", 30_000).to_i
+      )
+      puts "Verifying #{composition.id} variant #{variant_index + 1}/#{props_variants.size}: " \
+           "#{verification.sample_frames.size} frames (step #{verification.step}, " \
+           "RGB threshold #{verification.threshold}dB, alpha threshold #{verification.alpha_threshold}dB)"
+
+      results = verification.call
+      failures = results.reject(&:passed)
+      print_verification_results(results)
+      if failures.any?
+        raise "#{failures.size}/#{results.size} frames below threshold. " \
+              "Screenshots in #{verification.output_dir}"
+      end
+
+      puts "All #{results.size} frames match " \
+           "(RGB >= #{verification.threshold}dB, alpha >= #{verification.alpha_threshold}dB)."
+    end
+  end
+
+  def print_verification_results(results)
+    results.each do |result|
+      rgb = result.rgb_psnr.infinite? ? "identical" : format("%.2fdB", result.rgb_psnr)
+      alpha = result.alpha_psnr.infinite? ? "identical" : format("%.2fdB", result.alpha_psnr)
+      puts format(
+        "  frame %<frame>5d  RGB %<rgb>s  alpha %<alpha>s%<flag>s",
+        frame: result.frame,
+        rgb:,
+        alpha:,
+        flag: result.passed ? "" : "  ← FAIL"
+      )
+    end
+  end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: animate_it
 version: !ruby/object:Gem::Version
-  version: 0.3.2
+  version: 0.5.0
 platform: ruby
 authors:
 - growth-constant
@@ -58,14 +58,17 @@ files:
 - README.md
 - app/controllers/animate_it/application_controller.rb
 - app/controllers/animate_it/audio_controller.rb
+- app/controllers/animate_it/embed_assets_controller.rb
 - app/controllers/animate_it/frames_controller.rb
 - app/controllers/animate_it/props_controller.rb
+- app/controllers/animate_it/public_players_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/player.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
@@ -85,38 +88,54 @@ files:
 - lib/animate_it.rb
 - lib/animate_it/animation.rb
 - lib/animate_it/animation_helpers.rb
+- lib/animate_it/asset_manifest.rb
 - lib/animate_it/asset_renderer.rb
 - lib/animate_it/beats.rb
+- lib/animate_it/chapter_navigation.rb
+- lib/animate_it/chapters.rb
 - lib/animate_it/composition.rb
 - lib/animate_it/configuration.rb
 - lib/animate_it/easing.rb
+- lib/animate_it/embed_helper.rb
+- lib/animate_it/embed_runtime.rb
+- lib/animate_it/embed_runtime/embed.js
+- lib/animate_it/embed_styles.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/player_manifest.rb
 - lib/animate_it/props_schema.rb
 - lib/animate_it/registry.rb
 - lib/animate_it/render_store.rb
+- lib/animate_it/runtime.rb
+- lib/animate_it/runtime/runtime.js
 - lib/animate_it/scene.rb
 - lib/animate_it/style.rb
+- lib/animate_it/text_effects.rb
 - lib/animate_it/timeline.rb
 - lib/animate_it/timing.rb
+- lib/animate_it/track_document_schema.rb
+- lib/animate_it/tracks/document.rb
+- lib/animate_it/tracks/layer.rb
+- lib/animate_it/tracks/recorder.rb
 - lib/animate_it/units.rb
+- lib/animate_it/verification.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
+homepage: https://github.com/joinbuildit/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
+  homepage_uri: https://github.com/joinbuildit/animate_it
+  source_code_uri: https://github.com/joinbuildit/animate_it
+  changelog_uri: https://github.com/joinbuildit/animate_it/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/joinbuildit/animate_it/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths: