ffmpeg_core 0.2.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4efe5152c9dd01b8ebb2d34c9f6d6877371d017845242297f57f65044c968648
-  data.tar.gz: a1b09735ebc0acc9c21b252e3fa32b4168e0c5694eab8d72fa299e7c8c88dc9f
+  metadata.gz: afead7a6fce7f95748207153b521b35a223f2efd7add35664e12ba3e27f86b23
+  data.tar.gz: 3052072fb4a3541518cc5d12bf333b58b77a77f2b3b4deec44d51b89ddbac678
 SHA512:
-  metadata.gz: f3c4ace64795f63226082eb3eeb6e395c0f35976b86de25a3a8ed7c46973ce7d2b234de2485a6e3cd083060653da3f2d6a8f8c3a254260a15d5e472462097a21
-  data.tar.gz: 7b390fe28da3e17efe7a4523001aa41a0aa70685fc8e5d5951faf55e5d2feabe96e3aa5e48f94c0f3a0c70016a23b49c7b063739ae953bde41bba92b524e36b7
+  metadata.gz: d725d25a1d211186ede000ac81d58f20c57fc8f46ba5a3897b006a8e92e128b37f5f9cfb9295633bfe0a7dd878a0f99793329c388c1c2a920bc585256b4740db
+  data.tar.gz: 5e683ec8fb39dc1e669abaeaa8e3f7254de8f92ef4593ed6869ba7a5a4c02dab2d6ee8005243dbf31e24be27b11a689c89de736c0eca69e93be38b7d9e5fc531

data/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.0] - 2026-01-26
+
+### Added
+
+- **Complex Filters & Mapping:** Added `filter_graph` (for `-filter_complex`) and `maps` (for `-map`) options to `transcode`.
+- **Hardware Acceleration:** Added `:hwaccel` option to `transcode` (supports `:nvenc`, `:vaapi`, `:qsv`) with automatic encoder detection.
+
+## [0.3.0] - 2026-01-16
+
+### Added
+
+- **Remote Input Support:** `Movie.new` now accepts HTTP, HTTPS, RTMP, and RTSP URLs.
+- **Crop Support:** Added `crop` option to `transcode` (e.g., `crop: { width: 100, height: 100, x: 10, y: 10 }`).
+- **Advanced Metadata:** Added `video_profile` and `video_level` to `Probe`.
+- Rotation detection from `side_data_list` for better compatibility with newer video formats.
+
+### Fixed
+
+- **Rotation Geometry:** `Probe#width` and `Probe#height` now correctly swap values if the video is rotated 90 or 270 degrees.
+
 ## [0.2.0] - 2026-01-15
 
 ### Added

data/README.md

@@ -11,6 +11,8 @@ Modern Ruby wrapper for FFmpeg with clean API and proper error handling.
 - Zero runtime dependencies
 - **Real-time progress reporting**
 - **Support for video/audio filters and quality presets**
+- **Hardware Acceleration (NVENC, VAAPI, QSV)**
+- **Remote input support (HTTP/HTTPS/RTMP/RTSP)**
 - Proper error handling with detailed context
 - Thread-safe configuration
 - Simple, intuitive API
@@ -41,19 +43,26 @@ bundle install
 ```ruby
 require "ffmpeg_core"
 
-# Load a video file
+# Load a video file or remote URL
 movie = FFmpegCore::Movie.new("input.mp4")
+# movie = FFmpegCore::Movie.new("http://example.com/video.mp4")
 
 # Get metadata
 movie.duration      # => 120.5 (seconds)
-movie.resolution    # => "1920x1080"
+movie.resolution    # => "1920x1080" (automatically swapped if rotated)
+movie.width         # => 1920
+movie.height        # => 1080
 movie.video_codec   # => "h264"
 movie.audio_codec   # => "aac"
 movie.frame_rate    # => 29.97
 movie.bitrate       # => 5000 (kb/s)
-movie.rotation      # => 90 (degrees)
-movie.aspect_ratio  # => "16:9"
 movie.valid?        # => true
+
+# Access detailed metadata via probe
+movie.probe.rotation      # => 90 (degrees)
+movie.probe.aspect_ratio  # => "16:9"
+movie.probe.video_profile # => "High"
+movie.probe.video_level   # => 41
 ```
 
 ### Transcoding
@@ -71,13 +80,76 @@ movie.transcode("output.mp4", {
   video_codec: "libx264",
   audio_codec: "aac",
   video_bitrate: "1000k",
+  audio_bitrate: "128k",
   resolution: "1280x720",
+  crop: { width: 500, height: 500, x: 10, y: 10 }, # Crop video
   video_filter: "scale=1280:-1,transpose=1", # Resize and rotate
+  audio_filter: "volume=0.5",                # Reduce volume
   preset: "slow",      # ffmpeg preset (ultrafast, fast, medium, slow, etc.)
   crf: 23              # Constant Rate Factor (0-51)
 })
 ```
 
+### Complex Filter Graphs & Stream Mapping
+
+Use structured APIs for `-filter_complex` and `-map` to build complex pipelines without raw string hacks.
+
+```ruby
+movie.transcode("out.mp4", {
+  filter_graph: [
+    "[0:v]crop=320:240:0:0[c]",
+    "[c]scale=640:480[outv]"
+  ],
+  maps: ["[outv]", "0:a"]
+})
+```
+
+### Hardware Acceleration
+
+Opt-in to hardware-accelerated encoding with automatic encoder detection and graceful fallback.
+
+```ruby
+# Automatically switches to h264_nvenc if available, falls back to libx264 otherwise
+movie.transcode("out.mp4", hwaccel: :nvenc)
+
+# Supports :nvenc, :vaapi, and :qsv
+movie.transcode("out.mp4", hwaccel: :vaapi)
+```
+
+### Using Filters
+
+FFmpegCore supports raw FFmpeg filter strings for both video (`video_filter` or `-vf`) and audio (`audio_filter` or `-af`).
+
+**Common Video Filters:**
+
+```ruby
+movie.transcode("output.mp4", {
+  # Scale to width 1280, keep aspect ratio
+  video_filter: "scale=1280:-1",
+
+  # Crop 100x100 starting at position (10,10)
+  video_filter: "crop=100:100:10:10",
+
+  # Rotate 90 degrees clockwise
+  video_filter: "transpose=1",
+
+  # Chain multiple filters (Scale then Rotate)
+  video_filter: "scale=1280:-1,transpose=1"
+})
+```
+
+**Common Audio Filters:**
+
+```ruby
+movie.transcode("output.mp4", {
+  # Increase volume by 50%
+  audio_filter: "volume=1.5",
+
+  # Fade in first 5 seconds
+  audio_filter: "afade=t=in:ss=0:d=5"
+})
+```
+
 ### Screenshots
 
 ```ruby
@@ -86,7 +158,7 @@ movie = FFmpegCore::Movie.new("input.mp4")
 # Extract screenshot at specific time
 movie.screenshot("thumbnail.jpg", seek_time: 5)
 
-# With resolution
+# With resolution and quality
 movie.screenshot("thumbnail.jpg", {
   seek_time: 10,
   resolution: "640x360",
@@ -106,7 +178,7 @@ end
 
 ## Error Handling
 
-FFmpegCore provides specific error classes for different failure scenarios:
+FFmpegCore provides specific error classes for different failure scenarios. All execution errors (transcoding, probing, screenshots) inherit from `FFmpegCore::ExecutionError`, which provides access to the command, exit status, and stderr output.
 
 ```ruby
 begin
@@ -115,9 +187,9 @@ begin
 rescue FFmpegCore::InvalidInputError => e
   # File doesn't exist or is not readable
   puts "Input error: #{e.message}"
-rescue FFmpegCore::TranscodingError => e
-  # FFmpeg transcoding failed
-  puts "Transcoding failed: #{e.message}"
+rescue FFmpegCore::ExecutionError => e
+  # Covers TranscodingError, ProbeError, and ScreenshotError
+  puts "Execution failed: #{e.message}"
   puts "Command: #{e.command}"
   puts "Exit status: #{e.exit_status}"
   puts "Stderr: #{e.stderr}"
@@ -129,14 +201,16 @@ end
 
 ### Error Classes
 
-| Error                             | Description                            |
-| --------------------------------- | -------------------------------------- |
-| `FFmpegCore::Error`               | Base error class                       |
-| `FFmpegCore::BinaryNotFoundError` | FFmpeg/FFprobe not found               |
-| `FFmpegCore::InvalidInputError`   | Input file doesn't exist or unreadable |
-| `FFmpegCore::ProbeError`          | Failed to extract metadata             |
-| `FFmpegCore::TranscodingError`    | FFmpeg transcoding failed              |
-| `FFmpegCore::ScreenshotError`     | Screenshot extraction failed           |
+| Error                             | Description                            | Parent |
+| --------------------------------- | -------------------------------------- | ------ |
+| `FFmpegCore::Error`               | Base error class                       | StandardError |
+| `FFmpegCore::BinaryNotFoundError` | FFmpeg/FFprobe not found               | Error |
+| `FFmpegCore::InvalidInputError`   | Input file doesn't exist or unreadable | Error |
+| `FFmpegCore::OutputError`         | Output file cannot be written          | Error |
+| `FFmpegCore::ExecutionError`      | Base for command execution errors      | Error |
+| `FFmpegCore::ProbeError`          | Failed to extract metadata             | ExecutionError |
+| `FFmpegCore::TranscodingError`    | FFmpeg transcoding failed              | ExecutionError |
+| `FFmpegCore::ScreenshotError`     | Screenshot extraction failed           | ExecutionError |
 
 ## Development
 
@@ -153,4 +227,4 @@ bundle exec rubocop
 
 ## License
 
-MIT License. See [LICENSE.txt](LICENSE.txt) for details.
+MIT License. See [LICENSE.txt](LICENSE.txt) for details.

data/lefthook.yml

@@ -0,0 +1,8 @@
+pre-commit:
+  parallel: true
+  jobs:
+    - name: rubocop
+      glob: "*.rb"
+      run: bundle exec rubocop --force-exclusion {staged_files}
+    - name: rspec
+      run: bundle exec rspec

data/lib/ffmpeg_core/configuration.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+require "fileutils"
+require "forwardable"
+require "open3"
+
 module FFmpegCore
   # Configuration for FFmpegCore library
   class Configuration
@@ -11,8 +15,30 @@ module FFmpegCore
       @timeout = 30 # seconds
     end
 
+    def encoders
+      @encoders ||= detect_encoders
+    end
+
     private
 
+    def detect_encoders
+      return Set.new unless @ffmpeg_binary
+
+      stdout, _stderr, status = Open3.capture3(@ffmpeg_binary, "-encoders")
+      return Set.new unless status.success?
+
+      encoders = Set.new
+      stdout.each_line do |line|
+        # Match lines like: " V..... libx264 ..."
+        if line =~ /^\s*[VAS][\w.]+\s+(\w+)/
+          encoders.add($1)
+        end
+      end
+      encoders
+    rescue
+      Set.new
+    end
+
     def detect_binary(name)
       # Check common locations
       paths = ENV["PATH"].split(File::PATH_SEPARATOR)

data/lib/ffmpeg_core/movie.rb

@@ -26,6 +26,9 @@ module FFmpegCore
     # @option options [String, Integer] :audio_bitrate Audio bitrate (e.g., "128k" or 128)
     # @option options [String] :resolution Resolution (e.g., "1280x720")
     # @option options [Integer, Float] :frame_rate Frame rate (e.g., 30)
+    # @option options [Array<String>, String] :filter_graph Complex filter graph (e.g., ["[0:v]crop=..."])
+    # @option options [Array<String>, String] :maps Stream maps (e.g., ["[outv]", "0:a"])
+    # @option options [Symbol] :hwaccel Hardware acceleration (:nvenc, :vaapi, :qsv)
     # @option options [Array<String>] :custom Custom FFmpeg flags
     # @yield [Float] Progress ratio (0.0 to 1.0)
     # @return [String] Path to transcoded file

data/lib/ffmpeg_core/probe.rb

@@ -39,16 +39,32 @@ module FFmpegCore
       video_stream&.dig("codec_name")
     end
 
+    def video_profile
+      video_stream&.dig("profile")
+    end
+
+    def video_level
+      video_stream&.dig("level")
+    end
+
     def audio_codec
       audio_stream&.dig("codec_name")
     end
 
     def width
-      video_stream&.dig("width")
+      val = video_stream&.dig("width")
+      return val unless val
+      return val if (rotation || 0) % 180 == 0
+
+      video_stream&.dig("height")
     end
 
     def height
-      video_stream&.dig("height")
+      val = video_stream&.dig("height")
+      return val unless val
+      return val if (rotation || 0) % 180 == 0
+
+      video_stream&.dig("width")
     end
 
     def frame_rate
@@ -79,6 +95,10 @@ module FFmpegCore
       tags = video_stream.fetch("tags", {})
       return tags["rotate"].to_i if tags["rotate"]
 
+      # Try side_data_list (common in some newer formats)
+      side_data = video_stream.fetch("side_data_list", []).find { |sd| sd.key?("rotation") }
+      return side_data["rotation"].to_i if side_data
+
       # Default to 0 if not found
       0
     end
@@ -102,6 +122,8 @@ module FFmpegCore
     end
 
     def validate_file!
+      return if %r{^(https?|rtmp|rtsp)://}.match?(path)
+
       raise InvalidInputError, "File does not exist: #{path}" unless File.exist?(path)
       raise InvalidInputError, "File is not readable: #{path}" unless File.readable?(path)
     end

data/lib/ffmpeg_core/transcoder.rb

@@ -25,6 +25,8 @@ module FFmpegCore
     private
 
     def validate_input!
+      return if %r{^(https?|rtmp|rtsp)://}.match?(input_path)
+
       raise InvalidInputError, "Input file does not exist: #{input_path}" unless File.exist?(input_path)
     end
 
@@ -36,6 +38,9 @@ module FFmpegCore
     def build_command
       cmd = [FFmpegCore.configuration.ffmpeg_binary]
 
+      # Apply HW Accel if requested
+      cmd += resolve_hwaccel_codec
+
       # Input file
       cmd += ["-i", input_path]
 
@@ -57,8 +62,16 @@ module FFmpegCore
       # Frame rate
       cmd += ["-r", options[:frame_rate].to_s] if options[:frame_rate]
 
-      # Video filter
-      cmd += ["-vf", options[:video_filter]] if options[:video_filter]
+      # Video filters
+      video_filters = []
+      video_filters << options[:video_filter] if options[:video_filter]
+
+      if options[:crop]
+        crop = options[:crop]
+        video_filters << "crop=#{crop[:width]}:#{crop[:height]}:#{crop[:x]}:#{crop[:y]}"
+      end
+
+      cmd += ["-vf", video_filters.join(",")] unless video_filters.empty?
 
       # Audio filter
       cmd += ["-af", options[:audio_filter]] if options[:audio_filter]
@@ -69,6 +82,21 @@ module FFmpegCore
       # Constant Rate Factor (CRF)
       cmd += ["-crf", options[:crf].to_s] if options[:crf]
 
+      # Filter Complex / Filter Graph
+      filter_graph = options[:filter_graph] || options[:filter_complex]
+      if filter_graph
+        graph_string = filter_graph.is_a?(Array) ? filter_graph.join(";") : filter_graph
+        cmd += ["-filter_complex", graph_string]
+      end
+
+      # Maps
+      maps = options[:maps] || options[:map]
+      if maps
+        Array(maps).each do |map|
+          cmd += ["-map", map]
+        end
+      end
+
       # Custom options (array of strings)
       cmd += options[:custom] if options[:custom]
 
@@ -137,5 +165,50 @@ module FFmpegCore
         end
       end
     end
+
+    def resolve_hwaccel_codec
+      return [] unless options[:hwaccel]
+
+      current_codec = options[:video_codec] || "libx264"
+      family = detect_codec_family(current_codec)
+      return [] unless family
+
+      hw_type = options[:hwaccel].to_sym
+      target_encoder = HW_ENCODERS.dig(family, hw_type)
+
+      if target_encoder && FFmpegCore.configuration.encoders.include?(target_encoder)
+        options[:video_codec] = target_encoder
+        return HW_FLAGS[hw_type] || []
+      end
+      []
+    end
+
+    def detect_codec_family(codec)
+      case codec.to_s
+      when /x264|h264|avc/i
+        :h264
+      when /x265|hevc/i
+        :hevc
+      end
+    end
+
+    HW_FLAGS = {
+      vaapi: ["-hwaccel", "vaapi", "-hwaccel_output_format", "vaapi"],
+      qsv: ["-hwaccel", "qsv"],
+      nvenc: ["-hwaccel", "cuda", "-hwaccel_output_format", "cuda"]
+    }.freeze
+
+    HW_ENCODERS = {
+      h264: {
+        nvenc: "h264_nvenc",
+        vaapi: "h264_vaapi",
+        qsv: "h264_qsv"
+      },
+      hevc: {
+        nvenc: "hevc_nvenc",
+        vaapi: "hevc_vaapi",
+        qsv: "hevc_qsv"
+      }
+    }.freeze
   end
 end

data/lib/ffmpeg_core/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FFmpegCore
-  VERSION = "0.2.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ffmpeg_core
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Alexey Poimtsev
@@ -21,6 +21,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- lefthook.yml
 - lib/ffmpeg_core.rb
 - lib/ffmpeg_core/configuration.rb
 - lib/ffmpeg_core/errors.rb
@@ -52,7 +53,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.4
 specification_version: 4
 summary: Modern Ruby wrapper for FFmpeg
 test_files: []