ruby-ffmpeg 0.1.0

data/lib/ffmpeg/command.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+require "open3"
+require "timeout"
+
+module FFMPEG
+  # Safely executes shell commands with timeout and proper error handling
+  #
+  # @example Basic usage
+  #   result = Command.run("ffmpeg", "-i", "input.mp4", "-c", "copy", "output.mp4")
+  #   result.success? # => true
+  #   result.output   # => "..."
+  #
+  # @example With progress callback
+  #   Command.run("ffmpeg", "-i", "input.mp4", "output.mp4") do |line|
+  #     # Parse progress from stderr
+  #     if (match = line.match(/time=(\d+:\d+:\d+\.\d+)/))
+  #       puts "Progress: #{match[1]}"
+  #     end
+  #   end
+  #
+  class Command
+    # Result of a command execution
+    Result = Data.define(:output, :error, :exit_code) do
+      def success?
+        exit_code.zero?
+      end
+
+      def failure?
+        !success?
+      end
+    end
+
+    class << self
+      # Run a command with arguments
+      # @param args [Array<String>] command and arguments
+      # @param timeout [Integer, nil] timeout in seconds
+      # @param env [Hash] environment variables
+      # @yield [String] each line of output for progress tracking
+      # @return [Result]
+      def run(*args, timeout: nil, env: {}, &block)
+        timeout ||= FFMPEG.configuration.timeout
+
+        log_command(args)
+
+        output = +""
+        error = +""
+        exit_status = nil
+
+        begin
+          Timeout.timeout(timeout) do
+            Open3.popen3(env, *args) do |stdin, stdout, stderr, wait_thr|
+              stdin.close
+
+              # Read stdout and stderr in threads to avoid blocking
+              stdout_thread = Thread.new do
+                stdout.each_line do |line|
+                  output << line
+                  yield line if block_given?
+                end
+              end
+
+              stderr_thread = Thread.new do
+                stderr.each_line do |line|
+                  error << line
+                  yield line if block_given?
+                end
+              end
+
+              stdout_thread.join
+              stderr_thread.join
+
+              exit_status = wait_thr.value
+            end
+          end
+        rescue Timeout::Error
+          raise CommandTimeout.new(args.join(" "), timeout)
+        end
+
+        log_result(output, error, exit_status&.exitstatus || 1)
+
+        Result.new(
+          output: output,
+          error: error,
+          exit_code: exit_status&.exitstatus || 1
+        )
+      end
+
+      # Run a command and raise on failure
+      # @param args [Array<String>] command and arguments
+      # @param timeout [Integer, nil] timeout in seconds
+      # @param env [Hash] environment variables
+      # @yield [String] each line of output
+      # @return [Result]
+      # @raise [TranscodingError] if command fails
+      def run!(*args, timeout: nil, env: {}, &block)
+        result = run(*args, timeout: timeout, env: env, &block)
+
+        unless result.success?
+          raise TranscodingError.new(
+            "Command failed with exit code #{result.exit_code}",
+            command: args.join(" "),
+            output: result.error,
+            exit_code: result.exit_code
+          )
+        end
+
+        result
+      end
+
+      # Build FFmpeg command with common options
+      # @param input [String] input file path
+      # @param output [String] output file path
+      # @param options [Hash] FFmpeg options
+      # @return [Array<String>]
+      def build_ffmpeg_command(input:, output:, **options)
+        cmd = [FFMPEG.ffmpeg_binary]
+
+        # Overwrite output
+        cmd << "-y" if FFMPEG.configuration.overwrite_output
+
+        # Input options (before -i)
+        if options[:seek]
+          cmd += ["-ss", options[:seek].to_s]
+        end
+
+        if options[:duration]
+          cmd += ["-t", options[:duration].to_s]
+        end
+
+        # Input file
+        cmd += ["-i", input]
+
+        # Video codec
+        if options[:video_codec]
+          cmd += ["-c:v", options[:video_codec]]
+        elsif options[:copy_video]
+          cmd += ["-c:v", "copy"]
+        end
+
+        # Audio codec
+        if options[:audio_codec]
+          cmd += ["-c:a", options[:audio_codec]]
+        elsif options[:copy_audio]
+          cmd += ["-c:a", "copy"]
+        elsif options[:no_audio]
+          cmd << "-an"
+        end
+
+        # Video filters
+        if options[:video_filters]&.any?
+          cmd += ["-vf", options[:video_filters].join(",")]
+        end
+
+        # Audio filters
+        if options[:audio_filters]&.any?
+          cmd += ["-af", options[:audio_filters].join(",")]
+        end
+
+        # Resolution
+        if options[:resolution]
+          cmd += ["-s", options[:resolution]]
+        end
+
+        # Frame rate
+        if options[:frame_rate]
+          cmd += ["-r", options[:frame_rate].to_s]
+        end
+
+        # Bitrate
+        if options[:video_bitrate]
+          cmd += ["-b:v", options[:video_bitrate]]
+        end
+
+        if options[:audio_bitrate]
+          cmd += ["-b:a", options[:audio_bitrate]]
+        end
+
+        # Threads
+        threads = options[:threads] || FFMPEG.configuration.threads
+        cmd += ["-threads", threads.to_s] if threads.positive?
+
+        # Custom options
+        if options[:custom]
+          cmd += Array(options[:custom]).flat_map { |opt| opt.split }
+        end
+
+        # Output format
+        if options[:format]
+          cmd += ["-f", options[:format]]
+        end
+
+        # Output file
+        cmd << output
+
+        cmd
+      end
+
+      private
+
+      def log_command(args)
+        return unless FFMPEG.logger
+
+        FFMPEG.logger.debug { "[FFMPEG] Running: #{args.join(' ')}" }
+      end
+
+      def log_result(output, error, exit_code)
+        return unless FFMPEG.logger
+
+        if exit_code.zero?
+          FFMPEG.logger.debug { "[FFMPEG] Success" }
+        else
+          FFMPEG.logger.error { "[FFMPEG] Failed (exit #{exit_code}): #{error}" }
+        end
+      end
+    end
+  end
+end

data/lib/ffmpeg/configuration.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require "logger"
+
+module FFMPEG
+  # Configuration options for FFMPEG
+  #
+  # @example
+  #   FFMPEG.configure do |config|
+  #     config.ffmpeg_binary = "/usr/local/bin/ffmpeg"
+  #     config.ffprobe_binary = "/usr/local/bin/ffprobe"
+  #     config.timeout = 300
+  #     config.logger = Rails.logger
+  #   end
+  #
+  class Configuration
+    # Path to ffmpeg binary
+    # @return [String]
+    attr_accessor :ffmpeg_binary
+
+    # Path to ffprobe binary
+    # @return [String]
+    attr_accessor :ffprobe_binary
+
+    # Default timeout for commands in seconds
+    # @return [Integer]
+    attr_accessor :timeout
+
+    # Logger for debug output
+    # @return [Logger, nil]
+    attr_accessor :logger
+
+    # Default video codec for transcoding
+    # @return [String]
+    attr_accessor :default_video_codec
+
+    # Default audio codec for transcoding
+    # @return [String]
+    attr_accessor :default_audio_codec
+
+    # Default output format
+    # @return [String]
+    attr_accessor :default_format
+
+    # Number of threads to use (0 = auto)
+    # @return [Integer]
+    attr_accessor :threads
+
+    # Hardware acceleration type (nil, :cuda, :videotoolbox, :vaapi, :qsv)
+    # @return [Symbol, nil]
+    attr_accessor :hardware_acceleration
+
+    # Temporary directory for intermediate files
+    # @return [String]
+    attr_accessor :temp_dir
+
+    # Whether to overwrite existing output files
+    # @return [Boolean]
+    attr_accessor :overwrite_output
+
+    def initialize
+      @ffmpeg_binary = find_binary("ffmpeg")
+      @ffprobe_binary = find_binary("ffprobe")
+      @timeout = 600 # 10 minutes default
+      @logger = nil
+      @default_video_codec = "libx264"
+      @default_audio_codec = "aac"
+      @default_format = "mp4"
+      @threads = 0 # auto
+      @hardware_acceleration = nil
+      @temp_dir = Dir.tmpdir
+      @overwrite_output = true
+    end
+
+    # Reset configuration to defaults
+    def reset!
+      initialize
+    end
+
+    # Validate configuration
+    # @raise [FFmpegNotFound] if ffmpeg binary not found
+    # @raise [FFprobeNotFound] if ffprobe binary not found
+    def validate!
+      raise FFmpegNotFound, @ffmpeg_binary unless binary_exists?(@ffmpeg_binary)
+      raise FFprobeNotFound, @ffprobe_binary unless binary_exists?(@ffprobe_binary)
+
+      true
+    end
+
+    private
+
+    def find_binary(name)
+      # Check common locations
+      paths = [
+        name, # Use PATH
+        "/usr/bin/#{name}",
+        "/usr/local/bin/#{name}",
+        "/opt/homebrew/bin/#{name}",
+        "/opt/local/bin/#{name}"
+      ]
+
+      paths.find { |path| binary_exists?(path) } || name
+    end
+
+    def binary_exists?(path)
+      return false if path.nil? || path.empty?
+
+      # Check if it's in PATH or is an absolute path that exists
+      system("which", path, out: File::NULL, err: File::NULL) ||
+        (File.absolute_path?(path) && File.executable?(path))
+    end
+  end
+end

data/lib/ffmpeg/errors.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+module FFMPEG
+  # Base error class for all FFMPEG errors
+  class Error < StandardError; end
+
+  # Raised when FFmpeg binary is not found
+  class FFmpegNotFound < Error
+    def initialize(binary = "ffmpeg")
+      super("#{binary} not found. Please install FFmpeg: https://ffmpeg.org/download.html")
+    end
+  end
+
+  # Raised when FFprobe binary is not found
+  class FFprobeNotFound < Error
+    def initialize(binary = "ffprobe")
+      super("#{binary} not found. Please install FFmpeg: https://ffmpeg.org/download.html")
+    end
+  end
+
+  # Raised when media file is not found or inaccessible
+  class MediaNotFound < Error
+    def initialize(path)
+      super("Media file not found: #{path}")
+    end
+  end
+
+  # Raised when media file is invalid or corrupted
+  class InvalidMedia < Error
+    def initialize(path, reason = nil)
+      message = "Invalid media file: #{path}"
+      message += " (#{reason})" if reason
+      super(message)
+    end
+  end
+
+  # Raised when transcoding fails
+  class TranscodingError < Error
+    attr_reader :command, :output, :exit_code
+
+    def initialize(message, command: nil, output: nil, exit_code: nil)
+      @command = command
+      @output = output
+      @exit_code = exit_code
+      super(message)
+    end
+  end
+
+  # Raised when a command times out
+  class CommandTimeout < Error
+    attr_reader :command, :timeout
+
+    def initialize(command, timeout)
+      @command = command
+      @timeout = timeout
+      super("Command timed out after #{timeout}s: #{command}")
+    end
+  end
+
+  # Raised when scene detection fails
+  class SceneDetectionError < Error; end
+
+  # Raised when keyframe extraction fails
+  class KeyframeExtractionError < Error; end
+
+  # Raised when preset is not found
+  class PresetNotFound < Error
+    def initialize(preset_name)
+      super("Preset not found: #{preset_name}")
+    end
+  end
+
+  # Raised when filter is invalid
+  class InvalidFilter < Error
+    def initialize(filter_name, reason = nil)
+      message = "Invalid filter: #{filter_name}"
+      message += " (#{reason})" if reason
+      super(message)
+    end
+  end
+end

data/lib/ffmpeg/keyframe_extractor.rb

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module FFMPEG
+  # Extracts keyframes/thumbnails from video files
+  #
+  # @example Extract at intervals
+  #   extractor = KeyframeExtractor.new(media)
+  #   frames = extractor.extract_at_intervals(interval: 5.0, output_dir: "/tmp/frames")
+  #   # => ["/tmp/frames/frame_0000.jpg", "/tmp/frames/frame_0005.jpg", ...]
+  #
+  # @example Extract specific count
+  #   frames = extractor.extract_count(10, output_dir: "/tmp/frames")
+  #   # => ["/tmp/frames/frame_0000.jpg", ..., "/tmp/frames/frame_0009.jpg"]
+  #
+  # @example Extract at specific timestamps
+  #   frames = extractor.extract_at_timestamps([0, 30, 60, 90], output_dir: "/tmp/frames")
+  #
+  class KeyframeExtractor
+    # Supported output formats
+    FORMATS = %w[jpg jpeg png bmp webp].freeze
+
+    # @return [Media] source media
+    attr_reader :media
+
+    # Create a new KeyframeExtractor
+    # @param media [Media] source media
+    def initialize(media)
+      @media = media
+      validate_media!
+    end
+
+    # Extract frames at regular intervals
+    # @param interval [Float] interval between frames in seconds
+    # @param output_dir [String] directory for output frames
+    # @param format [String] output image format
+    # @param quality [Integer] JPEG quality (1-31 for ffmpeg, lower is better)
+    # @param resolution [String, nil] output resolution (e.g., "640x480")
+    # @return [Array<String>] paths to extracted frames
+    def extract_at_intervals(interval: 5.0, output_dir:, format: "jpg", quality: 2, resolution: nil)
+      ensure_output_dir!(output_dir)
+      validate_format!(format)
+
+      # Calculate timestamps
+      timestamps = []
+      current = 0.0
+      while current < media.duration
+        timestamps << current
+        current += interval
+      end
+
+      extract_frames(timestamps, output_dir, format, quality, resolution)
+    end
+
+    # Extract a specific number of frames evenly distributed
+    # @param count [Integer] number of frames to extract
+    # @param output_dir [String] directory for output frames
+    # @param format [String] output image format
+    # @param quality [Integer] JPEG quality
+    # @param resolution [String, nil] output resolution
+    # @return [Array<String>] paths to extracted frames
+    def extract_count(count, output_dir:, format: "jpg", quality: 2, resolution: nil)
+      ensure_output_dir!(output_dir)
+      validate_format!(format)
+
+      return [] if count <= 0
+
+      # Calculate evenly distributed timestamps
+      duration = media.duration || 0
+      timestamps = if count == 1
+                     [0.0]
+                   else
+                     interval = duration / (count - 1)
+                     (0...count).map { |i| i * interval }
+                   end
+
+      extract_frames(timestamps, output_dir, format, quality, resolution)
+    end
+
+    # Extract frames at specific timestamps
+    # @param timestamps [Array<Float>] timestamps in seconds
+    # @param output_dir [String] directory for output frames
+    # @param format [String] output image format
+    # @param quality [Integer] JPEG quality
+    # @param resolution [String, nil] output resolution
+    # @return [Array<String>] paths to extracted frames
+    def extract_at_timestamps(timestamps, output_dir:, format: "jpg", quality: 2, resolution: nil)
+      ensure_output_dir!(output_dir)
+      validate_format!(format)
+
+      extract_frames(timestamps.sort, output_dir, format, quality, resolution)
+    end
+
+    # Extract actual I-frames (keyframes) from the video
+    # @param output_dir [String] directory for output frames
+    # @param format [String] output image format
+    # @param quality [Integer] JPEG quality
+    # @param max_frames [Integer, nil] maximum number of frames
+    # @return [Array<String>] paths to extracted frames
+    def extract_iframes(output_dir:, format: "jpg", quality: 2, max_frames: nil)
+      ensure_output_dir!(output_dir)
+      validate_format!(format)
+
+      output_pattern = File.join(output_dir, "iframe_%04d.#{format}")
+
+      cmd = [
+        FFMPEG.ffmpeg_binary,
+        "-i", media.path,
+        "-vf", "select='eq(pict_type,I)'",
+        "-vsync", "vfr",
+        "-q:v", quality.to_s
+      ]
+
+      cmd += ["-frames:v", max_frames.to_s] if max_frames
+      cmd += ["-y", output_pattern]
+
+      result = Command.run!(*cmd)
+
+      # Return list of created files
+      Dir.glob(File.join(output_dir, "iframe_*.#{format}")).sort
+    end
+
+    # Create a thumbnail sprite sheet (useful for video scrubbing)
+    # @param columns [Integer] number of columns in sprite
+    # @param rows [Integer] number of rows in sprite
+    # @param width [Integer] thumbnail width
+    # @param output_path [String] output sprite path
+    # @return [Hash] sprite info with :path, :columns, :rows, :thumbnail_width, :thumbnail_height
+    def create_sprite(columns: 10, rows: 10, width: 160, output_path:)
+      total_frames = columns * rows
+      interval = (media.duration || 0) / total_frames
+
+      # Calculate thumbnail height maintaining aspect ratio
+      aspect_ratio = (media.width.to_f / media.height) rescue 16.0/9
+      height = (width / aspect_ratio).round
+
+      tile = "#{columns}x#{rows}"
+      scale = "scale=#{width}:#{height}"
+
+      cmd = [
+        FFMPEG.ffmpeg_binary,
+        "-i", media.path,
+        "-vf", "fps=1/#{interval},#{scale},tile=#{tile}",
+        "-frames:v", "1",
+        "-y",
+        output_path
+      ]
+
+      Command.run!(*cmd)
+
+      {
+        path: output_path,
+        columns: columns,
+        rows: rows,
+        thumbnail_width: width,
+        thumbnail_height: height,
+        interval: interval
+      }
+    end
+
+    private
+
+    def validate_media!
+      raise KeyframeExtractionError, "Media has no video stream" unless media.video?
+    end
+
+    def validate_format!(format)
+      unless FORMATS.include?(format.downcase)
+        raise KeyframeExtractionError, "Unsupported format: #{format}. Supported: #{FORMATS.join(', ')}"
+      end
+    end
+
+    def ensure_output_dir!(dir)
+      FileUtils.mkdir_p(dir) unless File.directory?(dir)
+    end
+
+    def extract_frames(timestamps, output_dir, format, quality, resolution)
+      frames = []
+
+      timestamps.each_with_index do |timestamp, index|
+        output_path = File.join(output_dir, "frame_%04d.#{format}" % index)
+        extract_single_frame(timestamp, output_path, quality, resolution)
+        frames << output_path if File.exist?(output_path)
+      end
+
+      frames
+    end
+
+    def extract_single_frame(timestamp, output_path, quality, resolution)
+      cmd = [
+        FFMPEG.ffmpeg_binary,
+        "-ss", format_timestamp(timestamp),
+        "-i", media.path,
+        "-vframes", "1",
+        "-q:v", quality.to_s
+      ]
+
+      cmd += ["-s", resolution] if resolution
+      cmd += ["-y", output_path]
+
+      Command.run(*cmd)
+    end
+
+    def format_timestamp(seconds)
+      hours = (seconds / 3600).floor
+      minutes = ((seconds % 3600) / 60).floor
+      secs = seconds % 60
+
+      format("%02d:%02d:%06.3f", hours, minutes, secs)
+    end
+  end
+end