hls 0.1.0 → 0.2.0

data/lib/hls/codecs.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+require "open3"
+require "set"
+
+module HLS
+  # Codec resolution for ffmpeg.
+  #
+  # A profile declares its codec in one of three forms:
+  #
+  #   video_codec :h264                  # logical, auto-resolved per host
+  #   video_codec "libx264"              # explicit ffmpeg encoder name
+  #   video_codec "h264_nvenc"           # explicit (cloud GPU)
+  #
+  # When the profile asks for a logical codec, this module picks the best
+  # available encoder for the current host by consulting the ffmpeg
+  # encoder list. The list is queried once and cached.
+  module Codecs
+    H264 = {
+      videotoolbox: "h264_videotoolbox", # macOS hardware
+      nvenc:        "h264_nvenc",        # NVIDIA GPU
+      qsv:          "h264_qsv",          # Intel QuickSync
+      libx264:      "libx264"            # software fallback
+    }.freeze
+
+    # Per-platform priority order for the :h264 logical codec. The first
+    # encoder available on the host wins.
+    H264_PRIORITY = {
+      darwin: [:videotoolbox, :libx264],
+      linux:  [:nvenc, :qsv, :libx264]
+    }.freeze
+
+    class UnknownEncoder < StandardError; end
+
+    module_function
+
+    # Resolves a `video_codec` value to an explicit ffmpeg encoder name.
+    def resolve(value)
+      case value
+      when :h264
+        resolve_h264
+      when Symbol
+        # Already a specific variant: :libx264, :nvenc, etc.
+        H264.fetch(value) { raise UnknownEncoder, "Unknown codec symbol: #{value}" }
+      when String
+        value
+      else
+        raise ArgumentError, "Unsupported video_codec value: #{value.inspect}"
+      end
+    end
+
+    # The set of encoders ffmpeg reports as available on this host. Cached
+    # for the life of the process.
+    def available_encoders
+      @available_encoders ||= probe_encoders
+    end
+
+    # Reset the encoder cache. Useful in tests.
+    def reset!
+      @available_encoders = nil
+    end
+
+    def resolve_h264
+      priority = H264_PRIORITY[platform] || [:libx264]
+      encoder_name = priority
+        .map { |sym| H264.fetch(sym) }
+        .find { |name| available_encoders.include?(name) }
+
+      encoder_name || "libx264"
+    end
+
+    def platform
+      case RbConfig::CONFIG["host_os"]
+      when /darwin/  then :darwin
+      when /linux/   then :linux
+      when /mswin|mingw|cygwin/ then :windows
+      else :unknown
+      end
+    end
+
+    def probe_encoders
+      stdout, _stderr, status = Open3.capture3("ffmpeg", "-hide_banner", "-encoders")
+      return Set.new unless status.success?
+
+      stdout.lines.filter_map do |line|
+        # Encoder lines look like:  V..... libx264               ...
+        # Skip the header and metadata lines.
+        next unless line =~ /\A [\sVAS\.][\sFSXBD\.]{5}\s+(\S+)/
+
+        $1
+      end.to_set
+    end
+  end
+end

data/lib/hls/directory.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module HLS
+  # Walks a source directory and yields `(input, relative_output_dir)`
+  # pairs for each matching file. The relative output dir drops the
+  # source's extension so callers can join it onto a destination root.
+  #
+  # Example:
+  #
+  #   HLS::Directory.new("uploads").glob("**/*.mp4").each do |input, output|
+  #     # input is an HLS::Input
+  #     # output is a Pathname like "course/lecture-01" (no extension)
+  #   end
+  class Directory
+    include Enumerable
+
+    def initialize(source)
+      @source = Pathname.new(source)
+    end
+
+    def glob(pattern)
+      @pattern = pattern
+      self
+    end
+
+    def each(&block)
+      raise ArgumentError, "call .glob(pattern) before iterating" unless @pattern
+
+      @source.glob(@pattern).each do |path|
+        relative = path.relative_path_from(@source)
+        output = relative.dirname.join(relative.basename(path.extname))
+        yield Input.new(path), output
+      end
+    end
+  end
+end

data/lib/hls/encode_job.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Loaded by the Railtie when ActiveJob is available. Plain-Ruby usage of
+# the gem doesn't pull this in.
+return unless defined?(ActiveJob)
+
+module HLS
+  # ActiveJob wrapper that runs a profile's full pipeline (encode + upload).
+  #
+  # Enqueue with:
+  #
+  #   HLS::EncodeJob.perform_later(
+  #     profile: "CourseVideo",
+  #     input:   "/path/to/source.mp4",
+  #     output:  "/path/to/working/dir",
+  #     key_prefix: "phlex/forms/overview"
+  #   )
+  class EncodeJob < ActiveJob::Base
+    queue_as { ENV.fetch("HLS_QUEUE", "default") }
+
+    # Another worker is encoding the same output dir. Retrying just
+    # means we'll bump heads with them again — the lock is released
+    # exactly when their work finishes, and at that point the state
+    # sidecar will say `encoded?`, so the original caller can simply
+    # re-enqueue if they care to verify.
+    discard_on HLS::Lock::Busy
+
+    # Malformed state.json is operator-intervention territory: retrying
+    # silently re-runs the encode and re-corrupts. Surface it to the
+    # dead-letter queue so someone notices.
+    discard_on HLS::State::CorruptError
+
+    def perform(profile:, input:, output:, key_prefix: nil)
+      profile_class = profile.is_a?(Class) ? profile : profile.constantize
+      input_obj = input.is_a?(HLS::Input) ? input : HLS::Input.new(input)
+
+      profile_class.new(
+        input: input_obj,
+        output: Pathname.new(output),
+        key_prefix: key_prefix
+      ).process
+    end
+  end
+end

data/lib/hls/input.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+require "pathname"
+
+module HLS
+  # An input video file. Probes its metadata via ffprobe lazily (the first
+  # time you ask for `width`, `height`, etc.) and caches the result.
+  class Input
+    PROBE_ARGS = %w[
+      -v error
+      -select_streams v:0
+      -show_entries stream
+      -show_entries format
+      -of json
+    ].freeze
+
+    # Fallback framerate when ffprobe doesn't report one (rare, but
+    # possible for some containers / streams). 30fps is the safe choice
+    # for web video — common for screencasts and matches most uploads.
+    DEFAULT_FRAMERATE = 30
+
+    attr_reader :path
+
+    def initialize(path)
+      @path = Pathname.new(path)
+    end
+
+    def width    = video_stream[:width]
+    def height   = video_stream[:height]
+    def bitrate  = video_stream[:bit_rate]
+    def codec    = video_stream[:codec_name]
+    def duration = json.dig(:format, :duration)&.to_f
+
+    # Frames per second as a Float. ffprobe reports framerate as a
+    # rational ("30000/1001"); we resolve it to a float and round to the
+    # nearest int. Returns DEFAULT_FRAMERATE if the input doesn't
+    # advertise a usable framerate.
+    def framerate
+      raw = video_stream[:avg_frame_rate] || video_stream[:r_frame_rate]
+      return DEFAULT_FRAMERATE if raw.nil? || raw.empty? || raw == "0/0"
+
+      num, den = raw.split("/").map(&:to_f)
+      return DEFAULT_FRAMERATE if den.nil? || den.zero?
+      (num / den).round
+    end
+
+    def json
+      @json ||= probe
+    end
+
+    # Returns true if ffprobe found a usable video stream. False for
+    # audio-only files, malformed media, or anything missing pixel
+    # dimensions.
+    def video?
+      stream = json.dig(:streams, 0)
+      !!(stream && stream[:width] && stream[:height])
+    end
+
+    # Raises HLS::Error if the input is not a video. Call this before
+    # handing an Input to the encode pipeline if you want to fail fast
+    # with a clear message rather than waiting for ffmpeg to choke.
+    def validate!
+      return self if video?
+      raise HLS::Error,
+        "#{@path} has no video stream — ffprobe found " \
+        "#{json[:streams]&.size || 0} stream(s) but none with width/height. " \
+        "Audio-only files and non-media files are not supported."
+    end
+
+    private
+
+    # Returns the first video stream's metadata, or raises HLS::Error if
+    # there is none. We don't return an empty hash silently — `width`
+    # returning nil leads to obscure crashes deeper in the pipeline.
+    def video_stream
+      json.dig(:streams, 0) or raise HLS::Error,
+        "#{@path} has no video stream (ffprobe returned no streams matching v:0)"
+    end
+
+    def probe
+      raise HLS::Error, "input file not found: #{@path}" unless @path.exist?
+
+      stdout, stderr, status = Open3.capture3("ffprobe", *PROBE_ARGS, @path.to_s)
+      unless status.success?
+        raise HLS::Error, "ffprobe failed for #{@path}: #{stderr.strip}"
+      end
+
+      JSON.parse(stdout, symbolize_names: true)
+    end
+  end
+end

data/lib/hls/instrumentation.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module HLS
+  # Lightweight instrumentation wrapper around ActiveSupport::Notifications.
+  #
+  # Subscribe to the events from your host app to wire up logging,
+  # metrics, or tracing. Event names follow the Rails convention
+  # `<action>.<library>` so they show up nicely in LogSubscriber output.
+  #
+  #   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 emitted:
+  #
+  #   encode.hls         — encode! finished. payload: profile, output, renditions
+  #   poster.hls         — poster! finished. payload: profile, output, count
+  #   verify.hls         — verify_encode! passed. payload: profile, output
+  #   upload_object.hls  — single object PUT to the bucket. payload: key, bytes, content_type
+  #   process.hls        — full process pipeline. payload: profile, key_prefix, uploaded, skipped
+  #
+  # When ActiveSupport::Notifications isn't loaded (plain-Ruby usage,
+  # specs without Rails), the helper is a no-op that still yields.
+  module Instrumentation
+    module_function
+
+    # Wraps a block in an ActiveSupport::Notifications event. Yields the
+    # mutable payload hash to the block so callers can attach result
+    # data (e.g., uploaded counts) before the event is published. When
+    # ActiveSupport::Notifications isn't loaded, yields the same payload
+    # hash with no surrounding instrumentation.
+    def instrument(event, payload = {})
+      if defined?(ActiveSupport::Notifications)
+        ActiveSupport::Notifications.instrument("#{event}.hls", payload) { yield payload if block_given? }
+      else
+        yield payload if block_given?
+      end
+    end
+  end
+end

data/lib/hls/lock.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+require "pathname"
+
+module HLS
+  # Advisory file lock for an encode run. Two workers asked to process
+  # the same output directory at the same time would corrupt each
+  # other's state.json and leave a half-uploaded bundle. The lock
+  # makes that case fail loudly instead of silently.
+  #
+  # Uses `flock` with `LOCK_EX | LOCK_NB` — the second process gets
+  # `HLS::Lock::Busy` immediately rather than blocking. The lock file
+  # itself (`<output>/.hls-lock`) is left on disk; only the kernel-level
+  # advisory lock is released. This keeps the file's inode stable so
+  # `flock` works reliably across re-runs.
+  class Lock
+    FILENAME = ".hls-lock"
+
+    class Busy < HLS::Error; end
+
+    def self.acquire(output_dir, &block)
+      new(output_dir).acquire(&block)
+    end
+
+    attr_reader :path
+
+    def initialize(output_dir)
+      @path = Pathname.new(output_dir).join(FILENAME)
+    end
+
+    # Acquires the lock, yields, releases. If another process holds it,
+    # raises `HLS::Lock::Busy` immediately — we don't wait.
+    def acquire
+      @path.parent.mkpath
+      File.open(@path, File::CREAT | File::RDWR, 0o644) do |f|
+        unless f.flock(File::LOCK_EX | File::LOCK_NB)
+          raise Busy, "another process is already encoding #{@path.parent}"
+        end
+        f.truncate(0)
+        f.write("#{Process.pid}\n")
+        f.flush
+        begin
+          yield
+        ensure
+          f.flock(File::LOCK_UN)
+        end
+      end
+    end
+  end
+end

data/lib/hls/manifest.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require "m3u8"
+
+module HLS
+  # Reads an HLS bundle out of an S3-compatible bucket and returns
+  # signed-URL playlists ready to hand to a video player.
+  #
+  # The Manifest is the read-side counterpart to ApplicationVideo. A
+  # profile class hands one to its caller via `profile.manifest(path)`,
+  # but Manifest can also be used directly with any bucket.
+  #
+  # Example:
+  #
+  #   manifest = CourseVideo.manifest("phlex/forms/overview")
+  #   manifest.master_playlist  # => M3u8::Playlist with rewritten URIs
+  #   manifest.poster_url       # => pre-signed URL string
+  #
+  # `master_playlist` rewrites variant URIs from ffmpeg's flat
+  # `0/index.m3u8` form to a controller-routable `<path>/0.m3u8` shape
+  # so the host app's controller can serve each variant by name.
+  class Manifest
+    DEFAULT_POSTER  = "poster"
+    MASTER_PLAYLIST = "index.m3u8"
+    VARIANT_PLAYLIST = "index.m3u8"
+
+    attr_reader :storage, :path, :segment_duration, :cache
+
+    # storage::         An HLS::Storage adapter (S3, Memory, ...). Owns
+    #                   the bucket and the default signing TTL.
+    # path::            key prefix where the bundle lives
+    # segment_duration: HLS segment length, drives Variant#duration math
+    # variant_uri::     callable taking (path:, variant_index:) and
+    #                   returning the URI string to put in the master
+    #                   playlist for that variant. Default produces
+    #                   `<basename(path)>/<index>.m3u8`, which matches a
+    #                   `/videos/*path/:id/:variant` Rails route shape.
+    # cache::           an HLS::Cache (or any object responding to
+    #                   `fetch(key, &block)`). When set, raw playlists
+    #                   are read through it instead of being fetched on
+    #                   every request. nil disables caching.
+    def initialize(storage:, path:,
+                   segment_duration: 4, variant_uri: nil,
+                   cache: nil)
+      @storage          = storage
+      @path             = path
+      @segment_duration = Integer(segment_duration)
+      @variant_uri      = variant_uri || DEFAULT_VARIANT_URI
+      @cache            = cache
+    end
+
+    # Default presigned-URL TTL for this manifest. Reads from the
+    # storage adapter so signing config lives in one place.
+    def expires_in
+      storage.signing_ttl
+    end
+
+    DEFAULT_VARIANT_URI = ->(path:, variant_index:) {
+      "#{::File.basename(path)}/#{variant_index}.m3u8"
+    }
+
+    # Pre-signed URL for a poster image. With no argument, returns
+    # `<path>/poster.jpg` (back-compat with the legacy `HLS::Poster`
+    # filename). With a name, returns `<path>/<name>.jpg`.
+    def poster_url(name = DEFAULT_POSTER)
+      presigned_url("#{name}.jpg")
+    end
+
+    # Master playlist with variant URIs rewritten from ffmpeg's
+    # `<index>/index.m3u8` form to whatever the configured `variant_uri`
+    # callable returns. The default produces `<id>/<index>.m3u8` where
+    # `<id>` is the last segment of the manifest's path — relative to
+    # the master playlist's URL, so a player fetching
+    # `/videos/<path>/<id>.m3u8` resolves the variant URI to
+    # `/videos/<path>/<id>/<index>.m3u8`.
+    #
+    # Returns a fresh M3u8::Playlist on each call (does not mutate the
+    # cached raw playlist).
+    def master_playlist
+      list = M3u8::Playlist.new
+      list.items = raw_master_playlist.items.map do |item|
+        rewritten = item.clone
+        rewritten.uri = @variant_uri.call(
+          path: path,
+          variant_index: ::File.dirname(item.uri)
+        )
+        rewritten
+      end
+      list
+    end
+
+    # All variants discovered in the master playlist, indexed by
+    # ffmpeg's variant path (`"0"`, `"1"`, ...).
+    def variants
+      @variants ||= raw_master_playlist.items.map do |item|
+        variant_path = ::File.dirname(item.uri)
+        variant_playlist = read_playlist(variant_path, VARIANT_PLAYLIST)
+        Variant.new(manifest: self, variant_path: variant_path, items: variant_playlist.items)
+      end
+    end
+
+    # Look up a variant by ffmpeg's path identifier ("0", "1", ...).
+    def variant(variant_path)
+      variants.find { |v| v.variant_path == variant_path }
+    end
+
+    # Pre-signs an arbitrary key under this manifest's path.
+    def presigned_url(*parts, expires_in: self.expires_in)
+      object(*parts).presigned_url(:get, expires_in: Integer(expires_in))
+    end
+
+    private
+
+    def object(*parts)
+      storage.object(::File.join(path, *parts))
+    end
+
+    def read_object(*parts)
+      object(*parts).get.body.read
+    end
+
+    def read_playlist(*parts)
+      M3u8::Reader.new.read(cached_object_body(*parts))
+    end
+
+    # Reads a key's bytes through the cache when one is configured;
+    # otherwise hits the bucket directly. Cache keys include the bucket
+    # path so two manifests on different prefixes don't collide. The
+    # TTL lives on the cache object itself (HLS::Cache wraps a backend
+    # with a TTL); raw `Rails.cache` works too but uses its default TTL.
+    def cached_object_body(*parts)
+      return read_object(*parts) if cache.nil?
+
+      key = "hls/manifest/#{::File.join(path, *parts)}"
+      cache.fetch(key) { read_object(*parts) }
+    end
+
+    # The raw, untouched master playlist as ffmpeg wrote it. Kept private
+    # because callers should always go through `master_playlist`, which
+    # rewrites variant URIs. Memoized so repeated reads (poster_url +
+    # master_playlist + variants in one request) only pay one S3 GET.
+    def raw_master_playlist
+      @raw_master_playlist ||= read_playlist(MASTER_PLAYLIST)
+    end
+
+    # A single rendition variant — its ordered list of segments and the
+    # ability to slice a duration window for previews.
+    class Variant
+      attr_reader :manifest, :variant_path, :items
+
+      def initialize(manifest:, variant_path:, items:)
+        @manifest = manifest
+        @variant_path = variant_path
+        @items = items
+      end
+
+      # Duration in seconds. Approximate — uses segment_duration as a
+      # uniform per-segment value, which matches how ffmpeg writes VOD
+      # bundles. The last segment may be slightly shorter.
+      def duration
+        items.count * manifest.segment_duration
+      end
+
+      # Slice a duration window. The range is in seconds. Inclusive ranges
+      # round down, exclusive ranges round up. Useful for preview windows
+      # (e.g. `variant[0...30]` for a 30-second teaser).
+      def [](range)
+        raise ArgumentError, "Only Range objects are supported" unless range.is_a?(Range)
+
+        segment_count =
+          if range.exclude_end?
+            (range.end.to_f / manifest.segment_duration).ceil
+          else
+            (range.end.to_f / manifest.segment_duration).floor
+          end
+
+        Variant.new(manifest: manifest, variant_path: variant_path, items: items.take(segment_count))
+      end
+
+      # The variant playlist with each segment rewritten to a pre-signed
+      # URL. Returns a fresh M3u8::Playlist; does not mutate `items`.
+      def playlist
+        list = M3u8::Playlist.new
+        list.items = items.map do |item|
+          signed = item.clone
+          signed.segment = manifest.presigned_url(variant_path, item.segment)
+          signed
+        end
+        list
+      end
+    end
+  end
+end

data/lib/hls/railtie.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module HLS
+  # Railtie that wires HLS into a host Rails app.
+  #
+  # - Registers `app/videos` as an autoload + eager-load path so that
+  #   profile classes like `app/videos/course_video.rb` are picked up
+  #   by Zeitwerk.
+  # - Lazily loads HLS::EncodeJob when ActiveJob is loaded.
+  #
+  # That's it. There is intentionally no Rails.application.config.hls
+  # config bag and no load hook to subscribe to. Configure profile
+  # classes directly:
+  #
+  #   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
+  #
+  # Zeitwerk reloads the class in dev so the settings re-apply
+  # automatically; no special hook needed.
+  class Railtie < Rails::Railtie
+    initializer "hls.autoload_paths", before: :set_autoload_paths do |app|
+      videos_path = app.root.join("app", "videos")
+      app.config.autoload_paths   << videos_path.to_s
+      app.config.eager_load_paths << videos_path.to_s
+    end
+
+    initializer "hls.encode_job" do
+      ActiveSupport.on_load(:active_job) do
+        require "hls/encode_job"
+      end
+    end
+  end
+end