ruby-ffmpeg 0.1.0

data/lib/ffmpeg/media.rb

@@ -0,0 +1,385 @@
+# frozen_string_literal: true
+
+require "json"
+
+module FFMPEG
+  # Represents a media file and provides access to its metadata
+  #
+  # @example Basic usage
+  #   media = FFMPEG::Media.new("/path/to/video.mp4")
+  #   media.duration     # => 120.5
+  #   media.resolution   # => "1920x1080"
+  #   media.video_codec  # => "h264"
+  #   media.audio_codec  # => "aac"
+  #
+  # @example Checking properties
+  #   media.valid?       # => true
+  #   media.video?       # => true
+  #   media.audio?       # => true
+  #   media.hd?          # => true
+  #
+  # @example Transcoding
+  #   media.transcode("/path/to/output.webm", video_codec: "libvpx-vp9")
+  #
+  class Media
+    # @return [String] path to the media file
+    attr_reader :path
+
+    # @return [Hash] raw ffprobe output
+    attr_reader :raw
+
+    # @return [Array<Stream>] all streams in the media
+    attr_reader :streams
+
+    # @return [Hash] format information
+    attr_reader :format
+
+    # Create a new Media instance
+    # @param path [String] path to the media file
+    # @raise [MediaNotFound] if file doesn't exist
+    # @raise [InvalidMedia] if file can't be parsed
+    def initialize(path)
+      @path = File.expand_path(path)
+      validate_file!
+      probe!
+    end
+
+    # @return [Boolean] true if media was successfully parsed
+    def valid?
+      @valid
+    end
+
+    # @return [Float, nil] duration in seconds
+    def duration
+      format["duration"]&.to_f
+    end
+
+    # @return [Integer, nil] bit rate in bits/sec
+    def bit_rate
+      format["bit_rate"]&.to_i
+    end
+
+    # @return [Integer, nil] file size in bytes
+    def size
+      format["size"]&.to_i || File.size(path)
+    end
+
+    # @return [String, nil] container format name
+    def format_name
+      format["format_name"]
+    end
+
+    # @return [String, nil] format long name
+    def format_long_name
+      format["format_long_name"]
+    end
+
+    # @return [Hash] format tags (title, artist, etc.)
+    def tags
+      format["tags"] || {}
+    end
+
+    # @return [String, nil] media title from tags
+    def title
+      tags["title"]
+    end
+
+    # @return [Time, nil] creation time if available
+    def creation_time
+      time_str = tags["creation_time"]
+      Time.parse(time_str) if time_str
+    rescue ArgumentError
+      nil
+    end
+
+    # === Stream Accessors ===
+
+    # @return [Array<Stream>] all video streams
+    def video_streams
+      @video_streams ||= streams.select(&:video?)
+    end
+
+    # @return [Array<Stream>] all audio streams
+    def audio_streams
+      @audio_streams ||= streams.select(&:audio?)
+    end
+
+    # @return [Array<Stream>] all subtitle streams
+    def subtitle_streams
+      @subtitle_streams ||= streams.select(&:subtitle?)
+    end
+
+    # @return [Stream, nil] primary video stream
+    def video
+      video_streams.find(&:default) || video_streams.first
+    end
+
+    # @return [Stream, nil] primary audio stream
+    def audio
+      audio_streams.find(&:default) || audio_streams.first
+    end
+
+    # @return [Boolean] true if media has video
+    def video?
+      video_streams.any?
+    end
+
+    # @return [Boolean] true if media has audio
+    def audio?
+      audio_streams.any?
+    end
+
+    # === Video Properties (shortcuts to primary video stream) ===
+
+    # @return [Integer, nil] video width
+    def width
+      video&.width
+    end
+
+    # @return [Integer, nil] video height
+    def height
+      video&.height
+    end
+
+    # @return [String, nil] resolution as "WIDTHxHEIGHT"
+    def resolution
+      video&.resolution
+    end
+
+    # @return [String, nil] video codec name
+    def video_codec
+      video&.codec
+    end
+
+    # @return [Float, nil] video frame rate
+    def frame_rate
+      video&.frame_rate
+    end
+
+    # @return [Integer, nil] video bit rate
+    def video_bit_rate
+      video&.bit_rate
+    end
+
+    # @return [Integer, nil] video rotation in degrees
+    def rotation
+      video&.rotation
+    end
+
+    # @return [String, nil] pixel format
+    def pixel_format
+      video&.pixel_format
+    end
+
+    # @return [Boolean] true if video is portrait
+    def portrait?
+      video&.portrait? || false
+    end
+
+    # @return [Boolean] true if video is landscape
+    def landscape?
+      video&.landscape? || false
+    end
+
+    # @return [Boolean] true if video is HD (720p+)
+    def hd?
+      video&.hd? || false
+    end
+
+    # @return [Boolean] true if video is 4K (2160p+)
+    def uhd?
+      video&.uhd? || false
+    end
+
+    # === Audio Properties (shortcuts to primary audio stream) ===
+
+    # @return [String, nil] audio codec name
+    def audio_codec
+      audio&.codec
+    end
+
+    # @return [Integer, nil] audio sample rate
+    def sample_rate
+      audio&.sample_rate
+    end
+
+    # @return [Integer, nil] number of audio channels
+    def audio_channels
+      audio&.channels
+    end
+
+    # @return [String, nil] audio channel layout
+    def channel_layout
+      audio&.channel_layout
+    end
+
+    # @return [Integer, nil] audio bit rate
+    def audio_bit_rate
+      audio&.bit_rate
+    end
+
+    # === Frame Information ===
+
+    # @return [Integer, nil] approximate total frame count
+    def frame_count
+      return nil unless duration && frame_rate
+
+      (duration * frame_rate).round
+    end
+
+    # Calculate timestamp for a specific frame
+    # @param frame_number [Integer] frame number (0-indexed)
+    # @return [Float, nil] timestamp in seconds
+    def frame_to_timestamp(frame_number)
+      return nil unless frame_rate && frame_rate.positive?
+
+      frame_number.to_f / frame_rate
+    end
+
+    # Calculate frame number for a specific timestamp
+    # @param timestamp [Float] timestamp in seconds
+    # @return [Integer, nil] frame number (0-indexed)
+    def timestamp_to_frame(timestamp)
+      return nil unless frame_rate
+
+      (timestamp.to_f * frame_rate).round
+    end
+
+    # === Transcoding ===
+
+    # Transcode media to a new file
+    # @param output_path [String] path to output file
+    # @param options [Hash] transcoding options
+    # @yield [Float] progress percentage (0-100)
+    # @return [Media] the transcoded media
+    # @raise [TranscodingError] if transcoding fails
+    def transcode(output_path, **options, &block)
+      transcoder = Transcoder.new(self, output_path, **options)
+      transcoder.run(&block)
+    end
+
+    # === Scene Detection ===
+
+    # Detect scene changes in the video
+    # @param threshold [Float] scene detection threshold (0.0-1.0)
+    # @return [Array<Hash>] array of scene change points
+    def detect_scenes(threshold: 0.3)
+      detector = SceneDetector.new(self)
+      detector.detect(threshold: threshold)
+    end
+
+    # === Keyframe Extraction ===
+
+    # Extract keyframes from the video
+    # @param output_dir [String] directory for extracted frames
+    # @param interval [Float, nil] interval between frames in seconds
+    # @param count [Integer, nil] number of frames to extract
+    # @param timestamps [Array<Float>, nil] specific timestamps
+    # @return [Array<String>] paths to extracted frames
+    def extract_keyframes(output_dir:, interval: nil, count: nil, timestamps: nil)
+      extractor = KeyframeExtractor.new(self)
+
+      if timestamps
+        extractor.extract_at_timestamps(timestamps, output_dir: output_dir)
+      elsif count
+        extractor.extract_count(count, output_dir: output_dir)
+      else
+        extractor.extract_at_intervals(interval: interval || 5.0, output_dir: output_dir)
+      end
+    end
+
+    # === Screenshots ===
+
+    # Take a screenshot at a specific timestamp
+    # @param timestamp [Float] timestamp in seconds
+    # @param output_path [String] path for output image
+    # @param resolution [String, nil] output resolution (e.g., "640x480")
+    # @return [String] path to the screenshot
+    def screenshot(timestamp, output_path, resolution: nil)
+      extractor = KeyframeExtractor.new(self)
+      extractor.extract_at_timestamps([timestamp], output_dir: File.dirname(output_path)).first
+    end
+
+    # @return [String] human-readable description
+    def to_s
+      parts = ["Media: #{File.basename(path)}"]
+      parts << "Duration: #{format_duration(duration)}" if duration
+      parts << "Resolution: #{resolution}" if resolution
+      parts << "Codecs: #{video_codec}/#{audio_codec}" if video_codec || audio_codec
+      parts.join(" | ")
+    end
+
+    # @return [Hash] serializable representation
+    def to_h
+      {
+        path: path,
+        duration: duration,
+        size: size,
+        format: format_name,
+        video: video ? {
+          codec: video_codec,
+          resolution: resolution,
+          frame_rate: frame_rate,
+          bit_rate: video_bit_rate
+        } : nil,
+        audio: audio ? {
+          codec: audio_codec,
+          sample_rate: sample_rate,
+          channels: audio_channels,
+          bit_rate: audio_bit_rate
+        } : nil,
+        streams: streams.map(&:to_s)
+      }
+    end
+
+    private
+
+    def validate_file!
+      raise MediaNotFound, path unless File.exist?(path)
+      raise MediaNotFound, path unless File.readable?(path)
+    end
+
+    def probe!
+      result = Command.run(
+        FFMPEG.ffprobe_binary,
+        "-v", "quiet",
+        "-print_format", "json",
+        "-show_format",
+        "-show_streams",
+        path
+      )
+
+      unless result.success?
+        @valid = false
+        raise InvalidMedia.new(path, "ffprobe failed: #{result.error}")
+      end
+
+      begin
+        @raw = JSON.parse(result.output)
+      rescue JSON::ParserError => e
+        @valid = false
+        raise InvalidMedia.new(path, "Invalid ffprobe output: #{e.message}")
+      end
+
+      @format = @raw["format"] || {}
+      @streams = (@raw["streams"] || []).map { |s| Stream.new(s) }
+      @valid = @streams.any?
+
+      raise InvalidMedia.new(path, "No streams found") unless @valid
+    end
+
+    def format_duration(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
+end

data/lib/ffmpeg/railtie.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "rails/railtie"
+
+module FFMPEG
+  # Rails integration for FFMPEG
+  #
+  # Automatically configures FFMPEG with Rails defaults when the gem is loaded
+  # in a Rails application.
+  #
+  # @example Configuration in initializer
+  #   # config/initializers/ffmpeg.rb
+  #   FFMPEG.configure do |config|
+  #     config.logger = Rails.logger
+  #     config.temp_dir = Rails.root.join("tmp/ffmpeg")
+  #   end
+  #
+  class Railtie < Rails::Railtie
+    initializer "ffmpeg.configure" do
+      FFMPEG.configure do |config|
+        config.logger = Rails.logger if Rails.logger
+        config.temp_dir = Rails.root.join("tmp/ffmpeg").to_s
+      end
+    end
+
+    # Add rake tasks if available
+    rake_tasks do
+      load File.expand_path("tasks/ffmpeg.rake", __dir__)
+    end
+  end
+end

data/lib/ffmpeg/scene_detector.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module FFMPEG
+  # Detects scene changes in video using FFmpeg's scene detection filter
+  #
+  # @example Basic usage
+  #   detector = SceneDetector.new(media)
+  #   scenes = detector.detect(threshold: 0.3)
+  #   # => [
+  #   #   { timestamp: 0.0, score: 1.0 },
+  #   #   { timestamp: 5.23, score: 0.45 },
+  #   #   { timestamp: 12.8, score: 0.38 }
+  #   # ]
+  #
+  # @example With custom options
+  #   scenes = detector.detect(
+  #     threshold: 0.4,
+  #     min_scene_length: 2.0,
+  #     max_scenes: 20
+  #   )
+  #
+  class SceneDetector
+    # @return [Media] source media
+    attr_reader :media
+
+    # Create a new SceneDetector
+    # @param media [Media] source media
+    def initialize(media)
+      @media = media
+      validate_media!
+    end
+
+    # Detect scene changes
+    # @param threshold [Float] scene detection threshold (0.0-1.0)
+    #   Lower values detect more scene changes
+    # @param min_scene_length [Float, nil] minimum time between scenes in seconds
+    # @param max_scenes [Integer, nil] maximum number of scenes to detect
+    # @return [Array<Hash>] detected scenes with :timestamp and :score
+    # @raise [SceneDetectionError] if detection fails
+    def detect(threshold: 0.3, min_scene_length: nil, max_scenes: nil)
+      scenes = run_detection(threshold)
+
+      # Always include first frame
+      scenes.unshift({ timestamp: 0.0, score: 1.0 }) unless scenes.any? { |s| s[:timestamp].zero? }
+
+      # Filter by minimum scene length
+      if min_scene_length
+        scenes = filter_by_min_length(scenes, min_scene_length)
+      end
+
+      # Limit number of scenes
+      if max_scenes && scenes.length > max_scenes
+        scenes = select_best_scenes(scenes, max_scenes)
+      end
+
+      scenes.sort_by { |s| s[:timestamp] }
+    end
+
+    # Detect scenes and extract a keyframe for each
+    # @param threshold [Float] scene detection threshold
+    # @param output_dir [String] directory for extracted frames
+    # @param format [String] image format (jpg, png)
+    # @return [Array<Hash>] scenes with :timestamp, :score, and :keyframe_path
+    def detect_with_keyframes(threshold: 0.3, output_dir:, format: "jpg")
+      scenes = detect(threshold: threshold)
+
+      FileUtils.mkdir_p(output_dir)
+
+      scenes.each_with_index do |scene, index|
+        output_path = File.join(output_dir, "scene_%04d.#{format}" % index)
+        extract_frame(scene[:timestamp], output_path)
+        scene[:keyframe_path] = output_path
+      end
+
+      scenes
+    end
+
+    private
+
+    def validate_media!
+      raise SceneDetectionError, "Media has no video stream" unless media.video?
+    end
+
+    def run_detection(threshold)
+      # Use FFmpeg's select filter with scene detection
+      # Output format: frame:N pts:N pts_time:N.NNN scene:N.NNNN
+      cmd = [
+        FFMPEG.ffmpeg_binary,
+        "-i", media.path,
+        "-vf", "select='gt(scene,#{threshold})',showinfo",
+        "-f", "null",
+        "-"
+      ]
+
+      result = Command.run(*cmd)
+
+      # Even if command returns non-zero, we may have valid output
+      parse_scene_output(result.error)
+    end
+
+    def parse_scene_output(output)
+      scenes = []
+
+      # Parse showinfo filter output
+      # Example: [showinfo @ 0x...] n:   0 pts:      0 pts_time:0       ...
+      output.each_line do |line|
+        next unless line.include?("pts_time:")
+
+        match = line.match(/pts_time:(\d+\.?\d*)/)
+        next unless match
+
+        timestamp = match[1].to_f
+
+        # Try to extract scene score if available
+        score_match = line.match(/scene:(\d+\.?\d*)/)
+        score = score_match ? score_match[1].to_f : nil
+
+        scenes << {
+          timestamp: timestamp,
+          score: score || threshold_to_score(0.3)
+        }
+      end
+
+      scenes
+    end
+
+    def threshold_to_score(threshold)
+      # Convert threshold to approximate score
+      (1.0 - threshold + 0.1).clamp(0.0, 1.0)
+    end
+
+    def filter_by_min_length(scenes, min_length)
+      return scenes if scenes.empty?
+
+      filtered = [scenes.first]
+
+      scenes[1..].each do |scene|
+        if scene[:timestamp] - filtered.last[:timestamp] >= min_length
+          filtered << scene
+        end
+      end
+
+      filtered
+    end
+
+    def select_best_scenes(scenes, max_count)
+      # Keep first scene always, then select by highest score
+      return scenes if scenes.length <= max_count
+
+      first = scenes.first
+      rest = scenes[1..].sort_by { |s| -s[:score] }.first(max_count - 1)
+
+      [first, *rest].sort_by { |s| s[:timestamp] }
+    end
+
+    def extract_frame(timestamp, output_path)
+      cmd = [
+        FFMPEG.ffmpeg_binary,
+        "-ss", timestamp.to_s,
+        "-i", media.path,
+        "-vframes", "1",
+        "-y",
+        output_path
+      ]
+
+      result = Command.run(*cmd)
+      raise SceneDetectionError, "Failed to extract frame: #{result.error}" unless result.success?
+    end
+  end
+end