hls 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bc3a9e8f4508dbdc33d12b7ce2665d5e455421992520bf6ee36834bf936e2c8c
+  data.tar.gz: 86aa27e58a352a2eb6cab7d368ecc546db4b6b8a2e70b14e827d4185bc42e6df
+SHA512:
+  metadata.gz: 44c7aa81f15a22e0edf70821a506c3b87102bd05140814ff9ecf0f15153264cc7d5ea68c2cfb4610426084df37fea91398125f1f0b95a31b126328211b69f464
+  data.tar.gz: 172a06401b9c59d6e5b3781895893406f2ebdae6d78e55ece3643de3a9648438c0699e7caf382420de1fed78cf8335d37cf8f579d6ecb6112a023b6527fccc56

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/README.md

@@ -0,0 +1,55 @@
+# HLS
+
+When I started working on the [Phlex on Rails video course](https://beautifulruby.com/phlex), I tried streaming mp4 files from an S3 compatible object store and quickly found out from users they were running into issues watching the video. I added to use [HLS](https://en.wikipedia.org/wiki/HTTP_Live_Streaming), but I quickly found out it's a bit of a pain setting that up on a private object store.
+
+## Why?
+
+Creating & serving HLS videos from private object stores is tricky.
+
+### Sane encoding defaults
+
+When you encode a video into HLS format, it cranks out different resolutions and bitrates that play on everything from mobile phones to TVs. You give it an input video and it writes out all the chunks into a directory.
+
+### Generates pre-signed URLs in m3u8 playlists
+
+The most annoying part about serving HLS videos from private object stores is generating pre-signed URLs for each chunk. This gem generates pre-signed URLs for each chunk in the m3u8 playlist, making it easy to serve HLS videos from private object stores.
+
+### 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.
+
+Generators will also be included that pin an HLS polyfill for browsers that don't support HLS natively, like Chrome and Firefox.
+
+## 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)
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add hls
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install hls
+```
+
+## Usage
+
+TODO: Write usage instructions here when the gem is finished
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/beautifulruby/hls.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/examples/directory.rb

@@ -0,0 +1,65 @@
+require "bundler/inline"
+
+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")
+source = storage.join("Exports")
+destination = storage.join("Uploads")
+
+CONCURRENCY = Etc.nprocessors / 2
+
+class Jobs
+  include Enumerable
+
+  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
+end
+
+jobs = Jobs.new
+
+HLS::Directory.new(source).glob("**/*.mp4").each do |input, path|
+  output = destination.join(path)
+  FileUtils.mkdir_p(output)
+
+  package = HLS::Video::Web.new(input:, output:)
+  puts "Processing renditions for: #{input}"
+
+  jobs.render package
+end
+
+jobs.process

data/lib/hls/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module HLS
+  VERSION = "0.1.0"
+end

data/lib/hls.rb

@@ -0,0 +1,212 @@
+# frozen_string_literal: true
+
+require_relative "hls/version"
+require "shellwords"
+require "pathname"
+require "json"
+require "m3u8"
+
+module HLS
+  class Error < StandardError; end
+
+  class Poster
+    attr_reader :input, :output, :width, :height
+
+    def initialize(input:, output:, width:, height:)
+      @input = input
+      @output = output.join("poster.jpg")
+      @width = width
+      @height = height
+    end
+
+    def command
+      [
+        # invoke ffmpeg
+        "ffmpeg",
+        # overwrite output files without confirmation
+        "-y",
+        # input video file
+        "-i", input,
+        # scale video to target resolution
+        "-vf", "scale=w=#{width}:h=#{height}:force_original_aspect_ratio=decrease",
+        # extract only one frame
+        "-frames:v", "1",
+        # output file path
+        output
+      ]
+    end
+  end
+
+  module Video
+    class Base
+      attr_accessor :input, :output, :renditions
+
+      PLAYLIST = "index.m3u8".freeze
+
+      Rendition = Data.define(:width, :height, :bitrate)
+
+      def initialize(input:, output:)
+        @input = Input.new(input)
+        @output = output
+        @renditions = []
+      end
+
+      def downscaleable_renditions
+        @renditions.select { |r| r.width <= input.width }
+      end
+
+      def rendition(...)
+        @renditions << Rendition.new(...)
+      end
+
+      def command
+        [
+          "ffmpeg",
+          "-y",
+          "-i", @input.path,
+          "-filter_complex", filter_complex
+        ] + \
+        video_maps + \
+        audio_maps + \
+        [
+          "-f", "hls",
+          "-var_stream_map", stream_map,
+          "-master_pl_name", PLAYLIST,
+          "-hls_time", "4",
+          "-hls_playlist_type", "vod",
+          "-hls_segment_filename", segment,
+          playlist
+        ]
+      end
+
+      private
+
+      def filter_complex
+        n = downscaleable_renditions.size
+        split = "[0:v]split=#{n}#{(1..n).map { |i| "[v#{i}]" }.join}"
+        scaled = downscaleable_renditions.each_with_index.map do |rendition, i|
+          "[v#{i + 1}]scale='if(gt(iw,#{rendition.width}),#{rendition.width},iw)':'if(gt(iw,#{rendition.width}),-2,ih)'[v#{i + 1}out]"
+        end
+        ([split] + scaled).join("; ")
+      end
+
+      def video_maps(codec: "h264_videotoolbox")
+        downscaleable_renditions.each_with_index.flat_map do |rendition, i|
+          [
+            "-map", "[v#{i + 1}out]",
+            "-c:v:#{i}", codec,
+            "-b:v:#{i}", "#{rendition.bitrate}k"
+          ]
+        end
+      end
+
+      def audio_maps(codec: "aac", bitrate: 128)
+        downscaleable_renditions.each_with_index.flat_map do |_, i|
+          [
+            "-map", "a:0",
+            "-c:a:#{i}", codec,
+            "-b:a:#{i}", "#{bitrate}k",
+            "-ac", "2"
+          ]
+        end
+      end
+
+      def stream_map
+        downscaleable_renditions.each_index.map { |i| "v:#{i},a:#{i}" }.join(" ")
+      end
+
+      def variant
+        @output.join("%v")
+      end
+
+      def segment
+        variant.join("%d.ts").to_s
+      end
+
+      def playlist
+        variant.join(PLAYLIST).to_s
+      end
+    end
+
+    class Web < Base
+      def initialize(...)
+        super(...)
+        # 360p - Low quality for mobile/slow connections
+        rendition width: 640,  height: 360,  bitrate: 500
+        # 480p - Standard definition for basic streaming
+        rendition width: 854,  height: 480,  bitrate: 1000
+        # 720p - High definition for most desktop viewing
+        rendition width: 1280, height: 720,  bitrate: 3000
+        # 1080p - Full HD for high-quality streaming
+        rendition width: 1920, height: 1080, bitrate: 6000
+        # 4K - Ultra HD for premium viewing experience
+        rendition width: 3840, height: 2160, bitrate: 12000
+      end
+    end
+
+    # Do very little work on vidoes so I can get more dev cycles in.
+    class Dev < Base
+      def initialize(...)
+        super(...)
+        # 360p - Low quality for mobile/slow connections
+        rendition width: 640,  height: 360,  bitrate: 500
+      end
+    end
+  end
+
+  class Input
+    attr_reader :path, :json
+
+    def initialize(path)
+      @path = Pathname(path)
+    end
+
+    def json
+      @json ||= probe
+    end
+
+    def width      = stream.dig(:width)
+    def height     = stream.dig(:height)
+    def codec      = stream.dig(:codec_name)
+    def duration   = json.dig(:format, :duration)&.to_f
+    def framerate  = parse_rate(stream.dig(:r_frame_rate))
+
+    private
+
+    def stream
+      json.dig(:streams, 0)
+    end
+
+    def probe
+      raw = `ffprobe -v error -select_streams v:0 \
+        -show_entries stream=width,height,r_frame_rate,codec_name \
+        -show_entries format=duration \
+        -of json "#{@path}"`
+
+      JSON.parse(raw, symbolize_names: true)
+    end
+
+    def parse_rate(rate)
+      return unless rate
+      num, den = rate.split("/").map(&:to_f)
+      return if den.zero?
+      (num / den).round(3)
+    end
+  end
+
+  class Directory
+    def initialize(source)
+      @source = Pathname.new(source)
+    end
+
+    def glob(glob)
+      Enumerator.new do |y|
+        @source.glob(glob).each do |input|
+          relative = input.relative_path_from(@source)
+          output = relative.dirname.join(relative.basename(input.extname))
+          y << [ input, output ]
+        end
+      end
+    end
+  end
+end

data/sig/hls.rbs

@@ -0,0 +1,4 @@
+module HLS
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,80 @@
+--- !ruby/object:Gem::Specification
+name: hls
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Brad Gessler
+bindir: exe
+cert_chain: []
+date: 2025-07-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bigdecimal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: m3u8
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.8.0
+description: Create sane HLS video with a few commands and serve it up from an S3
+  object store.
+email:
+- bradgessler@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- README.md
+- Rakefile
+- examples/directory.rb
+- lib/hls.rb
+- lib/hls/version.rb
+- sig/hls.rbs
+homepage: https://github.com/beautifulruby/hls
+licenses: []
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/beautifulruby/hls
+  source_code_uri: https://github.com/beautifulruby/hls
+  changelog_uri: https://github.com/beautifulruby/hls
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: Create sane HLS video with a few commands and serve it up from an S3 object
+  store.
+test_files: []