hls 0.1.0 → 0.2.0

data/README.md

@@ -16,15 +16,22 @@ The most annoying part about serving HLS videos from private object stores is ge
 
 ### Rails integration
 
-When a user requests a video, you probably want a controller that determines whether they have access to the video. If they do, the Rails integration will request a manifest file stored along side your video to generate the pre-signed URLs for each chunk.
+A Railtie autoloads `app/videos/*.rb` profile classes, wires app-wide
+defaults from `config/initializers/hls.rb`, and ships an
+`HLS::EncodeJob` ActiveJob wrapper for queue-driven encoding.
 
-Generators will also be included that pin an HLS polyfill for browsers that don't support HLS natively, like Chrome and Firefox.
+## Requirements
+
+- Ruby 3.1+
+- `ffmpeg` and `ffprobe` on the PATH (Homebrew, apt, or your distro
+  equivalent)
+- An S3-compatible bucket (Tigris, Cloudflare R2, AWS S3, MinIO, etc.)
 
 ## Support
 
 Consider [buying a video course from Beautiful Ruby](https://beautifulruby.com) and learn a thing or two to keep the machine going that originally built this gem.
 
-[![](https://immutable.terminalwire.com/NgTt6nzO1aEnExV8j6ODuKt2iZpY74ZF8ecpUSCp4A0tXA0ErpJIS4cdMX0tQQKOWwZSl65jWnpzpgCLJThhhWtZJGr42XKt7WIi.png)](https://beautifulruby.com/phlex/forms/overview)
+[![](https://immutable.terminalwire.com/NgTt6nzO1aEnExV8j6ODuKt2iZpY74ZF8ecpUSCp4A0tXA0ErpJIS4cdMX0tQQKOWwZSl65jWnpzpgCLJThhhWtZJGr42XKt7WIi.png)](https://beautifulruby.com/phlex)
 
 ## Installation
 
@@ -40,9 +47,281 @@ If bundler is not being used to manage dependencies, install the gem by executin
 gem install hls
 ```
 
+In a Rails app, scaffold the initial config + base profile with:
+
+```bash
+bin/rails g hls:install
+```
+
+This writes `config/initializers/hls.rb` (with env-var-driven bucket /
+S3 config) and `app/videos/application_video.rb` (the base class your
+profiles inherit from). Then generate per-content-type profiles:
+
+```bash
+bin/rails g hls:video Course
+# => app/videos/course_video.rb
+```
+
+The generated profile has a sensible 3-rendition ladder, a hero
+poster, and inline comments for the common knobs. Edit to tune.
+
 ## Usage
 
-TODO: Write usage instructions here when the gem is finished
+### Declare a profile
+
+In a Rails app, `app/videos/*.rb` is autoloaded and inherits app-wide
+defaults from `config/initializers/hls.rb`:
+
+```ruby
+# config/initializers/hls.rb
+require "aws-sdk-s3"
+
+HLS.s3_resource = Aws::S3::Resource.new(
+  access_key_id:     ENV.fetch("VIDEO_AWS_ACCESS_KEY_ID"),
+  secret_access_key: ENV.fetch("VIDEO_AWS_SECRET_ACCESS_KEY"),
+  endpoint:          ENV.fetch("VIDEO_S3_ENDPOINT_URL"),
+  region:            "auto"
+)
+
+# app/videos/application_video.rb — bucket + signing TTL live on the
+# storage adapter, configured here so every subclass under app/videos
+# inherits them. Override `def self.storage` on a subclass to point
+# at a different bucket.
+class ApplicationVideo < HLS::ApplicationVideo
+  def self.storage = HLS::Storage::S3.new(
+    bucket_name: ENV.fetch("VIDEO_S3_BUCKET_NAME"),
+    signing_ttl: 1.hour
+  )
+
+  segment_duration 4
+end
+
+# app/videos/course_video.rb
+class CourseVideo < ApplicationVideo
+  rendition :high,   scale: 1.0
+  rendition :medium, scale: 0.5
+  rendition :small,  scale: 0.25
+
+  poster :hero,      scale: 1.0
+  poster :thumbnail, width: 320, height: 180
+end
+```
+
+### Encode and upload
+
+```ruby
+profile = CourseVideo.new(
+  input: HLS::Input.new("lecture.mp4"),
+  output: Pathname.new("tmp/encoded"),
+  key_prefix: "courses/phlex/intro"
+)
+profile.process
+# Probes input → encodes HLS multiplex + posters → uploads to bucket.
+# Idempotent: re-running with the same input is a no-op.
+```
+
+Or enqueue the work asynchronously:
+
+```ruby
+HLS::EncodeJob.perform_later(
+  profile: "CourseVideo",
+  input:  "lecture.mp4",
+  output: "tmp/encoded",
+  key_prefix: "courses/phlex/intro"
+)
+```
+
+### Serve from a controller
+
+```ruby
+class VideosController < ApplicationController
+  before_action { @manifest = CourseVideo.manifest(params[:id]) }
+
+  def index
+    respond_to do |format|
+      format.m3u8 { render plain: @manifest.master_playlist }
+      format.jpg  { redirect_to @manifest.poster_url(:hero), allow_other_host: true }
+    end
+  end
+
+  def show
+    variant = @manifest.variant(params[:variant])
+    render plain: variant.playlist
+  end
+end
+```
+
+`master_playlist` rewrites variant URIs to a controller-routable shape;
+`variant.playlist` rewrites segment URIs to pre-signed S3 URLs that
+the player can fetch directly.
+
+### Preview windows
+
+`Variant#[range]` slices the variant to a duration in seconds. Useful
+for locked-content previews:
+
+```ruby
+PREVIEW_DURATION = 30.seconds
+list = if subscriber?
+  @manifest.variant(params[:variant]).playlist
+else
+  @manifest.variant(params[:variant])[0...PREVIEW_DURATION].playlist
+end
+```
+
+### Testing your profile
+
+The gem ships test helpers for verifying that your profile produces a
+correct bundle end-to-end:
+
+```ruby
+require "hls/testing"
+
+RSpec.describe CourseVideo do
+  include HLS::Testing
+
+  it "produces a complete HLS bundle" do
+    video = generate_test_video(duration: 12)
+    output = Pathname.new(Dir.mktmpdir)
+
+    profile = CourseVideo.new(input: HLS::Input.new(video), output: output)
+    silence_ffmpeg { profile.encode!; profile.poster! }
+
+    expect(output).to be_a_valid_hls_bundle
+      .with_variants(3)
+      .with_posters(:hero, :thumbnail)
+  end
+end
+```
+
+### Codec auto-detection
+
+By default `video_codec :h264` resolves to the best available encoder
+on the host (`h264_videotoolbox` on macOS, `h264_nvenc`/`h264_qsv` on
+Linux GPUs, `libx264` as the universal fallback). Override per-profile
+when you need an explicit one:
+
+```ruby
+class WebVideo < ApplicationVideo
+  video_codec "libx264"   # always software, regardless of host
+end
+```
+
+### Configuration reference
+
+Every class-level setting on `HLS::ApplicationVideo` is inheritable
+through the class hierarchy. For static values, set with the DSL form
+(`segment_duration 4`); for dynamic values that should re-read on
+every Zeitwerk reload, override the reader (`def self.storage = ...`).
+
+| Setting              | Default              | Notes |
+|----------------------|----------------------|-------|
+| `storage`            | _none — required_    | `HLS::Storage::S3`, `HLS::Storage::Memory`, or any conforming adapter |
+| `segment_duration`   | `4`                  | HLS segment length, seconds |
+| `video_codec`        | `:h264`              | Symbol (auto-resolved) or string (explicit) |
+| `audio_codec`        | `"aac"`              | |
+| `audio_bitrate`      | `128`                | kbps |
+| `bits_per_pixel`     | `:mixed` (4)         | `:screencast` (3), `:mixed` (4), `:motion` (6) |
+| `max_bitrate_kbps`   | `15_000`             | Caps scaled-rendition bitrate |
+| `ffmpeg_timeout`     | `nil`                | Hard cap (seconds) on a single ffmpeg run; `nil` disables |
+| `cache`              | `nil`                | `HLS::Cache` (groups a `Rails.cache`-shaped backend with a TTL) or any object responding to `fetch(key, &block)` |
+
+`HLS::Storage::S3` itself takes `bucket_name:`, `signing_ttl:`, and an
+optional `s3_resource:` (defaults to `HLS.s3_resource`). For tests or
+non-AWS backends, use `HLS::Storage::Memory.new(name: ...)` or any
+object responding to `signing_ttl` and `object(key)`.
+
+`HLS.s3_resource` is process-global. If two profiles need different
+SDK clients (different regions, credentials, or endpoints), pass
+`s3_resource:` directly to each `HLS::Storage::S3` rather than relying
+on the global default:
+
+```ruby
+class CourseVideo < ApplicationVideo
+  def self.storage = HLS::Storage::S3.new(
+    s3_resource: Aws::S3::Resource.new(region: "us-west-2", ...),
+    bucket_name: "course-videos",
+    signing_ttl: 1.hour
+  )
+end
+```
+
+### Concurrency and retries
+
+The uploader runs PUTs in parallel with bounded concurrency and retries
+transient failures with exponential backoff. Defaults are tuned for
+typical home/office connections; override per-call:
+
+```ruby
+HLS::Uploader.new(
+  storage: storage, output: out, key_prefix: prefix, state: state,
+  concurrency: 8,        # default 4
+  max_retries: 5,        # default 3
+  initial_backoff: 0.25  # default 0.5 seconds, doubles per attempt
+).perform
+```
+
+Only transient errors (network timeouts, 503s, throttling) are retried;
+permanent errors (NoSuchBucket, 403) fail fast.
+
+### Instrumentation
+
+The gem publishes ActiveSupport::Notifications events when AS is
+loaded. Subscribe to wire up logging or metrics:
+
+```ruby
+ActiveSupport::Notifications.subscribe("encode.hls") do |name, start, finish, _, payload|
+  Rails.logger.info "[hls] encoded #{payload[:profile]} in #{((finish - start) * 1000).round}ms"
+end
+```
+
+Events:
+
+| Name                | Payload keys                                |
+|---------------------|---------------------------------------------|
+| `encode.hls`        | `profile`, `output`, `renditions`           |
+| `poster.hls`        | `profile`, `output`, `count`                |
+| `verify.hls`        | `profile`, `output`                         |
+| `upload_object.hls` | `key`, `bytes`, `content_type`              |
+| `upload_retry.hls`  | `key`, `attempt`, `error`, `message`        |
+| `process.hls`       | `profile`, `key_prefix`, `uploaded`, `skipped` |
+
+### Storage adapters
+
+The default backend is `HLS::Storage::S3`, which wraps an
+`Aws::S3::Bucket` (works with AWS S3, Tigris, Cloudflare R2, MinIO).
+`HLS::Storage::Memory` ships as a no-network adapter useful for tests.
+Roll your own by implementing the protocol — `signing_ttl` plus
+`object(key)` returning something that responds to `get`,
+`put(body:, content_type:, cache_control:)`, and
+`presigned_url(:get, expires_in:)`.
+
+#### MinIO
+
+MinIO is API-compatible with S3 — point `HLS.s3_resource` at its
+endpoint:
+
+```ruby
+# config/initializers/hls.rb
+HLS.s3_resource = Aws::S3::Resource.new(
+  access_key_id:     ENV["MINIO_ACCESS_KEY"],
+  secret_access_key: ENV["MINIO_SECRET_KEY"],
+  endpoint:          ENV["MINIO_ENDPOINT"], # e.g. http://localhost:9000
+  region:            "us-east-1",
+  force_path_style:  true                   # required for MinIO
+)
+
+# app/videos/application_video.rb
+class ApplicationVideo < HLS::ApplicationVideo
+  def self.storage = HLS::Storage::S3.new(
+    bucket_name: ENV.fetch("MINIO_BUCKET"),
+    signing_ttl: 1.hour
+  )
+end
+```
+
+`force_path_style: true` is the key MinIO requirement — MinIO doesn't
+do virtual-hosted-style addressing.
 
 ## Development
 

data/examples/directory.rb

@@ -4,62 +4,36 @@ gemfile do
   source "https://rubygems.org"
 
   gem "hls", path: ".."
-  gem "parallel"
 end
 
 require "fileutils"
-require "pathname"
-require "etc"
-require "shellwords"
-require "uri"
 
-storage = Pathname.new("/Users/bradgessler/Desktop")
+storage = Pathname.new(ENV.fetch("SOURCE_PATH", "/Users/bradgessler/Desktop"))
 source = storage.join("Exports")
 destination = storage.join("Uploads")
 
-CONCURRENCY = Etc.nprocessors / 2
+class CourseVideo < HLS::ApplicationVideo
+  bits_per_pixel :screencast
 
-class Jobs
-  include Enumerable
+  rendition :full,   scale: 1.0
+  rendition :medium, scale: 0.5
+  rendition :small,  scale: 0.25
 
-  def initialize
-    @jobs = []
-  end
-
-  def schedule(&job)
-    @jobs << job
-  end
-
-  def render(rendition)
-    schedule do
-      ffmpeg rendition
-    end
-  end
-
-  def process(in_processes: CONCURRENCY, **options)
-    Parallel.each(@jobs, in_processes: in_processes, &:call)
-  end
-
-  private
-
-  def ffmpeg(task)
-    cmd = task.command.map(&:to_s)
-    puts "[#{task.class.name}] Running: #{Shellwords.join(cmd)}"
-    system(*cmd)
-    puts "[#{task.class.name}] Done"
-  end
+  poster :poster, scale: 1.0
 end
 
-jobs = Jobs.new
+directory = HLS::Directory.new(source).glob("**/*.mp4").to_a
+puts "Processing #{directory.size} files from #{source}"
 
-HLS::Directory.new(source).glob("**/*.mp4").each do |input, path|
+directory.each do |input, path|
   output = destination.join(path)
   FileUtils.mkdir_p(output)
 
-  package = HLS::Video::Web.new(input:, output:)
-  puts "Processing renditions for: #{input}"
+  puts "Processing #{input.path} to #{output}"
 
-  jobs.render package
-end
+  profile = CourseVideo.new(input:, output:)
+  profile.encode!
+  profile.poster!
 
-jobs.process
+  puts "Completed #{input.path} to #{output}"
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module Hls
+  module Generators
+    # Bootstraps a host Rails app for the HLS gem:
+    #   - config/initializers/hls.rb (bucket + S3 resource config)
+    #   - app/videos/application_video.rb (base profile class)
+    #
+    # Usage:
+    #
+    #   bin/rails g hls:install
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      def create_initializer
+        template "initializer.rb", "config/initializers/hls.rb"
+      end
+
+      def create_application_video
+        template "application_video.rb", "app/videos/application_video.rb"
+      end
+
+      def post_install_message
+        say <<~MSG
+
+          HLS installed.
+
+          Next steps:
+            1. Set the env vars referenced in config/initializers/hls.rb
+               (VIDEO_AWS_ACCESS_KEY_ID, VIDEO_S3_BUCKET_NAME, etc.)
+            2. Generate your first profile:
+                 bin/rails g hls:video Course
+            3. Encode + upload a video:
+                 CourseVideo.new(input: HLS::Input.new("lecture.mp4"),
+                                 output: Pathname.new("tmp/encoded")).process
+        MSG
+      end
+    end
+  end
+end

data/lib/generators/hls/install/templates/application_video.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+# Base class for every video profile in this app. Defaults set here
+# flow down to subclasses unless overridden. Per-profile classes live
+# alongside this file at app/videos/<name>_video.rb — generate one
+# with:
+#
+#   bin/rails g hls:video Course
+#
+class ApplicationVideo < HLS::ApplicationVideo
+  # The storage backend. Defaulted to an S3 bucket configured from
+  # env vars; signing TTL controls how long pre-signed URLs stay
+  # valid. Override `storage` per-subclass to point at a different
+  # bucket, swap in a different adapter, etc.
+  def self.storage = HLS::Storage::S3.new(
+    bucket_name: ENV.fetch("VIDEO_S3_BUCKET_NAME"),
+    signing_ttl: 1.hour
+  )
+
+  # Examples of app-wide overrides. Uncomment to apply to every
+  # subclass.
+  #
+  # video_codec      :h264          # auto-resolves the best encoder
+  # audio_codec      "aac"
+  # bits_per_pixel   :screencast    # :screencast (3), :mixed (4), :motion (6)
+  # max_bitrate_kbps 15_000
+  # segment_duration 4
+end

data/lib/generators/hls/install/templates/initializer.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# HLS gem configuration. Sets the Aws::S3::Resource the gem talks to.
+# Per-profile bucket / signing TTL / segment duration live on the
+# profile classes themselves under app/videos/.
+
+require "aws-sdk-s3"
+
+HLS.s3_resource = Aws::S3::Resource.new(
+  access_key_id:     ENV.fetch("VIDEO_AWS_ACCESS_KEY_ID"),
+  secret_access_key: ENV.fetch("VIDEO_AWS_SECRET_ACCESS_KEY"),
+  endpoint:          ENV.fetch("VIDEO_S3_ENDPOINT_URL"),
+  region:            ENV.fetch("VIDEO_AWS_REGION", "auto")
+)

data/lib/generators/hls/video/templates/video.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Encoding profile for <%= class_name %>. Inherits app-wide defaults
+# from ApplicationVideo and config/initializers/hls.rb.
+#
+# Usage:
+#
+#   profile = <%= class_name %>.new(
+#     input: HLS::Input.new("path/to/source.mp4"),
+#     output: Pathname.new("tmp/encoded/#{id}"),
+#     key_prefix: "videos/#{id}"
+#   )
+#   profile.process
+#   # Probes input → encodes HLS multiplex + posters → uploads to bucket.
+#   # Idempotent: re-running with the same input is a no-op.
+#
+# Then in your controller:
+#
+#   manifest = <%= class_name %>.manifest("videos/#{id}")
+#   render plain: manifest.master_playlist
+#
+class <%= class_name %> < ApplicationVideo
+  # Three-rendition ladder scaled off the input. Each rendition is
+  # encoded only if it fits within the input dimensions (no upscaling).
+  # `scale:` derives width/height from the source; pass explicit
+  # `width:`/`height:`/`bitrate:` for fixed dimensions.
+  rendition :high,   scale: 1.0
+  rendition :medium, scale: 0.5
+  rendition :small,  scale: 0.25
+
+  # One full-size poster. Add more (thumbnails, social cards, etc.)
+  # by uncommenting the lines below or adding your own.
+  poster :hero, scale: 1.0
+  # poster :thumbnail, width: 320, height: 180
+  # poster :og,        width: 1200, height: 630   # social share card
+
+  # Per-profile overrides. Anything left out falls back to
+  # ApplicationVideo, then the gem's defaults.
+  #
+  # bits_per_pixel   :screencast   # :screencast (3), :mixed (4), :motion (6)
+  # video_codec      "libx264"     # pin software encoder regardless of host
+  # max_bitrate_kbps 8_000         # cap any single rendition's bitrate
+  # segment_duration 2             # tighter segments → faster seeking, more files
+end

data/lib/generators/hls/video/video_generator.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module Hls
+  module Generators
+    # Scaffolds a new video profile under app/videos/.
+    #
+    #   bin/rails g hls:video Course
+    #   # => app/videos/course_video.rb
+    #
+    # The generated file inherits from `ApplicationVideo` and ships with
+    # a sensible default rendition ladder, a hero poster, and inline
+    # comments for the common knobs (alternative codecs, bitrate
+    # tuning, additional posters). Edit the file to tune.
+    class VideoGenerator < Rails::Generators::NamedBase
+      source_root File.expand_path("templates", __dir__)
+
+      def create_video_profile
+        template "video.rb", File.join("app/videos", "#{file_name}_video.rb")
+      end
+
+      private
+
+      # `Course` -> `course`, `BlogPost` -> `blog_post`. Strips a
+      # trailing `Video` so `g hls:video CourseVideo` doesn't produce
+      # `course_video_video.rb`.
+      def file_name
+        super.sub(/_video\z/, "")
+      end
+
+      def class_name
+        "#{file_name.camelize}Video"
+      end
+    end
+  end
+end