ffmpeg_core 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bb9323f5aae7b7f162d4b43f219f14506af5fa012e033451a2021e92bec14128
-  data.tar.gz: 7164b154e6b542e2179f430418cd3b42fb68cc48a5dff62a679b13eb135b3de7
+  metadata.gz: 83185cde1635bd7362c737cba6da5c723be5407cd7457ea5bbac2e0b43206365
+  data.tar.gz: bf4dea2ee0d08d1e8af7b8193cef697f2b8dc1fcda8f5d86efed89e1d23c8f4e
 SHA512:
-  metadata.gz: f97a26864b497d77ae8b862daa0b45154f038cbc94dfbf56703a4879ccbac680b294acdacf35d20538fb736d046dbd85c55514bc6d7e7a8c0d6c41030878f40d
-  data.tar.gz: 5235e82f757aa787cb76dbed3af50a5bd4eff074c9476918f90d9d8c8187f658979a6ca0b773d762569f631394326c27c45d45d265f1a0e13f9eb2890a1bba26
+  metadata.gz: fbe0cf4fd2b09c72c143aeeb1281889f7291e816d7602c6d12852503f647fbc71100e106cf41c33c5e76b9728258d3ecc547b1407632748b6512e92086376265
+  data.tar.gz: 056ea62e71626ac7969cee7242fb14936b15aa9098311b631c36f14c87c61289f6da48a41e99e7745fb7032965a3550d9f1c59e56969b43bba6af33f4b25977f

data/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.6.0] - 2026-04-14
+
+### Added
+
+- **Compositor — multi-input video composition:**
+  - New `FFmpegCore::Compositor` class for operations requiring multiple input files in a single FFmpeg command
+  - Accepts an array of local paths or remote URLs as `input_paths`
+  - `:filter_complex` option (String or Array — array elements are joined with `;`)
+  - `:maps` option for stream mapping
+  - Progress reporting via block (requires `:duration`)
+  - Typical use cases: overlay (picture-in-picture), concatenation, side-by-side (`hstack`)
+  - README updated with usage examples
+
 ## [0.5.0] - 2026-04-13
 
 ### Added

data/README.md

@@ -11,12 +11,25 @@ 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)**
+- **Hardware Acceleration (NVENC, VAAPI, QSV, Vulkan AV1, D3D12)**
 - **Remote input support (HTTP/HTTPS/RTMP/RTSP)**
+- **Rich metadata: chapters, subtitles, EXIF, audio properties**
+- **Video operations: cut, audio extraction, batch screenshots**
+- **Multi-input composition: overlay, concatenation, side-by-side**
 - Proper error handling with detailed context
 - Thread-safe configuration
 - Simple, intuitive API
 
+## FFmpeg Version Requirements
+
+| Feature | Minimum FFmpeg version |
+|---|---|
+| Core transcoding, probing | Any recent version |
+| AV1 hardware encoding (Vulkan) | 8.0+ |
+| EXIF metadata parsing | 8.1+ |
+| D3D12 hardware acceleration | 8.1+ |
+| Chapter metadata (`chapters`) | Any (via `-show_chapters`) |
+
 ## Requirements
 
 - Ruby 3.2+
@@ -47,7 +60,7 @@ require "ffmpeg_core"
 movie = FFmpegCore::Movie.new("input.mp4")
 # movie = FFmpegCore::Movie.new("http://example.com/video.mp4")
 
-# Get metadata
+# Basic metadata
 movie.duration      # => 120.5 (seconds)
 movie.resolution    # => "1920x1080" (automatically swapped if rotated)
 movie.width         # => 1920
@@ -57,12 +70,32 @@ movie.audio_codec   # => "aac"
 movie.frame_rate    # => 29.97
 movie.bitrate       # => 5000 (kb/s)
 movie.valid?        # => true
+movie.has_video?    # => true
+movie.has_audio?    # => true
 
-# Access detailed metadata via probe
+# Video stream details
 movie.probe.rotation      # => 90 (degrees)
 movie.probe.aspect_ratio  # => "16:9"
 movie.probe.video_profile # => "High"
 movie.probe.video_level   # => 41
+movie.probe.pixel_format  # => "yuv420p"
+
+# Audio stream details
+movie.probe.audio_sample_rate    # => 48000
+movie.probe.audio_channels       # => 2
+movie.probe.audio_channel_layout # => "stereo"
+movie.probe.audio_streams        # => [{ "codec_type" => "audio", ... }, ...]
+
+# Subtitles and chapters
+movie.probe.subtitle_streams # => [{ "codec_name" => "subrip", ... }]
+movie.probe.chapters         # => [{ "tags" => { "title" => "Intro" }, ... }]
+
+# File-level tags and EXIF (FFmpeg 8.1+ for full EXIF support)
+movie.probe.tags  # => { "title" => "My Video", "artist" => "Author" }
+movie.probe.exif  # => { "creation_time" => "2024-06-15T14:30:00Z", ... }
+
+# Container format
+movie.probe.format_name # => "mov,mp4,m4a,3gp,3g2,mj2"
 ```
 
 ### Transcoding
@@ -104,18 +137,103 @@ movie.transcode("out.mp4", {
 })
 ```
 
+### Multi-Input Composition
+
+Use `FFmpegCore::Compositor` when you need multiple input files in a single FFmpeg command — overlay, concatenation, side-by-side, and any other `-filter_complex` operation.
+
+```ruby
+# Overlay (picture-in-picture): place overlay.mp4 on top of background.mp4
+FFmpegCore::Compositor.new(
+  ["background.mp4", "overlay.mp4"],
+  "output.mp4",
+  filter_complex: "[0:v][1:v]overlay=10:10[v]",
+  maps: ["[v]", "0:a"]
+).run
+
+# Concatenate two clips sequentially
+FFmpegCore::Compositor.new(
+  ["part1.mp4", "part2.mp4"],
+  "output.mp4",
+  filter_complex: "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1[v][a]",
+  maps: ["[v]", "[a]"]
+).run
+
+# Side-by-side (horizontal stack)
+FFmpegCore::Compositor.new(
+  ["left.mp4", "right.mp4"],
+  "output.mp4",
+  filter_complex: "[0:v][1:v]hstack[v]",
+  maps: ["[v]", "0:a"]
+).run
+
+# With progress reporting (requires :duration)
+FFmpegCore::Compositor.new(
+  ["a.mp4", "b.mp4"],
+  "output.mp4",
+  filter_complex: "[0:v][1:v]overlay[v]",
+  maps: ["[v]", "0:a"],
+  duration: 120.0
+).run do |progress|
+  puts "#{(progress * 100).round}%"
+end
+```
+
+> **Note:** Stream indices (`[0:v]`, `[1:v]`, etc.) correspond to the position of each file in the input array.
+
+### Cutting / Trimming
+
+Lossless trim using stream copy — no re-encoding, nearly instant:
+
+```ruby
+# Trim by start time + duration
+movie.cut("clip.mp4", start_time: 30, duration: 60)
+
+# Trim by start and end time
+movie.cut("clip.mp4", start_time: 30, end_time: 90)
+```
+
+> **Note:** `-c copy` seeks to the nearest keyframe. For frame-accurate trimming, use `transcode` with `custom: ["-ss", "30", "-to", "90"]`.
+
+### Audio Extraction
+
+```ruby
+# Extract audio with automatic codec detection from file extension
+movie.extract_audio("audio.aac")
+
+# Specify codec explicitly
+movie.extract_audio("audio.mp3", codec: "libmp3lame")
+movie.extract_audio("audio.opus", codec: "libopus")
+```
+
+### Multiple Screenshots
+
+```ruby
+# Extract 5 screenshots distributed evenly across the video
+paths = movie.screenshots("thumbs/", count: 5)
+# => ["thumbs/screenshot_001.jpg", ..., "thumbs/screenshot_005.jpg"]
+```
+
 ### 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)
+# H.264 / HEVC — classic accelerators
+movie.transcode("out.mp4", hwaccel: :nvenc)           # NVIDIA CUDA
+movie.transcode("out.mp4", hwaccel: :vaapi)           # Linux VAAPI
+movie.transcode("out.mp4", hwaccel: :qsv)             # Intel Quick Sync
+
+# AV1 — requires FFmpeg 8.0+
+movie.transcode("out.mp4", video_codec: "libaom-av1", hwaccel: :nvenc)   # NVIDIA
+movie.transcode("out.mp4", video_codec: "libaom-av1", hwaccel: :vaapi)   # VAAPI
+movie.transcode("out.mp4", video_codec: "libaom-av1", hwaccel: :vulkan)  # Vulkan compute
+
+# D3D12 — Windows only, requires FFmpeg 8.1+
+movie.transcode("out.mp4", hwaccel: :d3d12)
 ```
 
+All accelerators gracefully fall back to software encoding if the hardware encoder is not available.
+
 ### Using Filters
 
 FFmpegCore supports raw FFmpeg filter strings for both video (`video_filter` or `-vf`) and audio (`audio_filter` or `-af`).

data/lib/ffmpeg_core/compositor.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module FFmpegCore
+  # Execute FFmpeg operations with multiple input files
+  #
+  # @example Overlay (picture-in-picture)
+  #   FFmpegCore::Compositor.new(
+  #     ["background.mp4", "overlay.mp4"],
+  #     "output.mp4",
+  #     filter_complex: "[0:v][1:v]overlay=10:10[v]",
+  #     maps: ["[v]", "0:a"]
+  #   ).run
+  #
+  # @example Concatenate
+  #   FFmpegCore::Compositor.new(
+  #     ["part1.mp4", "part2.mp4"],
+  #     "output.mp4",
+  #     filter_complex: "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1[v][a]",
+  #     maps: ["[v]", "[a]"]
+  #   ).run
+  class Compositor
+    attr_reader :input_paths, :output_path, :options
+
+    # @param input_paths [Array<String>] Paths or URLs to input files (at least one required)
+    # @param output_path [String] Path to output file
+    # @param options [Hash] Compositing options
+    # @option options [String] :video_codec Video codec (e.g., "libx264")
+    # @option options [String] :audio_codec Audio codec (e.g., "aac")
+    # @option options [String, Integer] :video_bitrate Video bitrate (e.g., "1000k" or 1000)
+    # @option options [String, Integer] :audio_bitrate Audio bitrate (e.g., "128k" or 128)
+    # @option options [Array<String>, String] :filter_complex FFmpeg filter graph referencing input streams by index
+    #   (e.g., "[0:v][1:v]overlay=0:0[v]"). Array elements are joined with semicolons.
+    # @option options [Array<String>, String] :maps Stream maps selecting outputs from the filter graph
+    #   (e.g., ["[v]", "0:a"])
+    # @option options [Float] :duration Total duration in seconds, used for progress reporting
+    # @option options [Array<String>] :custom Raw FFmpeg flags appended verbatim (e.g., ["-shortest"])
+    # @raise [ArgumentError] if input_paths is empty
+    def initialize(input_paths, output_path, options = {})
+      raise ArgumentError, "At least one input path is required" if Array(input_paths).empty?
+
+      @input_paths = Array(input_paths).map(&:to_s)
+      @output_path = output_path.to_s
+      @options = options
+    end
+
+    # Run the FFmpeg compositing command
+    #
+    # @yield [Float] Progress ratio from 0.0 to 1.0 (requires :duration option)
+    # @return [String] Path to the output file
+    # @raise [InvalidInputError] if a local input file does not exist
+    # @raise [TranscodingError] if FFmpeg exits with a non-zero status
+    def run(&block)
+      validate_inputs!
+      ensure_output_directory!
+
+      command = build_command
+      execute_command(command, &block)
+    end
+
+    private
+
+    def validate_inputs!
+      input_paths.each do |path|
+        next if %r{^(https?|rtmp|rtsp)://}.match?(path)
+
+        raise InvalidInputError, "Input file does not exist: #{path}" unless File.exist?(path)
+      end
+    end
+
+    def ensure_output_directory!
+      output_dir = File.dirname(output_path)
+      FileUtils.mkdir_p(output_dir) unless Dir.exist?(output_dir)
+    end
+
+    def build_command
+      cmd = [FFmpegCore.configuration.ffmpeg_binary]
+
+      input_paths.each { |path| cmd += ["-i", path] }
+
+      cmd += ["-c:v", options[:video_codec]] if options[:video_codec]
+      cmd += ["-c:a", options[:audio_codec]] if options[:audio_codec]
+      cmd += ["-b:v", normalize_bitrate(options[:video_bitrate])] if options[:video_bitrate]
+      cmd += ["-b:a", normalize_bitrate(options[:audio_bitrate])] if options[:audio_bitrate]
+
+      filter = options[:filter_complex] || options[:filter_graph]
+      if filter
+        cmd += ["-filter_complex", filter.is_a?(Array) ? filter.join(";") : filter]
+      end
+
+      maps = options[:maps] || options[:map]
+      Array(maps).each { |map| cmd += ["-map", map] } if maps
+
+      cmd += options[:custom] if options[:custom]
+      cmd += ["-y", output_path]
+      cmd
+    end
+
+    def normalize_bitrate(bitrate)
+      return bitrate.to_s if bitrate.to_s.match?(/\d+[kKmM]/)
+
+      "#{bitrate}k"
+    end
+
+    def execute_command(command, &block)
+      error_log = []
+
+      Open3.popen3(*command) do |_stdin, _stdout, stderr, wait_thr|
+        stderr.each_line("\r") do |line|
+          clean_line = line.strip
+          next if clean_line.empty?
+
+          error_log << clean_line
+          error_log.shift if error_log.size > 20
+          parse_progress(line, &block) if block
+        end
+
+        status = wait_thr.value
+        unless status.success?
+          raise TranscodingError.new(
+            "FFmpeg compositing failed",
+            command: command.join(" "),
+            exit_status: status.exitstatus,
+            stdout: "",
+            stderr: error_log.join("\n")
+          )
+        end
+      end
+
+      output_path
+    end
+
+    def parse_progress(line)
+      return unless line =~ /time=(\d{2}):(\d{2}):(\d{2}\.\d{2})/
+
+      current_time = $1.to_i * 3600 + $2.to_i * 60 + $3.to_f
+      duration = options[:duration]
+      yield([current_time / duration.to_f, 1.0].min) if duration && duration.to_f > 0
+    end
+  end
+end

data/lib/ffmpeg_core/version.rb

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

data/lib/ffmpeg_core.rb

@@ -26,4 +26,5 @@ require_relative "ffmpeg_core/transcoder"
 require_relative "ffmpeg_core/screenshot"
 require_relative "ffmpeg_core/clipper"
 require_relative "ffmpeg_core/audio_extractor"
+require_relative "ffmpeg_core/compositor"
 require_relative "ffmpeg_core/movie"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ffmpeg_core
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Alexey Poimtsev
@@ -39,6 +39,7 @@ files:
 - lib/ffmpeg_core.rb
 - lib/ffmpeg_core/audio_extractor.rb
 - lib/ffmpeg_core/clipper.rb
+- lib/ffmpeg_core/compositor.rb
 - lib/ffmpeg_core/configuration.rb
 - lib/ffmpeg_core/errors.rb
 - lib/ffmpeg_core/movie.rb