helios-videos 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 29b809949f048f47c75bea77d368ef5c74e106abcd02ef2255e4552cba30bcdb
+  data.tar.gz: 4bd1f685e4e2b80772edc90e5e9ff4a64f1c17e4aa28cad0936540bfd3be7d27
+SHA512:
+  metadata.gz: aa5eff29b5557d5403002db4aaf971eb4d8181b4283346f07944daaa5bfefb42d9c6f7e8095949a726829c4093979b61ed431bdb977144d5f74cdba4519bae7b
+  data.tar.gz: d6ca7b0c69d316b7e71356830832561e602dab3622161453a86a38bfd878fdf80d6e0dd9380a9607209b17e0c179927b35ca4d5e81e333a9426d2465ad9755ba

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright TODO: Write your name
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,84 @@
+# Helios::Videos
+
+Video upload, processing, and streaming for Rails. Upload videos via ActiveStorage direct upload to S3, ingest into Mux or Cloudflare Stream for processing, and serve streaming video.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "helios-videos"
+```
+
+Then:
+
+```bash
+bundle install
+bin/rails helios_videos:install:migrations
+bin/rails db:migrate
+```
+
+**Prerequisites:** Your host app must have ActiveStorage installed (`bin/rails active_storage:install`).
+
+## Configuration
+
+Create `config/initializers/helios_videos.rb`:
+
+```ruby
+Helios::Videos.configure do |config|
+  # Choose your video processor
+  config.processor = :cloudflare  # or :mux
+
+  # Cloudflare Stream settings
+  config.cloudflare_account_id = ENV["CLOUDFLARE_ACCOUNT_ID"]
+  config.cloudflare_api_token  = ENV["CLOUDFLARE_API_TOKEN"]
+  config.require_signed_urls   = true
+
+  # OR Mux settings
+  # config.processor       = :mux
+  # config.mux_token_id    = ENV["MUX_TOKEN_ID"]
+  # config.mux_token_secret = ENV["MUX_TOKEN_SECRET"]
+end
+```
+
+## Routes
+
+Mount the engine:
+
+```ruby
+mount Helios::Videos::Engine, at: "/helios_videos"
+```
+
+## Usage
+
+### Creating a video
+
+```ruby
+video = Helios::Videos::Video.new(name: "My Video")
+video.video_file.attach(params[:video_file])
+video.save!
+# CheckVideoJob will automatically ingest the video into your configured processor
+```
+
+### Displaying a video
+
+```erb
+<%= video.player_component %>
+```
+
+### With helios-press
+
+When both gems are loaded, video blocks are automatically available in the block editor. Videos can be dragged into block placeholders for direct upload and processing.
+
+## JavaScript
+
+Register the Stimulus controllers in your host app:
+
+```javascript
+import { HeliosVideoBlockController } from "helios-videos"
+application.register("video-block", HeliosVideoBlockController)
+```
+
+## License
+
+Proprietary. All rights reserved.

data/Rakefile

@@ -0,0 +1,3 @@
+require "bundler/setup"
+
+require "bundler/gem_tasks"

data/app/assets/stylesheets/helios/videos/application.css

@@ -0,0 +1,15 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or any plugin's vendor/assets/stylesheets directory can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the bottom of the
+ * compiled file so the styles you add here take precedence over styles defined in any other CSS/SCSS
+ * files in this directory. Styles in this file should be added after the last require_* statement.
+ * It is generally better to create a new file per style scope.
+ *
+ *= require_tree .
+ *= require_self
+ */

data/app/controllers/helios/videos/admin/base_controller.rb

@@ -0,0 +1,8 @@
+module Helios
+  module Videos
+    module Admin
+      class BaseController < ::ApplicationController
+      end
+    end
+  end
+end

data/app/controllers/helios/videos/admin/videos_controller.rb

@@ -0,0 +1,27 @@
+module Helios
+  module Videos
+    module Admin
+      class VideosController < Helios::Videos::Admin::BaseController
+        before_action :set_video
+
+        def update
+          if @video.update(video_params)
+            head :ok
+          else
+            head :unprocessable_entity
+          end
+        end
+
+        private
+
+        def set_video
+          @video = Video.find(params[:id])
+        end
+
+        def video_params
+          params.require(:video).permit(:name)
+        end
+      end
+    end
+  end
+end

data/app/controllers/helios/videos/application_controller.rb

@@ -0,0 +1,6 @@
+module Helios
+  module Videos
+    class ApplicationController < ActionController::Base
+    end
+  end
+end

data/app/helpers/helios/videos/application_helper.rb

@@ -0,0 +1,6 @@
+module Helios
+  module Videos
+    module ApplicationHelper
+    end
+  end
+end

data/app/javascript/helios/videos/controllers/video_block_controller.js

@@ -0,0 +1,47 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Manages inline name editing for video blocks
+export default class extends Controller {
+  static values = {
+    videoId: Number
+  }
+
+  editName(event) {
+    const viewName = event.currentTarget
+    const editName = viewName.nextElementSibling
+
+    viewName.classList.add('d-none')
+    editName.classList.remove('d-none')
+    editName.querySelector('input').focus()
+  }
+
+  saveName(event) {
+    const input = event.currentTarget
+    const name = input.value
+
+    fetch(`/helios_videos/admin/videos/${this.videoIdValue}`, {
+      method: 'PATCH',
+      headers: {
+        'Content-Type': 'application/json',
+        'X-CSRF-Token': document.querySelector('[name="csrf-token"]').content
+      },
+      body: JSON.stringify({ video: { name: name } })
+    })
+    .then(() => {
+      const editName = input.closest('.name-edit')
+      const viewName = editName.previousElementSibling
+
+      viewName.textContent = name || 'Click to add name...'
+      viewName.classList.remove('d-none')
+      editName.classList.add('d-none')
+    })
+  }
+
+  cancelName(event) {
+    const editName = event.currentTarget.closest('.name-edit')
+    const viewName = editName.previousElementSibling
+
+    viewName.classList.remove('d-none')
+    editName.classList.add('d-none')
+  }
+}

data/app/javascript/helios/videos/index.js

@@ -0,0 +1,4 @@
+// Helios Videos - Stimulus Controllers
+// Import these in your host app's application.js or controllers/index.js
+
+export { default as HeliosVideoBlockController } from "./controllers/video_block_controller"

data/app/jobs/helios/videos/application_job.rb

@@ -0,0 +1,6 @@
+module Helios
+  module Videos
+    class ApplicationJob < ActiveJob::Base
+    end
+  end
+end

data/app/jobs/helios/videos/check_video_job.rb

@@ -0,0 +1,32 @@
+module Helios
+  module Videos
+    class CheckVideoJob < ApplicationJob
+      queue_as :default
+
+      def perform(video:, attempt_thumbnail: false)
+        if video.key.present?
+          Rails.logger.debug("[helios-videos] Video #{video.id} already ingested (key: #{video.key})")
+
+          if attempt_thumbnail && !video.thumbnail_image.attached?
+            success = video.download_and_store_thumbnail!
+            unless success
+              CheckVideoJob.set(wait: 30.seconds).perform_later(video: video, attempt_thumbnail: true)
+            end
+          end
+          return
+        end
+
+        if video.video_file.attached?
+          Rails.logger.debug("[helios-videos] Video #{video.id} file attached, starting ingestion...")
+          video.check_for_processing!
+
+          # Schedule thumbnail download after processing
+          CheckVideoJob.set(wait: 10.seconds).perform_later(video: video, attempt_thumbnail: true)
+        else
+          Rails.logger.debug("[helios-videos] Video #{video.id} file not attached, retrying in 5s...")
+          CheckVideoJob.set(wait: 5.seconds).perform_later(video: video, attempt_thumbnail: attempt_thumbnail)
+        end
+      end
+    end
+  end
+end

data/app/mailers/helios/videos/application_mailer.rb

@@ -0,0 +1,8 @@
+module Helios
+  module Videos
+    class ApplicationMailer < ActionMailer::Base
+      default from: "from@example.com"
+      layout "mailer"
+    end
+  end
+end

data/app/models/helios/videos/application_record.rb

@@ -0,0 +1,7 @@
+module Helios
+  module Videos
+    class ApplicationRecord < ActiveRecord::Base
+      self.abstract_class = true
+    end
+  end
+end

data/app/models/helios/videos/video.rb

@@ -0,0 +1,59 @@
+module Helios
+  module Videos
+    class Video < ActiveRecord::Base
+      self.table_name = "helios_videos_videos"
+
+      # Optional association to helios-press block (when both gems are loaded)
+      if defined?(Helios::Press::Block)
+        belongs_to :block, class_name: "Helios::Press::Block", optional: true
+      end
+
+      has_one_attached :video_file
+      has_one_attached :thumbnail_image
+
+      after_create :enqueue_check_for_video
+      before_destroy :delete_from_service
+
+      def player_component(muted: false, expiration: 4.hours)
+        Helios::Videos.processor.player_component(self, muted: muted, expiration: expiration)
+      end
+
+      def playback_url(signed: false, expiration: 4.hours)
+        Helios::Videos.processor.playback_url(self, signed: signed, expiration: expiration)
+      end
+
+      def signed_url(expiration: 4.hours)
+        playback_url(signed: true, expiration: expiration)
+      end
+
+      def download_and_store_thumbnail!(time: "3s")
+        Helios::Videos.processor.download_thumbnail!(self, time: time)
+      end
+
+      def thumbnail_url(time: "4s")
+        thumbnail_image.attached? ? thumbnail_image : nil
+      end
+
+      def requires_signed_urls?
+        respond_to?(:requires_signed_urls) ? requires_signed_urls : false
+      end
+
+      def check_for_processing!
+        Helios::Videos.processor.ingest!(self)
+      end
+
+      private
+
+      def enqueue_check_for_video
+        CheckVideoJob.perform_later(video: self)
+      end
+
+      def delete_from_service
+        Helios::Videos.processor.delete!(self)
+      rescue => e
+        Rails.logger.warn("[helios-videos] Failed to delete video #{id} from service: #{e.message}")
+        true # Don't block destroy
+      end
+    end
+  end
+end

data/app/views/layouts/helios/videos/application.html.erb

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <title>Helios videos</title>
+  <%= csrf_meta_tags %>
+  <%= csp_meta_tag %>
+
+  <%= yield :head %>
+
+  <%= stylesheet_link_tag    "helios/videos/application", media: "all" %>
+</head>
+<body>
+
+<%= yield %>
+
+</body>
+</html>

data/config/routes.rb

@@ -0,0 +1,5 @@
+Helios::Videos::Engine.routes.draw do
+  namespace :admin do
+    resources :videos, only: [:update]
+  end
+end

data/db/migrate/20250510000001_create_helios_videos_videos.rb

@@ -0,0 +1,16 @@
+class CreateHeliosVideosVideos < ActiveRecord::Migration[8.0]
+  def change
+    create_table :helios_videos_videos do |t|
+      t.string :name
+      t.string :key
+      t.jsonb :playback_urls
+      t.boolean :requires_signed_urls, default: false, null: false
+      t.integer :block_id
+
+      t.timestamps
+    end
+
+    add_index :helios_videos_videos, :block_id
+    add_index :helios_videos_videos, :key, unique: true
+  end
+end

data/lib/helios/videos/configuration.rb

@@ -0,0 +1,27 @@
+module Helios
+  module Videos
+    class Configuration
+      attr_accessor :processor,
+                    :require_signed_urls,
+                    :admin_parent_controller,
+                    # Cloudflare
+                    :cloudflare_account_id,
+                    :cloudflare_api_token,
+                    :cloudflare_customer_subdomain,
+                    # Mux
+                    :mux_token_id,
+                    :mux_token_secret
+
+      def initialize
+        @processor = :cloudflare
+        @require_signed_urls = true
+        @admin_parent_controller = "ApplicationController"
+        @cloudflare_account_id = ENV["CLOUDFLARE_ACCOUNT_ID"]
+        @cloudflare_api_token = ENV["CLOUDFLARE_API_TOKEN"]
+        @cloudflare_customer_subdomain = ENV["CLOUDFLARE_CUSTOMER_SUBDOMAIN"]
+        @mux_token_id = ENV["MUX_TOKEN_ID"]
+        @mux_token_secret = ENV["MUX_TOKEN_SECRET"]
+      end
+    end
+  end
+end

data/lib/helios/videos/engine.rb

@@ -0,0 +1,18 @@
+module Helios
+  module Videos
+    class Engine < ::Rails::Engine
+      isolate_namespace Helios::Videos
+
+      # When helios-press is also loaded, mix video support into Block
+      initializer "helios_videos.integrate_with_press" do
+        ActiveSupport.on_load(:active_record) do
+          if defined?(Helios::Press::Block)
+            Helios::Press::Block.class_eval do
+              has_one :video, class_name: "Helios::Videos::Video", foreign_key: :block_id, dependent: :destroy
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/helios/videos/processor.rb

@@ -0,0 +1,42 @@
+module Helios
+  module Videos
+    class Processor
+      attr_reader :config
+
+      def initialize(config)
+        @config = config
+      end
+
+      # Ingest a video from its ActiveStorage URL into the video service.
+      # Should set video.key and video.playback_urls on success.
+      def ingest!(video)
+        raise NotImplementedError, "#{self.class}#ingest! must be implemented"
+      end
+
+      # Delete a video from the video service.
+      def delete!(video)
+        raise NotImplementedError, "#{self.class}#delete! must be implemented"
+      end
+
+      # Return the playback URL for a video.
+      def playback_url(video, signed: false, expiration: 4.hours)
+        raise NotImplementedError, "#{self.class}#playback_url must be implemented"
+      end
+
+      # Return an HTML player component for the video.
+      def player_component(video, muted: false, expiration: 4.hours)
+        raise NotImplementedError, "#{self.class}#player_component must be implemented"
+      end
+
+      # Generate a signed token for the video (if supported).
+      def signed_token(video, expiration: 4.hours)
+        raise NotImplementedError, "#{self.class}#signed_token must be implemented"
+      end
+
+      # Download and store the video thumbnail.
+      def download_thumbnail!(video, time: "3s")
+        raise NotImplementedError, "#{self.class}#download_thumbnail! must be implemented"
+      end
+    end
+  end
+end

data/lib/helios/videos/processors/cloudflare.rb

@@ -0,0 +1,213 @@
+require "net/http"
+require "json"
+require "jwt"
+
+module Helios
+  module Videos
+    module Processors
+      class Cloudflare < Processor
+        SIGNING_KEY_CACHE_KEY = "helios_videos_cf_signing_key"
+        SIGNING_KEY_ID_CACHE_KEY = "helios_videos_cf_signing_key_id"
+
+        def ingest!(video)
+          return if video.key.present?
+          return unless video.video_file.attached?
+
+          uri = URI("https://api.cloudflare.com/client/v4/accounts/#{account_id}/stream/copy")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+
+          request = Net::HTTP::Post.new(uri.request_uri, {
+            "Authorization" => "Bearer #{api_token}",
+            "Content-Type" => "application/json"
+          })
+
+          request.body = {
+            url: video.video_file.url,
+            meta: { name: video.name },
+            requireSignedURLs: config.require_signed_urls
+          }.to_json
+
+          response = http.request(request)
+          body = JSON.parse(response.body)
+
+          unless response.is_a?(Net::HTTPSuccess)
+            Rails.logger.error("[helios-videos] Cloudflare ingest error: #{response.code} - #{response.body}")
+            raise "Cloudflare ingest failed: #{response.code}"
+          end
+
+          video.update!(
+            key: body["result"]["uid"],
+            playback_urls: body["result"]["playback"],
+            requires_signed_urls: config.require_signed_urls
+          )
+
+          Rails.logger.info("[helios-videos] Video #{video.id} ingested into Cloudflare: #{video.key}")
+        end
+
+        def delete!(video)
+          return unless video.key.present?
+
+          uri = URI("https://api.cloudflare.com/client/v4/accounts/#{account_id}/stream/#{video.key}")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+
+          request = Net::HTTP::Delete.new(uri.request_uri, {
+            "Authorization" => "Bearer #{api_token}",
+            "Content-Type" => "application/json"
+          })
+
+          response = http.request(request)
+
+          if response.is_a?(Net::HTTPSuccess)
+            Rails.logger.info("[helios-videos] Cloudflare video #{video.key} deleted")
+          else
+            Rails.logger.warn("[helios-videos] Failed to delete Cloudflare video #{video.key}: #{response.code}")
+          end
+        end
+
+        def playback_url(video, signed: false, expiration: 4.hours)
+          return nil unless video.key.present?
+
+          if signed || video.requires_signed_urls?
+            token = signed_token(video, expiration: expiration)
+            subdomain = customer_subdomain(video)
+            "https://#{subdomain}.cloudflarestream.com/#{token}/manifest/video.m3u8"
+          else
+            video.playback_urls&.dig("hls")
+          end
+        end
+
+        def player_component(video, muted: false, expiration: 4.hours)
+          return "(VIDEO NOT AVAILABLE)" unless video.key.present?
+
+          video_src = playback_url(video, signed: video.requires_signed_urls?, expiration: expiration)
+
+          <<~HTML.html_safe
+            <video
+              id="videojs-#{video.key}"
+              class="video-js vjs-default-skin"
+              style="width: 100%; height: 100%;"
+              controls
+              preload="auto"
+              data-setup='{}'
+              #{"muted" if muted}
+            >
+              <source src="#{video_src}" type="application/x-mpegURL" />
+              Your browser does not support HLS video.
+            </video>
+          HTML
+        end
+
+        def signed_token(video, expiration: 4.hours)
+          key_id, private_key = fetch_signing_key
+
+          now = Time.now.to_i
+          payload = {
+            sub: video.key,
+            kid: key_id,
+            exp: now + expiration.to_i,
+            nbf: now - 60
+          }
+
+          JWT.encode(payload, private_key, "RS256", typ: "JWT", kid: key_id)
+        end
+
+        def download_thumbnail!(video, time: "3s")
+          return false unless video.key.present?
+          return true if video.thumbnail_image.attached?
+
+          subdomain = customer_subdomain(video)
+          return false unless subdomain.present?
+
+          if video.requires_signed_urls?
+            token = signed_token(video, expiration: 1.hour)
+            base_url = "https://#{subdomain}.cloudflarestream.com/#{token}/thumbnails/thumbnail.jpg"
+          else
+            base_url = "https://#{subdomain}.cloudflarestream.com/#{video.key}/thumbnails/thumbnail.jpg"
+          end
+          url = time.present? ? "#{base_url}?time=#{time}" : base_url
+
+          require "open-uri"
+          downloaded_image = URI.open(url)
+          video.thumbnail_image.attach(
+            io: downloaded_image,
+            filename: "video_#{video.id}_thumbnail.jpg",
+            content_type: "image/jpeg"
+          )
+          Rails.logger.info("[helios-videos] Downloaded thumbnail for video #{video.id}")
+          true
+        rescue => e
+          Rails.logger.error("[helios-videos] Failed to download thumbnail for video #{video.id}: #{e.message}")
+          false
+        end
+
+        private
+
+        def account_id
+          config.cloudflare_account_id || raise("CLOUDFLARE_ACCOUNT_ID not configured")
+        end
+
+        def api_token
+          config.cloudflare_api_token || raise("CLOUDFLARE_API_TOKEN not configured")
+        end
+
+        def customer_subdomain(video)
+          config.cloudflare_customer_subdomain || extract_subdomain_from_video(video)
+        end
+
+        def extract_subdomain_from_video(video)
+          return nil unless video.playback_urls.present? && video.playback_urls["hls"].present?
+          uri = URI.parse(video.playback_urls["hls"])
+          uri.host.split(".").first
+        rescue => e
+          Rails.logger.error("[helios-videos] Failed to extract subdomain: #{e.message}")
+          nil
+        end
+
+        def fetch_signing_key
+          cached_key = Rails.cache.read(SIGNING_KEY_CACHE_KEY)
+          cached_key_id = Rails.cache.read(SIGNING_KEY_ID_CACHE_KEY)
+
+          if cached_key.present? && cached_key_id.present?
+            begin
+              return [cached_key_id, OpenSSL::PKey::RSA.new(cached_key)]
+            rescue OpenSSL::PKey::RSAError
+              Rails.cache.delete(SIGNING_KEY_CACHE_KEY)
+              Rails.cache.delete(SIGNING_KEY_ID_CACHE_KEY)
+            end
+          end
+
+          result = create_signing_key
+          key_id = result["id"]
+          pem = Base64.decode64(result["pem"])
+
+          Rails.cache.write(SIGNING_KEY_CACHE_KEY, pem, expires_in: 7.days)
+          Rails.cache.write(SIGNING_KEY_ID_CACHE_KEY, key_id, expires_in: 7.days)
+
+          [key_id, OpenSSL::PKey::RSA.new(pem)]
+        end
+
+        def create_signing_key
+          uri = URI("https://api.cloudflare.com/client/v4/accounts/#{account_id}/stream/keys")
+          http = Net::HTTP.new(uri.host, uri.port)
+          http.use_ssl = true
+
+          request = Net::HTTP::Post.new(uri.request_uri, {
+            "Authorization" => "Bearer #{api_token}",
+            "Content-Type" => "application/json"
+          })
+
+          response = http.request(request)
+          body = JSON.parse(response.body)
+
+          unless response.is_a?(Net::HTTPSuccess)
+            raise "Failed to create Cloudflare signing key: #{response.code} - #{response.body}"
+          end
+
+          body["result"] || raise("Cloudflare API returned no result: #{body.inspect}")
+        end
+      end
+    end
+  end
+end

data/lib/helios/videos/processors/mux.rb

@@ -0,0 +1,109 @@
+module Helios
+  module Videos
+    module Processors
+      class Mux < Processor
+        def ingest!(video)
+          return if video.key.present?
+          return unless video.video_file.attached?
+
+          require "mux_ruby"
+
+          MuxRuby.configure do |c|
+            c.username = config.mux_token_id
+            c.password = config.mux_token_secret
+          end
+
+          assets_api = MuxRuby::AssetsApi.new
+          create_request = MuxRuby::CreateAssetRequest.new(
+            input: video.video_file.url,
+            playback_policy: [MuxRuby::PlaybackPolicy::PUBLIC]
+          )
+
+          response = assets_api.create_asset(create_request)
+          asset = response.data
+
+          video.update!(
+            key: asset.id,
+            playback_urls: { "hls" => "https://stream.mux.com/#{asset.playback_ids&.first&.id}.m3u8" }
+          )
+
+          Rails.logger.info("[helios-videos] Video #{video.id} ingested into Mux: #{video.key}")
+        end
+
+        def delete!(video)
+          return unless video.key.present?
+
+          require "mux_ruby"
+
+          MuxRuby.configure do |c|
+            c.username = config.mux_token_id
+            c.password = config.mux_token_secret
+          end
+
+          assets_api = MuxRuby::AssetsApi.new
+          assets_api.delete_asset(video.key)
+          Rails.logger.info("[helios-videos] Mux asset #{video.key} deleted")
+        rescue MuxRuby::ApiError => e
+          Rails.logger.warn("[helios-videos] Failed to delete Mux asset #{video.key}: #{e.message}")
+        end
+
+        def playback_url(video, signed: false, expiration: 4.hours)
+          return nil unless video.key.present?
+          video.playback_urls&.dig("hls")
+        end
+
+        def player_component(video, muted: false, expiration: 4.hours)
+          return "(VIDEO NOT AVAILABLE)" unless video.key.present?
+
+          playback_id = extract_playback_id(video)
+          return "(VIDEO NOT AVAILABLE)" unless playback_id.present?
+
+          <<~HTML.html_safe
+            <mux-player
+              stream-type="on-demand"
+              playback-id="#{playback_id}"
+              controls
+              #{"muted" if muted}
+              style="width: 100%;"
+            ></mux-player>
+          HTML
+        end
+
+        def signed_token(video, expiration: 4.hours)
+          nil # Mux uses playback IDs, not signed tokens in the same way
+        end
+
+        def download_thumbnail!(video, time: "3s")
+          return false unless video.key.present?
+          return true if video.thumbnail_image.attached?
+
+          playback_id = extract_playback_id(video)
+          return false unless playback_id.present?
+
+          url = "https://image.mux.com/#{playback_id}/thumbnail.jpg?time=#{time.to_i}"
+
+          require "open-uri"
+          downloaded_image = URI.open(url)
+          video.thumbnail_image.attach(
+            io: downloaded_image,
+            filename: "video_#{video.id}_thumbnail.jpg",
+            content_type: "image/jpeg"
+          )
+          true
+        rescue => e
+          Rails.logger.error("[helios-videos] Failed to download Mux thumbnail for video #{video.id}: #{e.message}")
+          false
+        end
+
+        private
+
+        def extract_playback_id(video)
+          hls_url = video.playback_urls&.dig("hls")
+          return nil unless hls_url.present?
+          # Extract from https://stream.mux.com/PLAYBACK_ID.m3u8
+          hls_url.match(%r{stream\.mux\.com/([^.]+)\.m3u8})&.captures&.first
+        end
+      end
+    end
+  end
+end

data/lib/helios/videos/version.rb

@@ -0,0 +1,5 @@
+module Helios
+  module Videos
+    VERSION = "0.1.0"
+  end
+end

data/lib/helios/videos.rb

@@ -0,0 +1,33 @@
+require "helios/videos/version"
+require "helios/videos/engine"
+require "helios/videos/configuration"
+require "helios/videos/processor"
+require "helios/videos/processors/cloudflare"
+require "helios/videos/processors/mux"
+
+module Helios
+  module Videos
+    class << self
+      def configuration
+        @configuration ||= Configuration.new
+      end
+
+      def configure
+        yield(configuration)
+      end
+
+      def processor
+        @processor = nil if @processor_type != configuration.processor
+        @processor_type = configuration.processor
+        @processor ||= case configuration.processor
+        when :cloudflare
+          Processors::Cloudflare.new(configuration)
+        when :mux
+          Processors::Mux.new(configuration)
+        else
+          raise "Unknown video processor: #{configuration.processor}. Use :cloudflare or :mux"
+        end
+      end
+    end
+  end
+end

data/lib/tasks/helios/videos_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :helios_videos do
+#   # Task goes here
+# end

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: helios-videos
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Jason Fleetwood-Boldt
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rails
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '8.0'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+description: Upload videos to S3 via ActiveStorage direct upload, ingest into Mux
+  or Cloudflare Stream for processing, and serve streaming video back to users.
+email:
+- jason@heliosflow.ai
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- MIT-LICENSE
+- README.md
+- Rakefile
+- app/assets/stylesheets/helios/videos/application.css
+- app/controllers/helios/videos/admin/base_controller.rb
+- app/controllers/helios/videos/admin/videos_controller.rb
+- app/controllers/helios/videos/application_controller.rb
+- app/helpers/helios/videos/application_helper.rb
+- app/javascript/helios/videos/controllers/video_block_controller.js
+- app/javascript/helios/videos/index.js
+- app/jobs/helios/videos/application_job.rb
+- app/jobs/helios/videos/check_video_job.rb
+- app/mailers/helios/videos/application_mailer.rb
+- app/models/helios/videos/application_record.rb
+- app/models/helios/videos/video.rb
+- app/views/layouts/helios/videos/application.html.erb
+- config/routes.rb
+- db/migrate/20250510000001_create_helios_videos_videos.rb
+- lib/helios/videos.rb
+- lib/helios/videos/configuration.rb
+- lib/helios/videos/engine.rb
+- lib/helios/videos/processor.rb
+- lib/helios/videos/processors/cloudflare.rb
+- lib/helios/videos/processors/mux.rb
+- lib/helios/videos/version.rb
+- lib/tasks/helios/videos_tasks.rake
+homepage: https://github.com/heliosdev/helios-videos
+licenses:
+- Nonstandard
+metadata:
+  homepage_uri: https://github.com/heliosdev/helios-videos
+  source_code_uri: https://github.com/heliosdev/helios-videos
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Video upload, processing, and streaming for Rails via Mux or Cloudflare Stream
+test_files: []