ruby-ffmpeg 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 0c5608dc7cc071bd2df362e31ed56e9a71994ac7ad0ffcd1e3f5cc160d2cb39c
+  data.tar.gz: 29adefaaca271fde91c4c2c58fb49c3c7b234b31a25667862d7f78475e5471cb
+SHA512:
+  metadata.gz: a9461b5c17c61c53feb3619b60fa8d17e76851afa2f22e2f8b752d8db4e2a703fc8173ae825414e5bd0a5b63b7d62e658894075f3a67fb6cb708e188e3ff9c57
+  data.tar.gz: 0d6b09652b3b8d5f62b112092377ece5ebce22a7c50104053dcb802eade131faec9b062028f3bb7027e6f186624de99192aae7ea0fd1a7dc4f26470e21f35c89

data/README.md

@@ -0,0 +1,336 @@
+# ruby-ffmpeg
+
+A modern Ruby wrapper for FFmpeg with zero dependencies. Provides clean APIs for metadata extraction, transcoding, scene detection, and keyframe extraction.
+
+[![Gem Version](https://badge.fury.io/rb/ruby-ffmpeg.svg)](https://badge.fury.io/rb/ruby-ffmpeg)
+[![Ruby](https://github.com/activeagents/ruby-ffmpeg/actions/workflows/main.yml/badge.svg)](https://github.com/activeagents/ruby-ffmpeg/actions/workflows/main.yml)
+
+## Features
+
+- **Zero Dependencies** - Pure Ruby, no gem dependencies
+- **Modern Ruby** - Requires Ruby 3.1+, uses Data classes and modern patterns
+- **FFmpeg 4-7 Support** - Tested against FFmpeg versions 4, 5, 6, and 7
+- **Scene Detection** - Detect scene changes for video analysis
+- **Keyframe Extraction** - Extract frames at intervals, timestamps, or I-frames
+- **Progress Reporting** - Real-time transcoding progress callbacks
+- **Rails Integration** - Active Storage analyzer and previewer included
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem 'ruby-ffmpeg'
+```
+
+Or install directly:
+
+```bash
+gem install ruby-ffmpeg
+```
+
+**Note:** FFmpeg must be installed on your system. Install with:
+- macOS: `brew install ffmpeg`
+- Ubuntu: `sudo apt install ffmpeg`
+- Windows: `choco install ffmpeg`
+
+## Quick Start
+
+```ruby
+require 'ffmpeg'
+
+# Load a video
+media = FFMPEG::Media.new("/path/to/video.mp4")
+
+# Get metadata
+media.duration      # => 120.5
+media.resolution    # => "1920x1080"
+media.video_codec   # => "h264"
+media.audio_codec   # => "aac"
+media.frame_rate    # => 29.97
+media.bit_rate      # => 5000000
+
+# Check properties
+media.valid?        # => true
+media.video?        # => true
+media.audio?        # => true
+media.hd?           # => true
+media.portrait?     # => false
+```
+
+## Transcoding
+
+```ruby
+# Basic transcoding
+media.transcode("/output.mp4")
+
+# With options
+media.transcode("/output.webm",
+  video_codec: "libvpx-vp9",
+  audio_codec: "libopus",
+  resolution: "1280x720",
+  video_bitrate: "2M"
+)
+
+# With progress callback
+media.transcode("/output.mp4") do |progress|
+  puts "Progress: #{progress.round(1)}%"
+end
+
+# Copy streams (no re-encoding)
+media.transcode("/output.mp4",
+  copy_video: true,
+  copy_audio: true
+)
+
+# Trim video
+media.transcode("/clip.mp4",
+  seek: 30,      # Start at 30 seconds
+  duration: 10   # 10 second clip
+)
+```
+
+## Scene Detection
+
+Detect scene changes for video analysis, chapter generation, or highlight extraction:
+
+```ruby
+# Detect scenes with default threshold
+scenes = media.detect_scenes
+# => [
+#   { timestamp: 0.0, score: 1.0 },
+#   { timestamp: 5.23, score: 0.45 },
+#   { timestamp: 12.8, score: 0.38 }
+# ]
+
+# Custom threshold (lower = more sensitive)
+scenes = media.detect_scenes(threshold: 0.2)
+
+# Using SceneDetector directly for more options
+detector = FFMPEG::SceneDetector.new(media)
+scenes = detector.detect(
+  threshold: 0.3,
+  min_scene_length: 2.0,  # Minimum 2 seconds between scenes
+  max_scenes: 20          # Maximum 20 scenes
+)
+
+# Detect scenes and extract keyframes
+scenes = detector.detect_with_keyframes(
+  threshold: 0.3,
+  output_dir: "/tmp/scenes"
+)
+# Each scene now has :keyframe_path
+```
+
+## Keyframe Extraction
+
+Extract frames for thumbnails, video analysis, or sprite sheets:
+
+```ruby
+# Extract at regular intervals
+frames = media.extract_keyframes(
+  output_dir: "/tmp/frames",
+  interval: 5.0  # Every 5 seconds
+)
+# => ["/tmp/frames/frame_0000.jpg", "/tmp/frames/frame_0005.jpg", ...]
+
+# Extract specific number of frames
+frames = media.extract_keyframes(
+  output_dir: "/tmp/frames",
+  count: 10  # 10 evenly-distributed frames
+)
+
+# Extract at specific timestamps
+frames = media.extract_keyframes(
+  output_dir: "/tmp/frames",
+  timestamps: [0, 30, 60, 90, 120]
+)
+
+# Using KeyframeExtractor directly for more options
+extractor = FFMPEG::KeyframeExtractor.new(media)
+
+# Extract actual I-frames (keyframes) from video
+iframes = extractor.extract_iframes(
+  output_dir: "/tmp/iframes",
+  max_frames: 50
+)
+
+# Create a thumbnail sprite sheet (for video scrubbing)
+sprite = extractor.create_sprite(
+  columns: 10,
+  rows: 10,
+  width: 160,
+  output_path: "/tmp/sprite.jpg"
+)
+# => { path: "/tmp/sprite.jpg", columns: 10, rows: 10, ... }
+```
+
+## Stream Information
+
+Access detailed stream information:
+
+```ruby
+# Video stream
+video = media.video
+video.codec         # => "h264"
+video.width         # => 1920
+video.height        # => 1080
+video.frame_rate    # => 29.97
+video.bit_rate      # => 4500000
+video.pixel_format  # => "yuv420p"
+video.rotation      # => 0
+
+# Audio stream
+audio = media.audio
+audio.codec         # => "aac"
+audio.sample_rate   # => 48000
+audio.channels      # => 2
+audio.channel_layout # => "stereo"
+
+# All streams
+media.streams.each do |stream|
+  puts stream.to_s
+end
+```
+
+## Configuration
+
+```ruby
+FFMPEG.configure do |config|
+  # Custom binary paths
+  config.ffmpeg_binary = "/usr/local/bin/ffmpeg"
+  config.ffprobe_binary = "/usr/local/bin/ffprobe"
+
+  # Default timeout (seconds)
+  config.timeout = 600
+
+  # Enable logging
+  config.logger = Logger.new(STDOUT)
+
+  # Default codecs
+  config.default_video_codec = "libx264"
+  config.default_audio_codec = "aac"
+
+  # Number of threads (0 = auto)
+  config.threads = 0
+
+  # Temporary directory
+  config.temp_dir = "/tmp/ffmpeg"
+
+  # Overwrite existing files
+  config.overwrite_output = true
+end
+```
+
+## Rails Integration
+
+### Active Storage Analyzer
+
+Automatically extract video metadata for Active Storage:
+
+```ruby
+# config/initializers/active_storage.rb
+Rails.application.config.active_storage.analyzers.prepend(
+  FFMPEG::ActiveStorage::Analyzer
+)
+```
+
+Now video blobs will have metadata like:
+```ruby
+video.metadata
+# => { width: 1920, height: 1080, duration: 120.5, video_codec: "h264", ... }
+```
+
+### Active Storage Previewer
+
+Generate video previews:
+
+```ruby
+# config/initializers/active_storage.rb
+Rails.application.config.active_storage.previewers.prepend(
+  FFMPEG::ActiveStorage::Previewer
+)
+```
+
+### Rake Tasks
+
+```bash
+# Check FFmpeg installation
+rake ffmpeg:check
+
+# Analyze a video
+rake ffmpeg:analyze[/path/to/video.mp4]
+
+# Extract keyframes
+rake ffmpeg:keyframes[/path/to/video.mp4,output_dir,5]
+
+# Detect scenes
+rake ffmpeg:scenes[/path/to/video.mp4,0.3]
+```
+
+## Error Handling
+
+```ruby
+begin
+  media = FFMPEG::Media.new("/path/to/video.mp4")
+  media.transcode("/output.mp4")
+rescue FFMPEG::MediaNotFound => e
+  puts "File not found: #{e.message}"
+rescue FFMPEG::InvalidMedia => e
+  puts "Invalid media: #{e.message}"
+rescue FFMPEG::TranscodingError => e
+  puts "Transcoding failed: #{e.message}"
+  puts "Command: #{e.command}"
+  puts "Output: #{e.output}"
+rescue FFMPEG::CommandTimeout => e
+  puts "Command timed out: #{e.message}"
+end
+```
+
+## Comparison with streamio-ffmpeg
+
+| Feature | ruby-ffmpeg | streamio-ffmpeg |
+|---------|-------------|-----------------|
+| Ruby Version | 3.1+ | 2.0+ |
+| FFmpeg Version | 4-7 | 2.8.4 |
+| Dependencies | None | None |
+| Scene Detection | Built-in | No |
+| Keyframe Extraction | Built-in | No |
+| Active Storage | Built-in | No |
+| Progress Callbacks | Yes | Yes |
+| Last Updated | 2026 | 2016 |
+
+## Development
+
+```bash
+# Clone the repo
+git clone https://github.com/activeagents/ruby-ffmpeg.git
+cd ruby-ffmpeg
+
+# Install dependencies
+bin/setup
+
+# Run tests
+rake test
+
+# Run linter
+rake rubocop
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b feature/my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin feature/my-new-feature`)
+5. Create a new Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Credits
+
+Developed and maintained by [Active Agents](https://activeagents.ai).
+
+Inspired by [streamio-ffmpeg](https://github.com/streamio/streamio-ffmpeg) and [instructure/ruby-ffmpeg](https://github.com/instructure/ruby-ffmpeg).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[test rubocop]

data/lib/ffmpeg/active_storage/analyzer.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module FFMPEG
+  module ActiveStorage
+    # Active Storage Analyzer for video files using FFMPEG
+    #
+    # This analyzer extracts video metadata that Active Storage can use
+    # for displaying video information and generating previews.
+    #
+    # @example Add to Active Storage analyzers
+    #   # config/initializers/active_storage.rb
+    #   Rails.application.config.active_storage.analyzers.prepend(
+    #     FFMPEG::ActiveStorage::Analyzer
+    #   )
+    #
+    class Analyzer < ::ActiveStorage::Analyzer
+      class << self
+        # Check if this analyzer can process the blob
+        # @param blob [ActiveStorage::Blob]
+        # @return [Boolean]
+        def accept?(blob)
+          blob.video?
+        end
+      end
+
+      # Analyze the video and return metadata
+      # @return [Hash] video metadata
+      def metadata
+        download_blob_to_tempfile do |file|
+          media = FFMPEG::Media.new(file.path)
+
+          {
+            width: media.width,
+            height: media.height,
+            duration: media.duration,
+            angle: media.rotation,
+            display_aspect_ratio: calculate_display_aspect_ratio(media),
+            audio: media.audio?,
+            video: media.video?,
+            video_codec: media.video_codec,
+            audio_codec: media.audio_codec,
+            frame_rate: media.frame_rate,
+            bit_rate: media.bit_rate
+          }.compact
+        end
+      rescue FFMPEG::Error => e
+        Rails.logger.error "[FFMPEG] Analysis failed: #{e.message}" if defined?(Rails)
+        {}
+      end
+
+      private
+
+      def calculate_display_aspect_ratio(media)
+        return nil unless media.width && media.height && media.height.positive?
+
+        ratio = media.width.to_f / media.height
+
+        # Common aspect ratios
+        common_ratios = {
+          [16, 9] => 1.778,
+          [4, 3] => 1.333,
+          [21, 9] => 2.333,
+          [1, 1] => 1.0,
+          [9, 16] => 0.5625,
+          [3, 4] => 0.75
+        }
+
+        # Find closest common ratio
+        closest = common_ratios.min_by { |_, r| (r - ratio).abs }
+
+        if (closest[1] - ratio).abs < 0.05
+          closest[0].join(":")
+        else
+          "#{media.width}:#{media.height}"
+        end
+      end
+    end
+  end
+end

data/lib/ffmpeg/active_storage/previewer.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module FFMPEG
+  module ActiveStorage
+    # Active Storage Previewer for video files using FFMPEG
+    #
+    # Generates video preview images (thumbnails) for Active Storage.
+    #
+    # @example Add to Active Storage previewers
+    #   # config/initializers/active_storage.rb
+    #   Rails.application.config.active_storage.previewers.prepend(
+    #     FFMPEG::ActiveStorage::Previewer
+    #   )
+    #
+    class Previewer < ::ActiveStorage::Previewer
+      class << self
+        # Check if this previewer can process the blob
+        # @param blob [ActiveStorage::Blob]
+        # @return [Boolean]
+        def accept?(blob)
+          blob.video?
+        end
+      end
+
+      # Generate a preview image
+      # @yield [io, options] the generated preview image
+      def preview(**options)
+        download_blob_to_tempfile do |input|
+          media = FFMPEG::Media.new(input.path)
+
+          # Extract frame at 10% into the video (avoid black frames at start)
+          timestamp = (media.duration || 10) * 0.1
+
+          draw_frame(media, timestamp) do |output|
+            yield io: output, filename: "#{blob.filename.base}.jpg",
+                  content_type: "image/jpeg"
+          end
+        end
+      end
+
+      private
+
+      def draw_frame(media, timestamp)
+        Dir.mktmpdir("ffmpeg_preview") do |dir|
+          output_path = File.join(dir, "preview.jpg")
+
+          extractor = FFMPEG::KeyframeExtractor.new(media)
+          extractor.extract_at_timestamps(
+            [timestamp],
+            output_dir: dir,
+            format: "jpg",
+            quality: 2
+          )
+
+          # Find the generated file
+          frame_path = Dir.glob(File.join(dir, "frame_*.jpg")).first
+
+          if frame_path && File.exist?(frame_path)
+            yield File.open(frame_path, "rb")
+          else
+            raise FFMPEG::KeyframeExtractionError, "Failed to generate preview"
+          end
+        end
+      end
+    end
+  end
+end