ruby-ffmpeg 0.1.0

data/lib/ffmpeg/stream.rb

@@ -0,0 +1,229 @@
+# frozen_string_literal: true
+
+module FFMPEG
+  # Represents a media stream (video, audio, subtitle, etc.)
+  #
+  # @example
+  #   stream = media.video_streams.first
+  #   stream.codec           # => "h264"
+  #   stream.width           # => 1920
+  #   stream.height          # => 1080
+  #   stream.frame_rate      # => 29.97
+  #   stream.video?          # => true
+  #
+  class Stream
+    # Stream types
+    VIDEO = "video"
+    AUDIO = "audio"
+    SUBTITLE = "subtitle"
+    DATA = "data"
+    ATTACHMENT = "attachment"
+
+    # @return [Integer] stream index
+    attr_reader :index
+
+    # @return [String] stream type (video, audio, subtitle, data)
+    attr_reader :type
+
+    # @return [String] codec name (h264, aac, etc.)
+    attr_reader :codec
+
+    # @return [String, nil] codec long name
+    attr_reader :codec_long_name
+
+    # @return [String, nil] profile (High, Main, etc.)
+    attr_reader :profile
+
+    # @return [Integer, nil] width (video only)
+    attr_reader :width
+
+    # @return [Integer, nil] height (video only)
+    attr_reader :height
+
+    # @return [Float, nil] frame rate (video only)
+    attr_reader :frame_rate
+
+    # @return [Float, nil] average frame rate (video only)
+    attr_reader :avg_frame_rate
+
+    # @return [Integer, nil] bit rate in bits/sec
+    attr_reader :bit_rate
+
+    # @return [Float, nil] duration in seconds
+    attr_reader :duration
+
+    # @return [Integer, nil] sample rate (audio only)
+    attr_reader :sample_rate
+
+    # @return [Integer, nil] number of audio channels
+    attr_reader :channels
+
+    # @return [String, nil] channel layout (stereo, 5.1, etc.)
+    attr_reader :channel_layout
+
+    # @return [String, nil] pixel format (yuv420p, etc.)
+    attr_reader :pixel_format
+
+    # @return [Integer, nil] rotation in degrees
+    attr_reader :rotation
+
+    # @return [String, nil] language code (eng, spa, etc.)
+    attr_reader :language
+
+    # @return [Boolean] whether this is the default stream
+    attr_reader :default
+
+    # @return [Hash] raw stream data from ffprobe
+    attr_reader :raw
+
+    # Create a new Stream from ffprobe data
+    # @param data [Hash] stream data from ffprobe JSON
+    def initialize(data)
+      @raw = data
+      @index = data["index"]
+      @type = data["codec_type"]
+      @codec = data["codec_name"]
+      @codec_long_name = data["codec_long_name"]
+      @profile = data["profile"]
+      @bit_rate = data["bit_rate"]&.to_i
+      @duration = data["duration"]&.to_f
+
+      parse_video_attributes(data) if video?
+      parse_audio_attributes(data) if audio?
+      parse_tags(data["tags"] || {})
+      parse_disposition(data["disposition"] || {})
+    end
+
+    # @return [Boolean] true if this is a video stream
+    def video?
+      type == VIDEO
+    end
+
+    # @return [Boolean] true if this is an audio stream
+    def audio?
+      type == AUDIO
+    end
+
+    # @return [Boolean] true if this is a subtitle stream
+    def subtitle?
+      type == SUBTITLE
+    end
+
+    # @return [Boolean] true if this is a data stream
+    def data?
+      type == DATA
+    end
+
+    # @return [String, nil] resolution as "WIDTHxHEIGHT"
+    def resolution
+      return nil unless video? && width && height
+
+      "#{width}x#{height}"
+    end
+
+    # @return [Float, nil] aspect ratio
+    def aspect_ratio
+      return nil unless video? && width && height && height.positive?
+
+      width.to_f / height
+    end
+
+    # @return [Boolean] true if video is portrait orientation
+    def portrait?
+      return false unless video? && aspect_ratio
+
+      # Account for rotation
+      effective_ratio = [90, 270].include?(rotation.to_i) ? 1.0 / aspect_ratio : aspect_ratio
+      effective_ratio < 1.0
+    end
+
+    # @return [Boolean] true if video is landscape orientation
+    def landscape?
+      video? && !portrait?
+    end
+
+    # @return [Boolean] true if video is HD (720p or higher)
+    def hd?
+      return false unless video?
+
+      min_dimension = [width, height].compact.min
+      min_dimension && min_dimension >= 720
+    end
+
+    # @return [Boolean] true if video is 4K (2160p or higher)
+    def uhd?
+      return false unless video?
+
+      min_dimension = [width, height].compact.min
+      min_dimension && min_dimension >= 2160
+    end
+
+    # @return [String] human-readable description
+    def to_s
+      parts = ["Stream ##{index}: #{type.capitalize}"]
+      parts << codec if codec
+
+      if video?
+        parts << resolution if resolution
+        parts << "#{frame_rate}fps" if frame_rate
+      end
+
+      if audio?
+        parts << "#{sample_rate}Hz" if sample_rate
+        parts << channel_layout if channel_layout
+      end
+
+      parts.join(", ")
+    end
+
+    private
+
+    def parse_video_attributes(data)
+      @width = data["width"]&.to_i
+      @height = data["height"]&.to_i
+      @pixel_format = data["pix_fmt"]
+
+      # Parse frame rate (can be "30/1" or "30000/1001" format)
+      @frame_rate = parse_frame_rate(data["r_frame_rate"])
+      @avg_frame_rate = parse_frame_rate(data["avg_frame_rate"])
+
+      # Parse rotation from side_data_list
+      @rotation = parse_rotation(data["side_data_list"])
+    end
+
+    def parse_audio_attributes(data)
+      @sample_rate = data["sample_rate"]&.to_i
+      @channels = data["channels"]&.to_i
+      @channel_layout = data["channel_layout"]
+    end
+
+    def parse_tags(tags)
+      @language = tags["language"]
+    end
+
+    def parse_disposition(disposition)
+      @default = disposition["default"] == 1
+    end
+
+    def parse_frame_rate(rate_string)
+      return nil unless rate_string
+
+      # Handle "30/1" or "30000/1001" format
+      if rate_string.include?("/")
+        num, den = rate_string.split("/").map(&:to_f)
+        return nil if den.zero?
+
+        (num / den).round(2)
+      else
+        rate_string.to_f
+      end
+    end
+
+    def parse_rotation(side_data_list)
+      return nil unless side_data_list.is_a?(Array)
+
+      rotation_data = side_data_list.find { |sd| sd["rotation"] }
+      rotation_data&.dig("rotation")&.to_i&.abs
+    end
+  end
+end

data/lib/ffmpeg/tasks/ffmpeg.rake

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+namespace :ffmpeg do
+  desc "Check FFMPEG installation and version"
+  task :check do
+    require "ffmpeg"
+
+    puts "Checking FFMPEG installation..."
+    puts
+
+    if FFMPEG.available?
+      puts "[OK] FFMPEG is installed"
+      puts "     Version: #{FFMPEG.version}"
+      puts "     Binary: #{FFMPEG.ffmpeg_binary}"
+      puts "     FFprobe: #{FFMPEG.ffprobe_binary}"
+    else
+      puts "[ERROR] FFMPEG is not installed or not in PATH"
+      puts
+      puts "Install with:"
+      puts "  macOS:  brew install ffmpeg"
+      puts "  Ubuntu: sudo apt install ffmpeg"
+      puts "  Windows: choco install ffmpeg"
+      exit 1
+    end
+  end
+
+  desc "Analyze a video file"
+  task :analyze, [:path] do |_t, args|
+    require "ffmpeg"
+
+    path = args[:path]
+    unless path
+      puts "Usage: rake ffmpeg:analyze[/path/to/video.mp4]"
+      exit 1
+    end
+
+    begin
+      media = FFMPEG::Media.new(path)
+      puts media.to_h.to_yaml
+    rescue FFMPEG::Error => e
+      puts "Error: #{e.message}"
+      exit 1
+    end
+  end
+
+  desc "Extract keyframes from a video"
+  task :keyframes, [:path, :output_dir, :interval] do |_t, args|
+    require "ffmpeg"
+
+    path = args[:path]
+    output_dir = args[:output_dir] || "./keyframes"
+    interval = (args[:interval] || 5).to_f
+
+    unless path
+      puts "Usage: rake ffmpeg:keyframes[/path/to/video.mp4,output_dir,interval]"
+      exit 1
+    end
+
+    begin
+      media = FFMPEG::Media.new(path)
+      frames = media.extract_keyframes(output_dir: output_dir, interval: interval)
+      puts "Extracted #{frames.count} keyframes to #{output_dir}"
+      frames.each { |f| puts "  #{f}" }
+    rescue FFMPEG::Error => e
+      puts "Error: #{e.message}"
+      exit 1
+    end
+  end
+
+  desc "Detect scenes in a video"
+  task :scenes, [:path, :threshold] do |_t, args|
+    require "ffmpeg"
+
+    path = args[:path]
+    threshold = (args[:threshold] || 0.3).to_f
+
+    unless path
+      puts "Usage: rake ffmpeg:scenes[/path/to/video.mp4,threshold]"
+      exit 1
+    end
+
+    begin
+      media = FFMPEG::Media.new(path)
+      scenes = media.detect_scenes(threshold: threshold)
+      puts "Detected #{scenes.count} scenes:"
+      scenes.each do |scene|
+        puts "  #{format_time(scene[:timestamp])} (score: #{scene[:score]&.round(2)})"
+      end
+    rescue FFMPEG::Error => e
+      puts "Error: #{e.message}"
+      exit 1
+    end
+  end
+
+  def format_time(seconds)
+    return "0:00" unless seconds
+
+    hours = (seconds / 3600).floor
+    minutes = ((seconds % 3600) / 60).floor
+    secs = (seconds % 60).floor
+
+    if hours.positive?
+      format("%d:%02d:%02d", hours, minutes, secs)
+    else
+      format("%d:%02d", minutes, secs)
+    end
+  end
+end

data/lib/ffmpeg/transcoder.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module FFMPEG
+  # Transcodes media files with progress reporting
+  #
+  # @example Basic transcoding
+  #   transcoder = Transcoder.new(media, "/output.mp4")
+  #   transcoder.run do |progress|
+  #     puts "#{progress}% complete"
+  #   end
+  #
+  # @example With options
+  #   transcoder = Transcoder.new(media, "/output.webm",
+  #     video_codec: "libvpx-vp9",
+  #     audio_codec: "libopus",
+  #     video_bitrate: "2M"
+  #   )
+  #   result = transcoder.run
+  #
+  class Transcoder
+    # @return [Media] source media
+    attr_reader :media
+
+    # @return [String] output path
+    attr_reader :output_path
+
+    # @return [Hash] transcoding options
+    attr_reader :options
+
+    # Create a new Transcoder
+    # @param media [Media] source media
+    # @param output_path [String] output file path
+    # @param options [Hash] transcoding options
+    # @option options [String] :video_codec video codec (default: libx264)
+    # @option options [String] :audio_codec audio codec (default: aac)
+    # @option options [String] :resolution output resolution (e.g., "1280x720")
+    # @option options [String, Float] :frame_rate output frame rate
+    # @option options [String] :video_bitrate video bitrate (e.g., "2M")
+    # @option options [String] :audio_bitrate audio bitrate (e.g., "128k")
+    # @option options [Float] :seek start time in seconds
+    # @option options [Float] :duration duration in seconds
+    # @option options [Boolean] :copy_video copy video without re-encoding
+    # @option options [Boolean] :copy_audio copy audio without re-encoding
+    # @option options [Boolean] :no_audio strip audio
+    # @option options [Array<String>] :video_filters video filter chain
+    # @option options [Array<String>] :audio_filters audio filter chain
+    # @option options [String] :format output format
+    # @option options [Array<String>] :custom custom FFmpeg arguments
+    # @option options [Integer] :threads number of threads
+    def initialize(media, output_path, **options)
+      @media = media
+      @output_path = File.expand_path(output_path)
+      @options = default_options.merge(options)
+    end
+
+    # Run the transcoding
+    # @yield [Float] progress percentage (0-100)
+    # @return [Media] the output media
+    # @raise [TranscodingError] if transcoding fails
+    def run(&block)
+      ensure_output_directory!
+
+      cmd = build_command
+      total_duration = calculate_duration
+
+      Command.run!(*cmd) do |line|
+        if block_given? && total_duration&.positive?
+          progress = parse_progress(line, total_duration)
+          yield progress if progress
+        end
+      end
+
+      yield 100.0 if block_given?
+
+      Media.new(output_path)
+    end
+
+    # Get the FFmpeg command that will be executed
+    # @return [Array<String>]
+    def command
+      build_command
+    end
+
+    # Preview the command as a string
+    # @return [String]
+    def command_preview
+      build_command.join(" ")
+    end
+
+    private
+
+    def default_options
+      config = FFMPEG.configuration
+      {
+        video_codec: config.default_video_codec,
+        audio_codec: config.default_audio_codec,
+        threads: config.threads
+      }
+    end
+
+    def build_command
+      Command.build_ffmpeg_command(
+        input: media.path,
+        output: output_path,
+        **options
+      )
+    end
+
+    def ensure_output_directory!
+      dir = File.dirname(output_path)
+      FileUtils.mkdir_p(dir) unless File.directory?(dir)
+    end
+
+    def calculate_duration
+      if options[:duration]
+        options[:duration].to_f
+      elsif options[:seek] && media.duration
+        media.duration - options[:seek].to_f
+      else
+        media.duration
+      end
+    end
+
+    def parse_progress(line, total_duration)
+      # FFmpeg outputs progress to stderr in format:
+      # frame=  123 fps= 30 q=28.0 size=    1234kB time=00:00:04.56 bitrate=2234.5kbits/s
+      return nil unless line.include?("time=")
+
+      match = line.match(/time=(\d+):(\d+):(\d+(?:\.\d+)?)/)
+      return nil unless match
+
+      hours, minutes, seconds = match.captures.map(&:to_f)
+      current_time = hours * 3600 + minutes * 60 + seconds
+
+      progress = (current_time / total_duration * 100).round(1)
+      progress.clamp(0.0, 100.0)
+    end
+  end
+end

data/lib/ffmpeg/version.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module FFMPEG
+  VERSION = "0.1.0"
+
+  # Minimum supported FFmpeg version
+  MIN_FFMPEG_VERSION = "4.0"
+
+  # Tested FFmpeg versions
+  TESTED_FFMPEG_VERSIONS = %w[4 5 6 7].freeze
+end

data/lib/ffmpeg.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require_relative "ffmpeg/version"
+require_relative "ffmpeg/errors"
+require_relative "ffmpeg/configuration"
+require_relative "ffmpeg/command"
+require_relative "ffmpeg/media"
+require_relative "ffmpeg/stream"
+require_relative "ffmpeg/transcoder"
+require_relative "ffmpeg/scene_detector"
+require_relative "ffmpeg/keyframe_extractor"
+
+# Load Rails integration if Rails is available
+if defined?(Rails::Railtie)
+  require_relative "ffmpeg/railtie"
+end
+
+# Load Active Storage integration if Active Storage is available
+if defined?(ActiveStorage)
+  require_relative "ffmpeg/active_storage/analyzer"
+  require_relative "ffmpeg/active_storage/previewer"
+end
+
+# FFMPEG - A modern Ruby wrapper for FFmpeg
+#
+# @example Basic usage
+#   media = FFMPEG::Media.new("/path/to/video.mp4")
+#   media.duration     # => 120.5
+#   media.resolution   # => "1920x1080"
+#   media.video_codec  # => "h264"
+#
+# @example Transcoding
+#   media.transcode("/path/to/output.mp4") do |progress|
+#     puts "Progress: #{progress}%"
+#   end
+#
+# @example Scene detection
+#   detector = FFMPEG::SceneDetector.new(media)
+#   scenes = detector.detect(threshold: 0.3)
+#   # => [{ timestamp: 0.0 }, { timestamp: 5.2 }, ...]
+#
+# @example Keyframe extraction
+#   extractor = FFMPEG::KeyframeExtractor.new(media)
+#   frames = extractor.extract_at_intervals(interval: 5.0, output_dir: "/tmp/frames")
+#   # => ["/tmp/frames/frame_0000.jpg", ...]
+#
+module FFMPEG
+  class << self
+    # Global configuration
+    # @return [Configuration]
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    # Configure FFMPEG
+    # @yield [Configuration]
+    def configure
+      yield(configuration)
+    end
+
+    # Path to ffmpeg binary
+    # @return [String]
+    def ffmpeg_binary
+      configuration.ffmpeg_binary
+    end
+
+    # Path to ffprobe binary
+    # @return [String]
+    def ffprobe_binary
+      configuration.ffprobe_binary
+    end
+
+    # Logger instance
+    # @return [Logger, nil]
+    def logger
+      configuration.logger
+    end
+
+    # Check if FFmpeg is installed and accessible
+    # @return [Boolean]
+    def available?
+      Command.run(ffmpeg_binary, "-version").success?
+    rescue Errno::ENOENT
+      false
+    end
+
+    # Get FFmpeg version
+    # @return [String, nil]
+    def version
+      result = Command.run(ffmpeg_binary, "-version")
+      return nil unless result.success?
+
+      result.output.match(/ffmpeg version (\S+)/i)&.[](1)
+    end
+  end
+end

data/ruby-ffmpeg.gemspec

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "lib/ffmpeg/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "ruby-ffmpeg"
+  spec.version = FFMPEG::VERSION
+  spec.authors = ["Active Agents"]
+  spec.email = ["hello@activeagents.ai"]
+
+  spec.summary = "Modern Ruby wrapper for FFmpeg with scene detection and keyframe extraction"
+  spec.description = <<~DESC
+    A clean, well-tested FFmpeg wrapper with modern Ruby conventions, proper error handling,
+    and zero dependencies. Features include metadata extraction, transcoding with progress
+    reporting, scene detection, keyframe extraction, and Rails/Active Storage integration.
+    Tested against FFmpeg 4, 5, 6, and 7.
+  DESC
+  spec.homepage = "https://github.com/activeagents/ruby-ffmpeg"
+  spec.license = "MIT"
+  spec.required_ruby_version = ">= 3.1.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/activeagents/ruby-ffmpeg"
+  spec.metadata["changelog_uri"] = "https://github.com/activeagents/ruby-ffmpeg/blob/main/CHANGELOG.md"
+  spec.metadata["documentation_uri"] = "https://rubydoc.info/gems/ruby-ffmpeg"
+  spec.metadata["bug_tracker_uri"] = "https://github.com/activeagents/ruby-ffmpeg/issues"
+  spec.metadata["rubygems_mfa_required"] = "true"
+
+  # Specify which files should be added to the gem when it is released
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ .git .github .rubocop Gemfile])
+    end
+  end
+
+  spec.bindir = "exe"
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  # No runtime dependencies - just pure Ruby!
+  # FFmpeg binary must be installed separately
+
+  # Development dependencies
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "rake", "~> 13.0"
+  spec.add_development_dependency "rubocop", "~> 1.21"
+  spec.add_development_dependency "yard", "~> 0.9"
+end