animate_it 0.1.0 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 178ea946f7dfb1a83da1a68ba2ea514984d2ad1ab9792bbcd7d7fadff5380fc5
-  data.tar.gz: ca63aee15a52e08db308a17a2094989131bc1c6c6625f52cfb8dd375ef2b71ec
+  metadata.gz: 95bcfafc0a059c64d5f3a4097a308ba2b7b9fff58cafdb18de720926e02cb07e
+  data.tar.gz: 268da7e42d644633ee56bafb7528e7051280474647873d31bad585b07bd472cb
 SHA512:
-  metadata.gz: 7d4f409c4d620768e021529c8d3b7b2de5d5e8b2be1eaa05165c986c25f10e384434842f71b5c5f0062f482dc228d43efc40d65dc18feae776914a91d19985b5
-  data.tar.gz: cdc55f7e5159a4ec9854a61b447be969a4710d95b831ff9024611afe5b88650eb29b8de2ba097cc3cfb0c91ac459fdadf60bb213e5d46ffffc279aadb393d251
+  metadata.gz: d4cd9739b39aecc9d9cedf7d159718a768b7ba26ad3c4382e6f1bd96226ba70c4d59d708c57c263124eb07d39f0ff21bf3daab91733e774ffa15457dd8f3cf9e
+  data.tar.gz: c6f480ba02780a0c2cff836d061247961985138916607a318e6a4311456e8627684179dd52a81d16ab8fe30b413192f9126e9c3073306799299c8a8ff5ec06ec

data/CHANGELOG.md

@@ -6,6 +6,44 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Fixed
+- Studio audio is now served with HTTP byte-range support (Accept-Ranges,
+  206 Partial Content). Browsers refuse to seek media served without it, so
+  play-pause-play and scrub-then-play restarted clips from 0:00.
+
+## [0.3.1] - 2026-07-22
+
+### Changed
+- Relaxed the HAML dependency from `~> 6.3` to `>= 6.3` so hosts on HAML 7 are
+  not forced to downgrade.
+
+## [0.3.0] - 2026-07-22
+
+### Fixed
+- Studio playback started from a scrubbed position could seek the audio before
+  its metadata had loaded; the seek silently failed and the clip played from
+  0:00 instead of the playhead offset. The seek is now deferred until
+  `loadedmetadata`.
+- Studio playback now stops on Turbo navigation (`turbo:before-visit`,
+  `turbo:before-cache`) and `pagehide` — Turbo swaps the body without unloading
+  the window, so a detached, still-playing audio element kept sounding under
+  the next page.
+
+## [0.2.0] - 2026-07-09
+
+### Added
+- Scene sidecar templates can now be authored in ERB (`canvas.html.erb`) as well
+  as HAML — Rails resolves whichever exists, so HAML and ERB scenes can be mixed
+  in one app.
+- Test matrix across Rails 7.2 and 8.1 on Ruby 3.3 and 3.4, via Appraisal.
+
+### Changed
+- Lowered the minimum supported versions to Rails >= 7.2 and Ruby >= 3.3
+  (previously Rails >= 8.1.3, Ruby >= 3.4).
+- HAML is now a runtime dependency, so the Studio UI and HAML scenes render on
+  any host without the host having to add HAML itself (fixes an ERB-only host
+  crashing when mounting the Studio).
+
 ## [0.1.0] - 2026-07-08
 
 ### Added
@@ -20,5 +58,8 @@ adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 - `render_animate_it_video` executable and `animate_it:render` rake task.
 - `animate_it:install` generator.
 
-[Unreleased]: https://github.com/growth-constant/animate_it/compare/v0.1.0...HEAD
+[Unreleased]: https://github.com/joinbuildit/animate_it/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/joinbuildit/animate_it/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/growth-constant/animate_it/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/growth-constant/animate_it/compare/v0.1.0...v0.2.0
 [0.1.0]: https://github.com/growth-constant/animate_it/releases/tag/v0.1.0

data/README.md

@@ -1,10 +1,13 @@
 <p align="center">
-  <img src="assets/logo.svg" alt="AnimateIt" width="360">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="assets/logo-dark.svg">
+    <img src="assets/logo.svg" alt="AnimateIt" width="360">
+  </picture>
 </p>
 
 <p align="center">
-  <strong>Videos as code.</strong> Declarative, frame-driven video compositions for Rails,
-  rendered with headless Chromium (Playwright) + FFmpeg.
+  <strong>Remotion for Rails.</strong> Make videos from your app's own components and data,
+  written in Ruby — no React, no video editor, no After Effects.
 </p>
 
 <p align="center">
@@ -15,14 +18,23 @@
 
 ---
 
-AnimateIt lets you describe a video as a Ruby class and a HAML template, preview it
-frame-by-frame in a bundled **Studio** UI, and render it to MP4/WebM/MOV/GIF. Each
-frame is a real web page — so you get the full power of CSS, your app's own
-components, and real data — captured by a headless browser and stitched with FFmpeg.
+[Remotion](https://www.remotion.dev/) made it possible to build videos in React.
+**AnimateIt brings the same idea to Ruby on Rails** — without React, a JavaScript
+project, or a video editor.
+
+You describe a video as a Ruby class and a HAML template, preview it frame-by-frame
+in a bundled **Studio** UI, and render it to MP4/WebM/MOV/GIF. Every frame is a real
+web page, so you get the full power of CSS and — crucially — **your app's own
+components, styles, fonts, and real data**. A headless browser captures each frame
+and FFmpeg stitches them into a video.
+
+It's built for indie hackers and Rails developers who want to promote their projects
+with polished product demos, launch clips, and social ads — reusing the UI they've
+already built, staying in Ruby, and skipping the whole "learn a video editor" detour.
 
 ## Requirements
 
-- Ruby >= 3.4, Rails >= 8.1.3
+- Ruby >= 3.3, Rails >= 7.2 (tested against Rails 7.2 and 8.1)
 - **FFmpeg** on the PATH (rendering)
 - **Node + Playwright** with a Chromium build (rendering): `npx playwright install chromium`
 - **HAML** (composition sidecar templates + Studio views)
@@ -99,6 +111,23 @@ CSS-variable bag (`animation_vars`), named `beat`s, and `audio` / `audio_loop`
 tracks are all available. Compositions can render your app's real partials and
 ViewComponents — see `AnimateIt.config.render_stylesheets` below.
 
+### HAML or ERB
+
+Scene sidecar templates can be authored in **HAML** (`canvas.html.haml`) or
+**ERB** (`canvas.html.erb`) — Rails resolves whichever file exists, so you can
+mix engines across scenes. The HAML canvas above is equivalent to:
+
+```erb
+-# app/videos/hello_video/canvas.html.erb
+<style>.title { opacity: var(--title-opacity, 1); font-size: 6rem; font-weight: 800; }</style>
+<div class="stage" style="<%= @vars %>">
+  <div class="title">Hello 👋</div>
+</div>
+```
+
+The gem bundles HAML for its own Studio UI, so you never need to add HAML to your
+app to use it — ERB-only apps work out of the box.
+
 ## Rendering
 
 The renderer needs your Rails **server running** (it drives a real browser against
@@ -147,6 +176,19 @@ end
 Render concurrency for the Studio's background renderer is tunable via
 `ANIMATE_IT_RENDER_CONCURRENCY` and `ANIMATE_IT_RENDER_STARTS_PER_SECOND`.
 
+## Claude skill
+
+If you use [Claude Code](https://claude.com/claude-code), this repo ships an
+Agent Skill that teaches Claude how to author AnimateIt compositions — the DSL,
+the render pipeline, embedding, rendering your app's real partials, motion
+craft, and the gotchas. Install it into your project's `.claude/skills/`:
+
+```bash
+npx animate-it-skills          # copies the skill into ./.claude/skills
+```
+
+The skill source lives in [`skills/`](skills/).
+
 ## Development
 
 ```bash
@@ -156,11 +198,26 @@ bundle exec rubocop
 
 # full render smoke test (needs ffmpeg + Playwright chromium)
 RUN_RENDER_SMOKE=1 bundle exec rspec spec/rendering_spec.rb
+
+# run the suite against a specific Rails version (see Appraisals)
+bundle exec appraisal install
+bundle exec appraisal rails-7.2 rspec
+bundle exec appraisal rails-8.1 rspec
 ```
 
 Specs run against a minimal host app in `spec/dummy` — no external services, no
 database.
 
+## Credits
+
+AnimateIt is inspired by [**Remotion**](https://www.remotion.dev) — the framework
+that pioneered making videos programmatically in React. AnimateIt brings that
+"videos as code" idea to the Ruby on Rails ecosystem, natively and without React.
+Huge thanks to the Remotion team for the inspiration.
+
 ## License
 
-[MIT](MIT-LICENSE).
+AnimateIt is released under the [**MIT License**](MIT-LICENSE) — free and open source,
+with **no restrictions on commercial or business use**. Individuals, startups,
+agencies, and companies of any size can use it in open-source and closed-source
+projects at no cost, forever. No paid tiers, no seat limits.

data/app/controllers/animate_it/application_controller.rb

@@ -1,7 +1,8 @@
 module AnimateIt
   class ApplicationController < ActionController::Base
-    # Composition sidecar templates live at app/videos/<composition>/*.html.haml
+    # Composition sidecar templates live at app/videos/<composition>/*.html.*
     # in the host app — outside the engine's view path, so add it explicitly.
+    # Sidecars may be HAML or ERB; Rails' lookup resolves whichever exists.
     prepend_view_path Rails.root.join("app/videos")
 
     # Sidecar templates routinely render host-app partials (e.g. the real

data/app/controllers/animate_it/audio_controller.rb

@@ -10,12 +10,25 @@ module AnimateIt
       file_path = resolve_audio_path(segment.source[:path])
       return head :not_found unless file_path && File.file?(file_path)
 
-      send_file file_path, type: Mime::Type.lookup_by_extension(File.extname(file_path).delete(".")),
-                           disposition: "inline"
+      serve_with_byte_ranges(file_path)
     end
 
     private
 
+    # send_file ignores Range headers, and browsers refuse to seek media
+    # served without byte-range support — every currentTime seek snaps back
+    # to 0:00, so the Studio player restarts clips from the beginning.
+    # Rack::Files implements range semantics (Accept-Ranges, 206/416).
+    def serve_with_byte_ranges(file_path)
+      status, headers, body = Rack::Files.new(File.dirname(file_path)).serving(request, file_path)
+      headers["content-type"] = Mime::Type.lookup_by_extension(File.extname(file_path).delete(".")).to_s
+      headers["content-disposition"] = "inline"
+      headers["accept-ranges"] = "bytes"
+      self.status = status
+      self.response_body = body
+      headers.each { |key, value| response.headers[key] = value }
+    end
+
     def resolve_audio_path(path)
       return nil if path.blank?
 

data/app/views/animate_it/studio/_studio_script.html.haml

@@ -141,6 +141,21 @@
       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 startAudio = (el) => {
+      const begin = () => {
+        if (timer === null) return; // stopped before metadata arrived
+        const { start, len } = audioWindow(el);
+        if (frame < start || frame >= start + len) return; // playhead left the window
+        el.currentTime = (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.
@@ -153,10 +168,7 @@
           // 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) {
-            el.currentTime = (currentFrame - start) / fps;
-            el.play().catch(() => {});
-          }
+          if (el.paused) startAudio(el);
         } else if (!el.paused) {
           el.pause();
         }
@@ -264,6 +276,13 @@
       }
     });
 
+    // Turbo Drive swaps the body without unloading the window: detached
+    // <audio> elements keep playing and the playback loop keeps ticking.
+    // Stop this page's playback before navigating away or caching.
+    document.addEventListener("turbo:before-visit", stop, { once: true });
+    document.addEventListener("turbo:before-cache", stop, { once: true });
+    window.addEventListener("pagehide", stop, { once: true });
+
     window.AnimateItStudio = {
       setFrame,
       currentFrame: () => frame

data/lib/animate_it/scene.rb

@@ -15,8 +15,10 @@ module AnimateIt
     # ----- class-level DSL -----------------------------------------------
     class << self
       # Sidecar template name. Defaults to "canvas" — i.e. a scene whose
-      # composition is `MyHero` looks for `app/videos/my_hero/canvas.html.haml`.
-      # Override to point to a sibling template instead.
+      # composition is `MyHero` looks for `app/videos/my_hero/canvas.html.*`.
+      # The sidecar may be authored in HAML (`canvas.html.haml`) or ERB
+      # (`canvas.html.erb`); Rails resolves whichever exists. Override to point
+      # to a sibling template instead.
       def template(name = nil)
         @template = name.to_s if name
         @template ||= "canvas"

data/lib/animate_it/version.rb

@@ -1,3 +1,3 @@
 module AnimateIt
-  VERSION = "0.1.0".freeze
+  VERSION = "0.3.1".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: animate_it
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.1
 platform: ruby
 authors:
 - growth-constant
@@ -9,26 +9,45 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: haml
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '6.3'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.1.3
+        version: '7.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 8.1.3
+        version: '7.2'
 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.
+  AnimateIt brings Remotion-style programmatic video to Ruby on Rails — without
+  React or a JavaScript project. Build videos as code: a Ruby class plus a HAML
+  template, using your app's own components, styles, fonts, and real data. Every
+  frame is a real web page, so anything you can render in your app you can put in
+  a video. Preview frame-by-frame in the bundled Studio, then export to
+  MP4/WebM/MOV/GIF with headless Chromium (Playwright) + FFmpeg.
+
+  Built for indie hackers and Rails developers who want to promote their projects
+  with polished product demos, launch clips, and social ads — without leaving
+  Ruby, hiring an editor, or learning After Effects.
 executables:
 - render_animate_it_video
 extensions: []
@@ -106,7 +125,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.4'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -115,6 +134,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: Declarative, frame-driven video compositions for Rails, rendered with Playwright
-  + FFmpeg
+summary: Remotion for Rails — make videos with your app's own assets, in Ruby. No
+  React required.
 test_files: []