RubyGems - animate_it - Versions diffs - 0.1.0 - Mend

animate_it 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (58) hide show

checksums.yaml +7 -0
data/CHANGELOG.md +24 -0
data/MIT-LICENSE +21 -0
data/README.md +166 -0
data/app/controllers/animate_it/application_controller.rb +73 -0
data/app/controllers/animate_it/audio_controller.rb +31 -0
data/app/controllers/animate_it/frames_controller.rb +22 -0
data/app/controllers/animate_it/props_controller.rb +10 -0
data/app/controllers/animate_it/renders_controller.rb +82 -0
data/app/controllers/animate_it/studio_controller.rb +17 -0
data/app/jobs/animate_it/application_job.rb +6 -0
data/app/jobs/animate_it/render_job.rb +28 -0
data/app/views/animate_it/frames/filmstrip.html.haml +65 -0
data/app/views/animate_it/frames/fragment.html.haml +6 -0
data/app/views/animate_it/frames/show.html.haml +54 -0
data/app/views/animate_it/props/_form.html.haml +3 -0
data/app/views/animate_it/props/update.html.haml +8 -0
data/app/views/animate_it/renders/create.html.haml +9 -0
data/app/views/animate_it/renders/show.html.haml +10 -0
data/app/views/animate_it/studio/_composition_list.html.haml +7 -0
data/app/views/animate_it/studio/_preview_pane.html.haml +35 -0
data/app/views/animate_it/studio/_props_pane.html.haml +14 -0
data/app/views/animate_it/studio/_studio_script.html.haml +273 -0
data/app/views/animate_it/studio/_studio_styles.html.haml +284 -0
data/app/views/animate_it/studio/_timeline_lanes.html.haml +34 -0
data/app/views/animate_it/studio/index.html.haml +8 -0
data/app/views/animate_it/studio/show.html.haml +23 -0
data/app/views/layouts/animate_it/application.html.haml +17 -0
data/config/routes.rb +12 -0
data/exe/render_animate_it_video +53 -0
data/lib/animate_it/animation.rb +189 -0
data/lib/animate_it/animation_helpers.rb +86 -0
data/lib/animate_it/asset_renderer.rb +49 -0
data/lib/animate_it/beats.rb +61 -0
data/lib/animate_it/composition.rb +354 -0
data/lib/animate_it/configuration.rb +27 -0
data/lib/animate_it/easing.rb +40 -0
data/lib/animate_it/engine.rb +31 -0
data/lib/animate_it/errors.rb +4 -0
data/lib/animate_it/frame_context.rb +28 -0
data/lib/animate_it/frame_duration.rb +13 -0
data/lib/animate_it/output.rb +57 -0
data/lib/animate_it/props_schema.rb +49 -0
data/lib/animate_it/registry.rb +30 -0
data/lib/animate_it/render_store.rb +189 -0
data/lib/animate_it/scene.rb +237 -0
data/lib/animate_it/style.rb +23 -0
data/lib/animate_it/timeline.rb +81 -0
data/lib/animate_it/timing.rb +63 -0
data/lib/animate_it/units.rb +38 -0
data/lib/animate_it/version.rb +3 -0
data/lib/animate_it/video_renderer.rb +219 -0
data/lib/animate_it/view_helpers.rb +84 -0
data/lib/animate_it.rb +93 -0
data/lib/generators/animate_it/install/install_generator.rb +40 -0
data/lib/generators/animate_it/install/templates/animate_it.rb +8 -0
data/lib/tasks/animate_it_tasks.rake +83 -0
metadata +120 -0

data/lib/animate_it/composition.rb ADDED Viewed

@@ -0,0 +1,354 @@
+module AnimateIt
+  class Composition
+    SUPPORTED_OUTPUT_FORMATS = %i[webm mp4 mov gif png_sequence png].freeze
+    class << self
+      attr_reader :timeline, :props_schema, :width, :height, :duration_in_frames
+      def inherited(subclass)
+        subclass.instance_variable_set(:@timeline, Timeline.new)
+        subclass.instance_variable_set(:@props_schema, PropsSchema.new)
+        subclass.instance_variable_set(:@fps, 30)
+        subclass.instance_variable_set(:@width, 1920)
+        subclass.instance_variable_set(:@height, 1080)
+        subclass.instance_variable_set(:@zoom, 1.0)
+        subclass.instance_variable_set(:@duration_in_frames, 30)
+        subclass.instance_variable_set(:@output_format, :webm)
+        super
+      end
+      def output_format(value = nil)
+        return @output_format if value.nil?
+        unless SUPPORTED_OUTPUT_FORMATS.include?(value)
+          raise ArgumentError,
+                "Unsupported output_format #{value.inspect} — pick :webm, :mp4, :mov, :gif, :png_sequence, or :png"
+        end
+        @output_format = value
+      end
+      def transparent?
+        %i[webm mov gif png_sequence png].include?(output_format)
+      end
+      # Declarative outputs: list every (format, path) target this composition
+      # should produce. Without a block, returns the registered outputs (empty
+      # array if none have been declared).
+      #
+      #   outputs do
+      #     mp4 to: "app/assets/images/pages/product/screener-hero.mp4"
+      #     gif to: "app/assets/images/pages/product/screener-hero.gif"
+      #     png to: "app/assets/images/pages/product/screener-hero-first.png", frame: 0
+      #   end
+      #
+      # Paths are repo-relative; the renderer joins them onto Rails.root.
+      def outputs(&block)
+        @outputs ||= []
+        return @outputs unless block
+        builder = OutputsBuilder.new(assets_dir: assets_dir, basename: output_basename)
+        builder.instance_eval(&block)
+        @outputs = builder.outputs.freeze
+        # Keep `output_format` in sync with the first animated output so single-
+        # output legacy callers (bin/render_animate_it_video, AnimateIt Studio)
+        # see a sensible format without re-declaring it.
+        primary = @outputs.find { |o| o.frame.nil? }
+        @output_format = primary.format if primary
+        @outputs
+      end
+      def id(value = nil)
+        return @id if value.nil?
+        @id = value.to_s
+        AnimateIt.register(self)
+      end
+      def fps(value = nil)
+        return @fps if value.nil?
+        @fps = value.to_i
+      end
+      def size(width, height)
+        @width = width.to_i
+        @height = height.to_i
+      end
+      # Browser-side magnification applied via CSS `zoom` on `<body>` in the
+      # frame layout. Multiplies every visual length (font sizes, padding,
+      # widths) without changing the output viewport, so heros built against
+      # px-sized host partials can lift up the apparent scale without
+      # rewriting CSS. Default `1.0` (no zoom).
+      #
+      #   size 1080, 1170
+      #   zoom 1.1
+      #
+      # The viewport stays at `size(...)`; only the rendered content inside
+      # `<body>` is magnified. Combine `zoom` with a smaller `size` to "zoom
+      # in" the apparent scale of the composition at the same aspect ratio.
+      def zoom(value = nil)
+        return @zoom if value.nil?
+        @zoom = value.to_f
+      end
+      def duration(value = nil)
+        return @duration_in_frames if value.nil?
+        @duration_in_frames = Units.frames(value, fps:)
+      end
+      def props(&block)
+        props_schema.instance_eval(&block) if block
+        props_schema
+      end
+      # ----- Beats: named time markers on the composition timeline ------
+      def beat(name, at:, length:)
+        beats.add(name, at: at, length: length)
+      end
+      def beats
+        @beats ||= Beats.new(fps: fps)
+      end
+      # ----- Outputs path helpers --------------------------------------
+      # Declare a directory + basename so `outputs do ... end` entries can
+      # be specified by format alone:
+      #
+      #   assets_dir "app/assets/images/pages/product"
+      #   output_basename "screener-hero"
+      #
+      #   outputs do
+      #     mp4
+      #     webm
+      #     gif
+      #     png frame: 0       # → screener-hero-first.png
+      #   end
+      def assets_dir(value = nil)
+        @assets_dir = value.to_s if value
+        @assets_dir
+      end
+      def output_basename(value = nil)
+        @output_basename = value.to_s if value
+        @output_basename || @id
+      end
+      # ----- 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)
+      end
+      # Play a voice-over clip at a named beat (or time/frame). The clip's
+      # duration defaults to the beat's length.
+      def voice_over(path, at:, duration: nil, name: nil, gain: 1.0, track: :voice)
+        beat = at.is_a?(Symbol) ? beats.fetch(at) : nil
+        from = beat ? beat.start_frame : at
+        length = duration || (beat ? beat.duration_frames : 1.second)
+        audio(path, duration: length, from: from, name: name || File.basename(path.to_s), track: track, gain: gain)
+      end
+      def sequence(
+        from: 0,
+        start_at: nil,
+        duration: nil,
+        name: nil,
+        scene: nil,
+        layout: :none,
+        class_name: nil,
+        style: nil,
+        show_in_timeline: true,
+        track: :main,
+        &block
+      )
+        timeline.add_segment(
+          name: name || scene&.name || "sequence-#{timeline.segments.size + 1}",
+          from_frame: Units.frames(start_at || from, fps:),
+          duration_frames: Units.frames(duration, fps:),
+          scene_class: scene,
+          renderer: block,
+          layout:,
+          class_name:,
+          style:,
+          show_in_timeline:,
+          track:
+        )
+      end
+      def scene(scene_class, duration: nil, from: 0, start_at: nil, name: nil, **)
+        # Tell the scene class which composition it belongs to so its
+        # animation property procs can resolve symbolic beat names against
+        # the composition's beat registry.
+        scene_class.composition_class = self if scene_class.respond_to?(:composition_class=)
+        # If duration isn't given, default to the full composition duration
+        # (single-scene shorthand support).
+        duration ||= @duration_in_frames
+        sequence(from:, start_at:, duration:, name:, scene: scene_class, **)
+      end
+      # Sweep nested AnimateIt::Scene subclasses and auto-mount the single
+      # scene if no explicit `scene` / `series` was declared. Called by the
+      # registrar after composition file load.
+      def auto_mount_single_scene!
+        return if timeline.segments.any?
+        nested = constants.map { |c| const_get(c) }.select do |const|
+          const.is_a?(Class) && const < AnimateIt::Scene
+        end
+        return unless nested.size == 1
+        scene(nested.first)
+      end
+      # 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)
+        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 },
+          show_in_timeline: true
+        )
+      end
+      def series(&)
+        SeriesBuilder.new(self).instance_eval(&)
+      end
+      def transition_series(&)
+        TransitionSeriesBuilder.new(self).instance_eval(&)
+      end
+      def frame_context(frame:, props:, segment: nil)
+        FrameContext.new(
+          self,
+          props_schema.resolve(props),
+          frame.to_i,
+          segment ? segment.local_frame(frame.to_i) : frame.to_i,
+          fps,
+          duration_in_frames,
+          width,
+          height,
+          segment
+        )
+      end
+      def render_frame(view_context, frame:, props: {})
+        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)
+        end
+        view_context.safe_join(rendered_segments)
+      end
+      private
+      def render_segment(view_context, segment, context)
+        return "" if segment.kind == :transition
+        content = if segment.scene_class
+                    segment.scene_class.new(context:, props: context.props).render(view_context)
+                  else
+                    view_context.capture(context, context.props, &segment.renderer)
+                  end
+        return content unless segment.layout == :absolute_fill
+        view_context.tag.div(
+          content,
+          class: ["animate-it-absolute-fill", segment.class_name].compact,
+          style: Style.build(
+            "position: absolute",
+            "inset: 0",
+            "width: 100%",
+            "height: 100%",
+            "display: flex",
+            "flex-direction: column",
+            segment.style
+          )
+        )
+      end
+    end
+    class SeriesBuilder
+      def initialize(composition)
+        @composition = composition
+        @cursor = 0
+      end
+      def scene(scene_class, duration:, after: 0, start_at: nil, name: nil, **)
+        duration_frames = Units.frames(duration, fps: @composition.fps)
+        from_frame = if start_at
+                       Units.frames(start_at, fps: @composition.fps)
+                     else
+                       @cursor + Units.frames(after, fps: @composition.fps)
+                     end
+        @composition.scene(scene_class, from: from_frame, duration: duration_frames.frames, name:, **)
+        @cursor = from_frame + duration_frames
+      end
+      def audio(path, duration: nil, after: 0, start_at: nil, name: nil, track: :audio, gain: 1.0)
+        from_frame = if start_at
+                       Units.frames(start_at, fps: @composition.fps)
+                     else
+                       @cursor + Units.frames(after, fps: @composition.fps)
+                     end
+        @composition.audio(path, duration:, from: from_frame, name:, track:, gain:)
+      end
+      def transition(_name, duration:)
+        @cursor -= Units.frames(duration, fps: @composition.fps)
+      end
+    end
+    class TransitionSeriesBuilder
+      def initialize(composition)
+        @composition = composition
+        @cursor = 0
+      end
+      def scene(scene_class, duration:, name: nil, **)
+        duration_frames = Units.frames(duration, fps: @composition.fps)
+        @composition.scene(scene_class, from: @cursor, duration: duration_frames.frames, name:, **)
+        @cursor += duration_frames
+      end
+      def transition(name, duration:)
+        @cursor -= Units.frames(duration, fps: @composition.fps)
+        @composition.timeline.add_segment(
+          name: "#{name}-transition",
+          from_frame: @cursor,
+          duration_frames: Units.frames(duration, fps: @composition.fps),
+          kind: :transition,
+          transition: name,
+          show_in_timeline: true
+        )
+      end
+      def overlay(scene_class, duration:, offset: 0, name: nil, **)
+        from_frame = @cursor - (Units.frames(duration,
+                                             fps: @composition.fps) / 2) + Units.frames(offset, fps: @composition.fps)
+        @composition.scene(scene_class, from: from_frame, duration:, name:, **)
+      end
+    end
+  end
+end

data/lib/animate_it/configuration.rb ADDED Viewed

@@ -0,0 +1,27 @@
+module AnimateIt
+  # Host-app-overridable configuration. Set via the initializer that
+  # `bin/rails animate_it:install` generates, or in any initializer:
+  #
+  #   AnimateIt.configure do |config|
+  #     config.mount_path = "/studio"
+  #   end
+  class Configuration
+    attr_accessor :mount_path
+    # Host-app stylesheets to load into every rendered frame/filmstrip <head>.
+    # Compositions that re-use host partials (which expect the host's component
+    # CSS) list the bundles they need here, e.g.:
+    #
+    #   config.render_stylesheets = %w[application components/star-ratings]
+    #
+    # Names are passed straight to `stylesheet_link_tag`, so they resolve
+    # through the host's asset pipeline. Default empty — a composition built
+    # from self-contained markup needs none.
+    attr_accessor :render_stylesheets
+    def initialize
+      @mount_path = "/animate_it"
+      @render_stylesheets = []
+    end
+  end
+end

data/lib/animate_it/easing.rb ADDED Viewed

@@ -0,0 +1,40 @@
+module AnimateIt
+  module Easing
+    module_function
+    def resolve(easing)
+      return easing if easing.respond_to?(:call)
+      case easing
+      when nil, :linear
+        method(:linear)
+      when :ease_in
+        method(:ease_in)
+      when :ease_out
+        method(:ease_out)
+      when :ease_in_out
+        method(:ease_in_out)
+      else
+        raise ArgumentError, "Unknown easing: #{easing.inspect}"
+      end
+    end
+    def linear(progress)
+      progress
+    end
+    def ease_in(progress)
+      progress * progress
+    end
+    def ease_out(progress)
+      1 - ((1 - progress) * (1 - progress))
+    end
+    def ease_in_out(progress)
+      return 2 * progress * progress if progress < 0.5
+      1 - ((((-2 * progress) + 2)**2) / 2.0)
+    end
+  end
+end

data/lib/animate_it/engine.rb ADDED Viewed

@@ -0,0 +1,31 @@
+require "rails/engine"
+module AnimateIt
+  class Engine < ::Rails::Engine
+    isolate_namespace AnimateIt
+    # `app/videos/` is automatically autoloaded + reloaded by Rails: the
+    # host's `paths.add "app", glob: "*"` default registers every
+    # `app/<subdir>/` with Zeitwerk's `main` autoloader, which has reload
+    # enabled in development. We don't need to add the path manually.
+    #
+    # On boot AND on every dev-mode reload (after Zeitwerk has cleared
+    # old constants and removed orphaned descendants), reset the registry
+    # and eager-load `app/videos` so composition classes self-register
+    # via the `id "..."` DSL before any request hits `AnimateIt.compositions`,
+    # the Studio UI, or the renderer.
+    #
+    # Reload sequence in development:
+    #   1. file changes under app/videos/
+    #   2. Rails reloader → Zeitwerk reload → `remove_const` for every
+    #      autoloaded composition class
+    #   3. our `to_prepare` callback → `AnimateIt.reload_compositions!`
+    #      → registry.reset! + eager_load_dir → every class redefines
+    #      from scratch, `inherited` fires, fresh Timeline/@beats/@outputs.
+    initializer "animate_it.load_compositions" do
+      Rails.application.config.to_prepare do
+        AnimateIt.reload_compositions!
+      end
+    end
+  end
+end

data/lib/animate_it/errors.rb ADDED Viewed

@@ -0,0 +1,4 @@
+module AnimateIt
+  class Error < StandardError; end
+  class CompositionNotFoundError < Error; end
+end

data/lib/animate_it/frame_context.rb ADDED Viewed

@@ -0,0 +1,28 @@
+module AnimateIt
+  FrameContext = Data.define(
+    :composition,
+    :props,
+    :frame,
+    :local_frame,
+    :fps,
+    :duration_in_frames,
+    :width,
+    :height,
+    :segment
+  ) do
+    def progress(duration_frames: nil)
+      total = duration_frames || segment&.duration_frames || duration_in_frames
+      return 0.0 if total.to_i <= 1
+      local_frame.to_f / (total - 1)
+    end
+    def interpolate(input, input_range, output_range, **)
+      Timing.interpolate(input, input_range, output_range, **)
+    end
+    def spring(**)
+      Timing.spring(frame: local_frame, fps:, **)
+    end
+  end
+end

data/lib/animate_it/frame_duration.rb ADDED Viewed

@@ -0,0 +1,13 @@
+module AnimateIt
+  FrameDuration = Data.define(:value) do
+    delegate :to_i, to: :value
+  end
+end
+unless Numeric.method_defined?(:frames)
+  class Numeric
+    def frames
+      AnimateIt::FrameDuration.new(to_i)
+    end
+  end
+end

data/lib/animate_it/output.rb ADDED Viewed

@@ -0,0 +1,57 @@
+module AnimateIt
+  # Declarative output target: one rendered file at one path.
+  # `format` selects the encoder; `path` is repo-relative (joined onto
+  # Rails.root by the renderer); `frame` is set for single-frame stills,
+  # nil for animated outputs (the whole composition).
+  Output = Struct.new(:format, :path, :frame, keyword_init: true) do
+    def still?
+      !frame.nil?
+    end
+    def absolute_path
+      Rails.root.join(path.to_s)
+    end
+  end
+  # Block DSL used inside `Composition.outputs do ... end`.
+  #
+  # Each method declares one Output. Two ways to call each format:
+  #
+  #   # explicit path
+  #   mp4 to: "app/assets/images/pages/product/screener-hero.mp4"
+  #
+  #   # convention-based path (composition declared `assets_dir` + `output_basename`)
+  #   mp4
+  #   webm
+  #   gif
+  #   png frame: 0       # → <basename>-first.png
+  class OutputsBuilder
+    attr_reader :outputs
+    def initialize(assets_dir: nil, basename: nil)
+      @outputs = []
+      @assets_dir = assets_dir
+      @basename = basename
+    end
+    Composition::SUPPORTED_OUTPUT_FORMATS.each do |fmt|
+      define_method(fmt) do |to: nil, frame: nil|
+        path = to || conventional_path(fmt, frame)
+        @outputs << Output.new(format: fmt, path: path, frame: frame)
+      end
+    end
+    private
+    def conventional_path(fmt, frame)
+      if @assets_dir.blank? || @basename.blank?
+        raise ArgumentError,
+              "Pass `to:` or declare `assets_dir`/`output_basename` on the composition"
+      end
+      ext = AnimateIt::VideoRenderer::EXTENSION_FOR_FORMAT[fmt] || fmt.to_s
+      suffix = frame&.zero? ? "-first" : nil # frame is nil for animated outputs
+      File.join(@assets_dir, "#{@basename}#{suffix}.#{ext}")
+    end
+  end
+end

data/lib/animate_it/props_schema.rb ADDED Viewed

@@ -0,0 +1,49 @@
+module AnimateIt
+  class PropsSchema
+    Field = Data.define(:name, :type, :default, :options)
+    attr_reader :fields
+    def initialize
+      @fields = []
+    end
+    def string(name, default: nil, **)
+      field(name, :string, default:, **)
+    end
+    def color(name, default: nil, **)
+      field(name, :color, default:, **)
+    end
+    def asset(name, default: nil, **)
+      field(name, :asset, default:, **)
+    end
+    def integer(name, default: nil, **)
+      field(name, :integer, default:, **)
+    end
+    def number(name, default: nil, **)
+      field(name, :number, default:, **)
+    end
+    def boolean(name, default: nil, **)
+      field(name, :boolean, default:, **)
+    end
+    def defaults
+      fields.to_h { |field| [field.name, field.default] }
+    end
+    def resolve(input)
+      defaults.merge(input.transform_keys(&:to_sym))
+    end
+    private
+    def field(name, type, default:, **options)
+      fields << Field.new(name.to_sym, type, default, options)
+    end
+  end
+end

data/lib/animate_it/registry.rb ADDED Viewed

@@ -0,0 +1,30 @@
+module AnimateIt
+  class Registry
+    def initialize
+      @compositions = {}
+    end
+    def register(composition_class)
+      id = composition_class.id
+      raise ArgumentError, "Composition #{composition_class.name} must declare an id" if id.blank?
+      @compositions[id] = composition_class
+    end
+    def fetch(id)
+      @compositions.fetch(id) do
+        raise CompositionNotFoundError, "No AnimateIt composition registered for #{id.inspect}"
+      end
+    end
+    def all
+      @compositions.values.sort_by(&:id)
+    end
+    # Drop every registration. Used by `AnimateIt.reload_compositions!` on
+    # dev-mode reload so renamed/removed composition ids don't linger.
+    def reset!
+      @compositions.clear
+    end
+  end
+end