hls 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc3a9e8f4508dbdc33d12b7ce2665d5e455421992520bf6ee36834bf936e2c8c
-  data.tar.gz: 86aa27e58a352a2eb6cab7d368ecc546db4b6b8a2e70b14e827d4185bc42e6df
+  metadata.gz: e08ad4995abd5e93b9dd89b2971c3d6cb698c774cd495d683356c4ec8cc1f2c2
+  data.tar.gz: f1fa71e889f4002caa0b51c5fb11048f1b7fcf82fbe68935eef1c6bb9ac436cc
 SHA512:
-  metadata.gz: 44c7aa81f15a22e0edf70821a506c3b87102bd05140814ff9ecf0f15153264cc7d5ea68c2cfb4610426084df37fea91398125f1f0b95a31b126328211b69f464
-  data.tar.gz: 172a06401b9c59d6e5b3781895893406f2ebdae6d78e55ece3643de3a9648438c0699e7caf382420de1fed78cf8335d37cf8f579d6ecb6112a023b6527fccc56
+  metadata.gz: 3ef35475f72800b5d9d01841a48b83e84c525d517ad94e9a3127dccf4dd05c82676854accc6a0cc4e19d7fc5bb1622daac1f93cf207126a735974cd674b07c37
+  data.tar.gz: 06c7ddb78a322e5728f5e6f03faa53e3e67833c1c5fe857f6ce3fa66d2900efcea91f578ca44aff7570e83b947f3262a0e8e9080f3c675fdb9085dd316d9fef7

data/CHANGELOG.md

@@ -0,0 +1,145 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-05-06
+
+### Changed (breaking)
+
+- **`config_digest` now sorts hash keys before SHA256ing the payload.**
+  The serialized form is stable across Ruby versions and hash insertion
+  order. *One-time effect on existing deployments:* the next `process`
+  run will re-encode every video once, since previously-recorded
+  digests no longer match the new representation. Subsequent runs are
+  no-ops as before.
+
+- **`HLS::Cache` groups the playlist cache backend with its TTL.** The
+  separate `manifest_cache` + `manifest_cache_ttl` class settings (and
+  the `cache_ttl:` kwarg on `HLS::Manifest.new`) are gone. Configure
+  one object on the profile:
+
+      class ApplicationVideo < HLS::ApplicationVideo
+        def self.cache = HLS::Cache.new(backend: Rails.cache, ttl: 5.minutes)
+      end
+
+  `HLS::Manifest` accepts an `HLS::Cache` or any object responding to
+  `fetch(key, &block)` (raw `Rails.cache` still works — it just uses
+  the cache's own default TTL).
+
+- **`HLS::Storage::S3` is now the default storage adapter** and owns
+  `bucket_name` + `signing_ttl`. The polymorphic `bucket` setting on
+  `HLS::ApplicationVideo` (and the matching `signing_ttl` setting and
+  `resolve_bucket` method) are removed. Configure profiles like:
+
+      class ApplicationVideo < HLS::ApplicationVideo
+        def self.storage = HLS::Storage::S3.new(
+          bucket_name: ENV.fetch("VIDEO_S3_BUCKET_NAME"),
+          signing_ttl: 1.hour
+        )
+      end
+
+  `HLS::Manifest` and `HLS::Uploader` now take `storage:` instead of
+  `bucket:` (and `Manifest` no longer takes `expires_in:` — it reads
+  it from `storage.signing_ttl`).
+
+- **The Railtie no longer fires the `:hls_application_video` load
+  hook**, no longer registers a `Rails.application.config.hls` config
+  bag, and no longer copies values onto profile classes via a
+  separate initializer. Settings live on the profile classes directly
+  (Zeitwerk reloads handle dev-mode freshness). Initializers shrink to
+  one line: `HLS.s3_resource = Aws::S3::Resource.new(...)`.
+
+### Added
+
+- **`HLS::EncodeJob` retry policy.** `discard_on` for `HLS::Lock::Busy`
+  (another worker is doing it) and `HLS::State::CorruptError` (operator
+  intervention required) — both are poison messages that ActiveJob's
+  default retry-everything-five-times behavior wastes work on. Other
+  errors continue to follow the host app's default retry policy.
+
+### Removed
+
+- **Dropped `parallel` and `bigdecimal` gem dependencies.** Neither was
+  used in `lib/`. The Uploader does its own bounded threading via
+  `Queue` + `Thread.new`, and nothing in the gem touches BigDecimal.
+
+### Added
+
+- **Config-aware encode idempotency.** The state sidecar now records
+  a `config_digest` alongside `input_digest` — a SHA256 of the
+  encode-affecting profile config (renditions, posters, codecs,
+  bitrates, segment_duration, bits_per_pixel). `process` re-runs
+  ffmpeg when *either* the input bytes or the profile config has
+  changed since the last successful encode. Previously, bumping
+  `audio_bitrate` or adding a rendition was a silent no-op on
+  re-run. Settings that don't affect output bytes (`storage`,
+  `cache`, `ffmpeg_timeout`, `variant_uri`) are excluded.
+- **Rails generators.** `bin/rails g hls:install` scaffolds
+  `config/initializers/hls.rb` and `app/videos/application_video.rb`.
+  `bin/rails g hls:video NAME` writes a per-content-type profile under
+  `app/videos/` with a sensible default ladder, an active hero poster,
+  and commented hints for the common per-profile overrides.
+
+- **ffmpeg stderr capture.** When ffmpeg fails, the tail of its stderr
+  is included in `HLS::Error` so failures are diagnosable without
+  re-running with verbose logging.
+- **Input validation.** `HLS::Input#validate!` raises early when the
+  input has no video stream (audio-only files, malformed media), and
+  `#video?` exposes the same predicate. The encode pipeline calls
+  `validate!` before invoking ffmpeg.
+- **Lock file in output dir.** `HLS::Lock` provides advisory file
+  locking via `flock`. `process` acquires it before encoding/uploading;
+  a second concurrent worker for the same output dir gets
+  `HLS::Lock::Busy` instead of corrupting state.
+- **Encode bundle verification.** `verify_encode!` walks the just-
+  encoded output, asserting the master + variants + segments + posters
+  all exist and are non-empty, before recording state and uploading.
+- **ActiveSupport::Notifications hooks.** Events `encode.hls`,
+  `poster.hls`, `verify.hls`, `upload_object.hls`, `upload_retry.hls`,
+  and `process.hls` published when AS is loaded; pure-Ruby usage is a
+  no-op. See README for payload keys.
+- **Configurable ffmpeg timeout.** `ffmpeg_timeout` class setting (in
+  seconds) terminates a stuck ffmpeg with SIGTERM then SIGKILL. `nil`
+  default preserves prior behavior.
+- **S3 retry with backoff.** Uploader retries transient failures
+  (network errors, 503, RequestTimeout, SlowDown, InternalError) up to
+  `max_retries` times with exponential backoff. Permanent errors
+  (NoSuchBucket, 403) fail fast.
+- **Threaded uploader.** Bounded-concurrency parallel uploads via a
+  worker pool. Default `concurrency: 4`. Set to `1` for serial.
+- **GOP scales with segment_duration.** Keyframe interval is now
+  `framerate × segment_duration` instead of a hardcoded 180. Each HLS
+  segment starts on a keyframe regardless of the configured segment
+  length, fixing seek stalls on non-default `segment_duration`.
+- **Storage adapter pattern.** `bucket` accepts any object responding
+  to `object(key)` that yields a duck-typed object with `get`, `put`,
+  and `presigned_url`. `HLS::Storage::Memory` ships as a no-network
+  adapter for tests. Documented MinIO setup in README.
+- **Pluggable Manifest cache.** Read-side Manifest accepts a `cache:`
+  object (an `HLS::Cache` wrapping a `Rails.cache`-shaped backend, or
+  any object responding to `fetch(key, &block)`) to cut S3 GETs for
+  hot videos.
+- **`resolve_variants_under` RSpec matcher.** Public test helper that
+  catches the variant-URI-doubling bug class by simulating RFC 3986
+  resolution against the master URL.
+
+### Changed
+
+- Variant URIs in the master playlist are now generated by an
+  overridable `variant_uri(path:, variant_index:)` class method.
+  Default returns `<basename(path)>/<variant_index>.m3u8`, which
+  resolves cleanly under a `/videos/*path/:id.m3u8` route shape.
+- Cache-Control on uploaded `.m3u8` files relaxed from `no-cache` to
+  `public, max-age=300` so a CDN can edge-cache playlists between
+  re-encodes.
+- ffprobe / ffmpeg subprocess calls switched from backticks / `system`
+  to `Open3.capture3` for safer argument handling and stderr capture.
+
+## [0.1.0]
+
+- Initial release.

data/CLAUDE.md

@@ -0,0 +1,448 @@
+# CLAUDE.md
+
+Guide for AI assistants and human maintainers working on this gem.
+The README is for *users* of the gem; this file is for people
+*changing* it.
+
+## What this gem actually is
+
+A Rails-friendly Ruby library for taking a video file, encoding it as
+an HLS bundle (multi-rendition multiplex + posters), and serving it
+from a private S3-compatible bucket via pre-signed URLs.
+
+The user-facing surface is small:
+- `HLS::ApplicationVideo` — DSL base class for `app/videos/*.rb`
+  profile classes
+- `HLS::Manifest` — read-side, returns signed playlists
+- `HLS::Input` — ffprobe wrapper
+- `HLS::Testing` — RSpec helpers for verifying user-defined profiles
+
+Everything else (`Uploader`, `State`, `Codecs`, `Railtie`,
+`EncodeJob`) is plumbing that profile classes orchestrate.
+
+## Architecture & layering
+
+```
+L4  Framework integration   railtie.rb, encode_job.rb
+L3  Orchestration           application_video.rb
+L2  Storage                 manifest.rb (read), uploader.rb (write)
+L1  Utilities               codecs, input, directory, state, testing,
+                            version
+```
+
+Lower layers don't reach up. `Manifest` doesn't know `ApplicationVideo`
+exists; `Uploader` doesn't know about `Manifest`. `ApplicationVideo`
+is the only file that composes the layers, and it's the only file
+users normally subclass.
+
+The Railtie is *optional* — the gem works in plain Ruby. The Railtie
+file is only required when `defined?(Rails::Railtie)` is true at
+load time (see `lib/hls.rb` bottom).
+
+## File map
+
+```
+lib/hls.rb                      Top-level module, error class, S3 resource accessor, requires
+lib/hls/version.rb              Version constant
+lib/hls/application_video.rb    DSL + encode/poster/upload orchestration
+lib/hls/manifest.rb             Reads bundle from S3, returns signed M3u8 playlists
+lib/hls/uploader.rb             Walks output dir, parallel idempotent S3 upload with retries
+lib/hls/state.rb                JSON sidecar: input digest, encoded_at, per-key etags
+lib/hls/lock.rb                 Advisory flock around the output dir during process
+lib/hls/instrumentation.rb      ActiveSupport::Notifications wrapper (no-op without AS)
+lib/hls/storage.rb              Storage protocol doc + Memory adapter for tests
+lib/hls/codecs.rb               Logical → explicit codec resolution per host
+lib/hls/input.rb                ffprobe wrapper (Open3, raises on failure)
+lib/hls/directory.rb            Source-walking helper for batch encoding scripts
+lib/hls/testing.rb              Public RSpec helpers + matcher (only when RSpec defined)
+lib/hls/railtie.rb              Autoloads app/videos/, applies config.hls defaults
+lib/hls/encode_job.rb           ActiveJob wrapper around profile.process
+
+lib/generators/hls/install/     `bin/rails g hls:install` — initializer + ApplicationVideo
+lib/generators/hls/video/       `bin/rails g hls:video NAME` — per-content-type profile
+```
+
+Each lib file has a matching spec under `spec/hls/`. Cross-cutting
+specs (`process_spec.rb`, `poster_dsl_spec.rb`) live alongside.
+End-to-end specs that shell out to ffmpeg live under `spec/integration/`.
+
+## The pipeline
+
+`profile.process` acquires a file lock on the output dir, then runs:
+
+1. **Probe** — `HLS::Input` shells out to `ffprobe` for width / height
+   / codec / duration / framerate. Lazy and memoized per Input
+   instance. `validate!` is called before encode to fail fast on
+   audio-only inputs.
+2. **Encode** — `ApplicationVideo#encode!` builds an `ffmpeg` command
+   from the rendition declarations + codec resolution. One ffmpeg
+   invocation produces all renditions of the multiplex via
+   `-filter_complex split` + `-var_stream_map`. Subject to
+   `ffmpeg_timeout` and stderr is captured into `HLS::Error` on failure.
+3. **Poster** — separate ffmpeg invocation if any `poster ...`
+   declarations exist. Multiple outputs from one decode pass.
+4. **Verify** — `verify_encode!` walks the output and asserts all
+   expected files exist and are non-empty. Bails BEFORE recording state
+   so a failed verify doesn't claim the bundle is encoded.
+5. **Upload** — `HLS::Uploader` walks the output dir, computes MD5 of
+   each file, skips files whose recorded digest in `state.json`
+   matches. PUTs each file with appropriate Content-Type and
+   Cache-Control. Default `concurrency: 4` parallel workers, with
+   bounded retries on transient errors. Records etag back into state.
+
+Idempotency is enforced at two levels:
+- **Encode level**: skipped when the input's SHA256 digest matches
+  what's recorded in state.json AND the master playlist file actually
+  exists. Both checks are necessary — see "Common gotchas" below.
+- **Upload level**: per-file MD5 compared to recorded digest.
+
+## Class-level DSL pattern
+
+`HLS::ApplicationVideo` uses a small custom inheritable-attribute
+helper (`class_setting`) instead of pulling in ActiveSupport's
+`class_attribute`. This keeps the gem usable without Rails.
+
+The pattern: each setting is a singleton method that reads with no
+args, writes with one. Reads walk the class hierarchy via `superclass`
+until they find a set value or hit the default.
+
+`renditions` and `posters` accumulate into per-class arrays. The
+`inherited` callback dups parent declarations into subclasses, so
+subclass mutations don't leak back to the parent.
+
+Avoid the temptation to swap this for `class_attribute` unless we
+later decide to take a hard dep on activesupport. Right now the gem's
+only Rails-flavored deps are dev-only (railties, activejob).
+
+## Storage layout
+
+ffmpeg writes the bundle into `output/`:
+
+```
+<output>/
+├── index.m3u8         master playlist
+├── 0/                 first variant (highest rendition)
+│   ├── index.m3u8
+│   └── 0.ts, 1.ts, ...
+├── 1/                 second variant
+│   ├── index.m3u8
+│   └── 0.ts, 1.ts, ...
+├── 2/...
+├── hero.jpg           if `poster :hero` declared
+├── thumbnail.jpg      if `poster :thumbnail` declared
+└── .hls-state.json    written by us, not uploaded
+```
+
+Variant names default to integer indices (`0/`, `1/`, `2/`) because
+that's ffmpeg's default `%v` template substitution. Named variants via
+`-var_stream_map name:high,...` is a known follow-up not yet built.
+
+Bucket layout mirrors local layout under a `key_prefix`:
+
+```
+<bucket>/<key_prefix>/index.m3u8
+<bucket>/<key_prefix>/0/index.m3u8
+<bucket>/<key_prefix>/0/0.ts
+...
+```
+
+## Read side: how URI rewriting works
+
+The encoded master playlist points at variants by their relative path:
+
+```
+0/index.m3u8
+1/index.m3u8
+```
+
+But the host app's controller wants to serve variants by their
+*number* under a stable URL like `/videos/<id>/<variant>.m3u8`. So
+`Manifest#master_playlist` rewrites:
+
+```
+0/index.m3u8  →  <path>/0.m3u8
+1/index.m3u8  →  <path>/1.m3u8
+```
+
+The variant playlist (returned by `Variant#playlist`) goes a step
+further: each segment URI gets rewritten to a pre-signed S3 URL the
+player can fetch directly without proxying through the app server.
+
+**Critical**: `master_playlist` must NOT mutate the cached raw
+playlist. We had a regression where it did, which broke `variants`
+when both were called in the same request (`File.dirname` of an
+already-rewritten URI returns nonsense). There's a test pinning this.
+
+## Codec resolution
+
+`video_codec :h264` is a *logical* codec. At command-build time, the
+gem picks the best available encoder by:
+
+1. Checking `RbConfig::CONFIG["host_os"]` for darwin / linux / etc.
+2. Querying `ffmpeg -encoders` once per process and caching the result
+3. Walking the per-platform priority list (videotoolbox first on
+   macOS; nvenc → qsv → libx264 on Linux)
+
+To pin a specific encoder regardless of host, pass a string:
+`video_codec "libx264"`. Tests stub `HLS::Codecs.platform` and
+`available_encoders` to make platform-dependent paths deterministic.
+
+## Common gotchas
+
+### Variant URIs are RELATIVE to the master playlist URL
+
+The master playlist served by the controller lives at e.g.
+`/videos/<path>/<id>.m3u8`. Variant URIs inside it are RFC 3986
+relative references — the player resolves each one against the
+master's URL. A variant URI of `<id>/0.m3u8` resolves to
+`/videos/<path>/<id>/0.m3u8` (good). A variant URI of
+`<path>/<id>/0.m3u8` resolves to
+`/videos/<path>/<path>/<id>/0.m3u8` — **the path doubles** —
+because resolution drops the master URL's filename and joins
+relative to the parent directory. We hit this once: it produced
+`Aws::S3::Errors::NoSuchKey` when the player tried to fetch the
+doubled URL.
+
+`HLS::Manifest#master_playlist` produces the URI via the configured
+`variant_uri` callable, defaulting to
+`<basename(path)>/<index>.m3u8`. This default works for
+`/videos/*path/:id/:variant.m3u8` Rails routes. For any other URL
+shape, override `self.variant_uri(path:, variant_index:)` on the
+profile class.
+
+There's a regression test in `spec/hls/manifest_spec.rb` that
+simulates the player's URL resolution with `URI#+`. Keep it. The
+`HLS::Testing` matcher `resolve_variants_under(url)` is the
+generalization users can run on their own profile specs.
+
+### `path:` gem deps don't hot-reload
+
+When the host app pins `gem "hls", path: "../hls"` for development,
+gem source changes don't reload across the Rails process. After
+changing gem code, fully restart the Rails server (Ctrl+C, `bin/dev`
+again). Zeitwerk's reloader watches `app/`, not gems.
+
+### `hls.js` caches master playlists in-memory
+
+Even after a server-side fix lands, the player keeps the previously-
+fetched master playlist in memory across plays in the same tab. If
+debugging URL rewriting, hard-reload the browser tab (Cmd+Shift+R)
+or open a private window to bypass it. The `Cache-Control: public,
+max-age=300` we set on uploaded m3u8s is also strong enough to keep
+old playlists around briefly.
+
+### "Encoded but files missing"
+
+If state.json exists but the output directory's been wiped (ephemeral
+worker, manual cleanup, etc.), the naive `state.encoded?` check passes
+but the upload step would try to walk an empty directory. The fix
+(in `ApplicationVideo#encoded?`, private) checks BOTH state AND that
+the master playlist is on disk. Keep this dual check — there's a test
+for it.
+
+### Empty-string buckets
+
+`ENV.fetch("VIDEO_S3_BUCKET_NAME", "")` returns `""` when the env var
+is missing. Empty string is truthy in Ruby. `resolve_bucket` treats
+both `nil` and `""` as "no bucket configured" and raises. Don't
+add another path that bypasses this check.
+
+### No Rails config bag, no load hook
+
+The Railtie does only two things: register `app/videos` as an
+autoload path and lazy-require `HLS::EncodeJob` when ActiveJob
+loads. There is intentionally no `Rails.application.config.hls.*`
+bag and no `:hls_application_video` load hook to subscribe to.
+
+Why? Because Zeitwerk already reloads `app/videos/*.rb` in dev, the
+class body of `ApplicationVideo` re-runs on every reload — so any
+configuration written there (env-var-derived or otherwise) refreshes
+automatically. A load hook would be redundant.
+
+Profile classes own their own configuration via the class-level DSL
+plus `def self.storage = ...` overrides. The only module-level state
+the gem keeps is `HLS.s3_resource` for the AWS SDK client.
+
+### Storage is one object that owns bucket + signing TTL
+
+Earlier versions had two separate class settings (`bucket` accepting
+String/Bucket/duck-typed thing, plus `signing_ttl`) and a
+`resolve_bucket` switch that picked an adapter based on the value
+type. That all collapsed into one `storage` setting that takes any
+object satisfying the protocol (`signing_ttl` + `object(key)`):
+
+  - `HLS::Storage::S3` is the default. It owns `bucket_name`,
+    `signing_ttl`, and an optional `s3_resource` override.
+  - `HLS::Storage::Memory` is the test/dev adapter.
+  - Any duck-typed object (future ActiveStorage adapter, custom
+    backend) plugs in the same way.
+
+`HLS::Manifest` and `HLS::Uploader` only ever talk through `storage`
+— they don't know what kind of bucket or backend is behind it.
+
+### State sidecar corruption
+
+A malformed state.json would silently re-encode + re-upload everything
+without telling the operator. We deliberately raise `HLS::State::CorruptError`
+instead of recovering. If you hit this, delete the state file
+intentionally rather than working around it in the gem.
+
+### ffmpeg multithreading on macOS
+
+On macOS with `h264_videotoolbox`, multiple concurrent ffmpeg
+processes contend on the Media Engine and macOS's videotoolbox
+session limits. `HLS_PARALLEL=1` is the safe default. Bumping it
+helps on Linux with libx264 only if you have many small videos to
+batch.
+
+### Cache-control on m3u8
+
+VOD playlists are immutable once written. We use `public, max-age=300`
+(not `no-cache`) so CDNs can edge-cache them. A redeploy of a bundle
+takes effect within 5 min. Don't tighten this without thinking about
+CDN cost.
+
+### GOP must equal framerate × segment_duration
+
+ffmpeg's `-g` (GOP size) sets how many frames between keyframes. HLS
+players seek to segment boundaries and need each segment to start with
+a keyframe. Computed in `ApplicationVideo#gop_size` from
+`input.framerate * segment_duration`. Hardcoding it (the previous bug)
+caused stalls when segment_duration was set to anything other than the
+"normal" value. Don't reintroduce a constant here.
+
+### Lock file collides with stale interrupted runs only via Busy
+
+`process` writes `.hls-lock` and `flock(LOCK_EX | LOCK_NB)`s it. A
+second process gets `HLS::Lock::Busy` *immediately* — we don't wait.
+The lock file itself stays on disk after release; only the kernel-level
+advisory lock is dropped. The state.json + .hls-lock + .DS_Store + ._*
+patterns are all skipped by the uploader.
+
+### Storage protocol is duck-typed
+
+`bucket` accepts anything responding to `object(key)` whose return
+value implements `get` / `put(body:, content_type:, cache_control:)` /
+`presigned_url(:get, expires_in:)`. The `Aws::S3::Bucket` already
+matches; `HLS::Storage::Memory` is a test double; anything else is the
+host app's responsibility. `resolve_bucket` returns duck-typed buckets
+unchanged — it only special-cases String (via `HLS.s3_resource`) and
+Aws::S3::Bucket (passthrough).
+
+## Running tests
+
+```sh
+bundle exec rspec                           # everything (~35s, ffmpeg integration)
+bundle exec rspec --exclude-pattern "spec/integration/**"   # unit only (~1s)
+bundle exec rspec spec/hls/manifest_spec.rb # one file
+```
+
+The integration specs (`spec/integration/`) actually shell out to
+ffmpeg. They generate a 12-second test source via
+`HLS::Testing.generate_test_video` and verify output dimensions,
+playlist structure, and segment counts. Slow but they're the test
+that catches command-building bugs the stubbed unit tests miss.
+
+The Rails-flavored specs (`spec/hls/railtie_spec.rb` and
+`spec/integration/rails_pipeline_spec.rb`) share a single Rails app
+boot via `spec/support/dummy_rails_app.rb`. Rails freezes
+`autoload_paths` after `initialize!`, so booting twice in one process
+crashes — always go through `DummyRailsApp.boot!`.
+
+## Adding things
+
+### A new codec
+
+Edit `lib/hls/codecs.rb`:
+- Add to `H264` if it's an h264 variant
+- Add to `H264_PRIORITY[platform]` for auto-resolution
+- Add a `case` arm in `ApplicationVideo#video_codec_options` for
+  encoder-specific ffmpeg flags (preset, profile, tune, etc.)
+- Add a spec covering both the resolution and the command-shape
+
+### A new class-level setting
+
+Add `class_setting :name, default: ...` near the bottom of the class
+body in `application_video.rb`. If host apps should be able to
+override it via `config.hls.name = ...`, add a corresponding line in
+the Railtie's `apply_config` initializer.
+
+### A new ffmpeg arg in the encode command
+
+Edit `ApplicationVideo#command` (or one of `video_maps` / `audio_maps`).
+**Add a unit test** asserting the new arg appears in the right place,
+and check whether the integration spec's golden assertions need
+updating.
+
+### A new test helper
+
+Add to `lib/hls/testing.rb`. Helpers can shell out (ffmpeg/ffprobe are
+hard deps anyway) but should not require Rails. Custom matchers go
+inside the `if defined?(RSpec::Matchers)` block at the bottom of that
+file.
+
+### A new Rails generator
+
+Live under `lib/generators/hls/<name>/`:
+- `<name>_generator.rb` — subclass `Rails::Generators::{Base,NamedBase}`
+- `templates/*.rb` (or `.tt`) — Thor templates; `<%= %>` interpolates
+  generator method results
+
+Spec it under `spec/generators/`. Use the Rails helpers
+(`Rails::Generators::Testing::{Behavior,Assertions}`) plus
+`spec/support/minitest_shims.rb` so `assert_file` and friends work
+inside RSpec. Always include a behavior test that `load`s the
+generated file and asserts the resulting class actually works — text
+matches don't catch wrong inheritance, missing renditions, etc.
+
+## How this gem is used in `../server`
+
+The sister project `../server` (beautifulruby.com) is the canonical
+production consumer. Its `app/controllers/videos_controller.rb` is
+~50 lines that delegates to `CourseVideo.manifest(path)`. Its
+`config/initializers/hls.rb` configures the Tigris bucket. The legacy
+`app/models/video.rb` was deleted during the integration in favor of
+`HLS::Manifest`.
+
+When making changes here that could affect the read side (Manifest,
+URI rewriting, signed URLs), run the server suite too:
+
+```sh
+cd ../server && bundle exec rspec spec/requests/videos_spec.rb
+```
+
+## Plans directory
+
+Long-form design docs live in `plans/`. The flow:
+
+- `plans/00-goal.md` — the north star and master checklist
+- `plans/0[1-5]-*.md` — implemented steps (all checked off)
+- `plans/06-activestorage-adapter.md` — the next major chunk; not
+  built yet
+
+The format of each plan is consistent: Goal / Preconditions / Work /
+Acceptance. The acceptance checklists are runnable — they're meant
+to be the gate for marking the step complete.
+
+## Things deliberately NOT in the gem
+
+Rejected to keep scope tight:
+
+- Live HLS / DASH support — VOD only
+- DRM beyond pre-signed URLs
+- Custom segment naming via post-encode rewriting (ffmpeg's templating
+  covers what we need)
+- Multi-profile fan-out from one source within a single `process` —
+  use multiple profile instances if you need both `WebVideo` and
+  `MobileVideo` outputs
+
+## Release workflow
+
+```sh
+# 1. Bump lib/hls/version.rb
+# 2. Move the [Unreleased] section in CHANGELOG.md under the new version
+bundle exec rake release
+```
+
+This tags, pushes, and publishes to rubygems. There's no CI release
+pipeline yet — releases are manual.