ffmpeg_core 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 8605d887cd2bf7b03dc1cc1dc06f004b797a694467f5376c361e432fdc648e50
+  data.tar.gz: 6d3308730d6ca3eceb6de5aa90053c39bcbcb0438a0faf4bc4a2a5b035ba7c66
+SHA512:
+  metadata.gz: 4bd3cc9dcdbae4104798cc0c6bd5ceef7f151f8a07aad0c33c6793f5c37928762f0c81baf0ce9ff943a4af17594ae4c9675db92e695ca73fd23ae0f2d93cfc43
+  data.tar.gz: 60e15449132609d881dfe136d7fe7d8e6777089a396578d79cbd0034bcd142e032c94a818ffc78d819fb724c49b7870451cabe2644e0d573e820afaf9d8815ad

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+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).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-01-14
+
+### Added
+
+- `FFmpegCore::Movie` - main API for working with video files
+- `FFmpegCore::Probe` - extract video metadata using ffprobe
+- `FFmpegCore::Transcoder` - transcode videos with various options
+- `FFmpegCore::Screenshot` - extract screenshots from videos
+- `FFmpegCore::Configuration` - thread-safe global configuration
+- Automatic ffmpeg/ffprobe binary detection
+- Comprehensive error classes with detailed context

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Alexey Poimtsev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,152 @@
+# FFmpegCore
+
+Modern Ruby wrapper for FFmpeg with clean API and proper error handling.
+
+## Features
+
+- Modern Ruby 3+ conventions
+- Zero runtime dependencies
+- Proper error handling with detailed context
+- Thread-safe configuration
+- Simple, intuitive API
+
+## Requirements
+
+- Ruby 3.2+
+- FFmpeg installed (`brew install ffmpeg` on macOS)
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "ffmpeg_core"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Usage
+
+### Basic Usage
+
+```ruby
+require "ffmpeg_core"
+
+# Load a video file
+movie = FFmpegCore::Movie.new("input.mp4")
+
+# Get metadata
+movie.duration      # => 120.5 (seconds)
+movie.resolution    # => "1920x1080"
+movie.video_codec   # => "h264"
+movie.audio_codec   # => "aac"
+movie.frame_rate    # => 29.97
+movie.bitrate       # => 5000 (kb/s)
+movie.valid?        # => true
+```
+
+### Transcoding
+
+```ruby
+movie = FFmpegCore::Movie.new("input.mp4")
+
+# Basic transcoding
+movie.transcode("output.mp4", video_codec: "libx264")
+
+# With options
+movie.transcode("output.mp4", {
+  video_codec: "libx264",
+  audio_codec: "aac",
+  video_bitrate: "1000k",
+  audio_bitrate: "128k",
+  resolution: "1280x720",
+  frame_rate: 30
+})
+
+# Custom FFmpeg flags
+movie.transcode("output.mp4", {
+  video_codec: "libx264",
+  custom: ["-preset", "fast", "-crf", "23"]
+})
+```
+
+### Screenshots
+
+```ruby
+movie = FFmpegCore::Movie.new("input.mp4")
+
+# Extract screenshot at specific time
+movie.screenshot("thumbnail.jpg", seek_time: 5)
+
+# With resolution
+movie.screenshot("thumbnail.jpg", {
+  seek_time: 10,
+  resolution: "640x360",
+  quality: 2  # 2-31, lower is better
+})
+```
+
+### Configuration
+
+```ruby
+FFmpegCore.configure do |config|
+  config.ffmpeg_binary = "/usr/local/bin/ffmpeg"
+  config.ffprobe_binary = "/usr/local/bin/ffprobe"
+  config.timeout = 60
+end
+```
+
+## Error Handling
+
+FFmpegCore provides specific error classes for different failure scenarios:
+
+```ruby
+begin
+  movie = FFmpegCore::Movie.new("input.mp4")
+  movie.transcode("output.mp4", video_codec: "libx264")
+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}"
+  puts "Command: #{e.command}"
+  puts "Exit status: #{e.exit_status}"
+  puts "Stderr: #{e.stderr}"
+rescue FFmpegCore::BinaryNotFoundError => e
+  # FFmpeg not installed
+  puts "FFmpeg not found: #{e.message}"
+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 |
+
+## Development
+
+```bash
+# Install dependencies
+bundle install
+
+# Run tests
+bundle exec rspec
+
+# Run linter
+bundle exec rubocop
+```
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt) for details.

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/ffmpeg_core/configuration.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module FFmpegCore
+  # Configuration for FFmpegCore library
+  class Configuration
+    attr_accessor :ffmpeg_binary, :ffprobe_binary, :timeout
+
+    def initialize
+      @ffmpeg_binary = detect_binary("ffmpeg")
+      @ffprobe_binary = detect_binary("ffprobe")
+      @timeout = 30 # seconds
+    end
+
+    private
+
+    def detect_binary(name)
+      # Check common locations
+      paths = ENV["PATH"].split(File::PATH_SEPARATOR)
+      paths.each do |path|
+        binary = File.join(path, name)
+        return binary if File.executable?(binary)
+      end
+
+      # Homebrew locations (macOS)
+      homebrew_paths = [
+        "/opt/homebrew/bin/#{name}", # Apple Silicon
+        "/usr/local/bin/#{name}" # Intel
+      ]
+      homebrew_paths.each do |path|
+        return path if File.executable?(path)
+      end
+
+      raise BinaryNotFoundError, "#{name} binary not found. Please install FFmpeg: brew install ffmpeg"
+    end
+  end
+
+  class << self
+    def configuration
+      @configuration_mutex ||= Mutex.new
+      @configuration_mutex.synchronize do
+        @configuration ||= Configuration.new
+      end
+    end
+
+    def configuration=(config)
+      @configuration_mutex ||= Mutex.new
+      @configuration_mutex.synchronize do
+        @configuration = config
+      end
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def reset_configuration!
+      @configuration_mutex ||= Mutex.new
+      @configuration_mutex.synchronize do
+        @configuration = Configuration.new
+      end
+    end
+  end
+end

data/lib/ffmpeg_core/errors.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module FFmpegCore
+  # Base error class for all FFmpegCore errors
+  class Error < StandardError; end
+
+  # Raised when ffmpeg/ffprobe binary is not found
+  class BinaryNotFoundError < Error; end
+
+  # Raised when ffmpeg/ffprobe execution fails
+  class ExecutionError < Error
+    attr_reader :command, :exit_status, :stdout, :stderr
+
+    def initialize(message, command: nil, exit_status: nil, stdout: nil, stderr: nil)
+      @command = command
+      @exit_status = exit_status
+      @stdout = stdout
+      @stderr = stderr
+      super(message)
+    end
+  end
+
+  # Raised when input file is invalid or cannot be read
+  class InvalidInputError < Error; end
+
+  # Raised when output file cannot be written
+  class OutputError < Error; end
+
+  # Raised when probe fails to extract metadata
+  class ProbeError < Error; end
+
+  # Raised when transcoding fails
+  class TranscodingError < ExecutionError; end
+
+  # Raised when screenshot extraction fails
+  class ScreenshotError < ExecutionError; end
+end

data/lib/ffmpeg_core/movie.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module FFmpegCore
+  # Modern API for working with video files
+  class Movie
+    extend Forwardable
+
+    attr_reader :path, :probe
+
+    def initialize(path)
+      @path = path
+      @probe = Probe.new(path)
+    end
+
+    # Delegate metadata methods to probe
+    def_delegators :probe, :duration, :bitrate, :video_codec, :audio_codec,
+      :width, :height, :frame_rate, :resolution, :valid?
+
+    # Transcode video with modern API
+    #
+    # @param output_path [String] Path to output file
+    # @param options [Hash] Transcoding 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 [String] :resolution Resolution (e.g., "1280x720")
+    # @option options [Integer, Float] :frame_rate Frame rate (e.g., 30)
+    # @option options [Array<String>] :custom Custom FFmpeg flags
+    # @return [String] Path to transcoded file
+    def transcode(output_path, options = {})
+      transcoder = Transcoder.new(path, output_path, options)
+      transcoder.run
+    end
+
+    # Extract screenshot from video
+    #
+    # @param output_path [String] Path to output image
+    # @param options [Hash] Screenshot options
+    # @option options [Integer, Float] :seek_time Time in seconds to seek to (default: 0)
+    # @option options [String] :resolution Resolution (e.g., "640x360")
+    # @option options [Integer] :quality JPEG quality 2-31, lower is better (default: 2)
+    # @return [String] Path to screenshot file
+    def screenshot(output_path, options = {})
+      screenshotter = Screenshot.new(path, output_path, options)
+      screenshotter.extract
+    end
+  end
+end

data/lib/ffmpeg_core/probe.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "json"
+require "open3"
+
+module FFmpegCore
+  # Probe video metadata using ffprobe
+  class Probe
+    attr_reader :path, :metadata
+
+    def initialize(path)
+      @path = path.to_s
+      @metadata = nil
+      validate_file!
+      probe!
+    end
+
+    # Duration in seconds
+    def duration
+      @metadata.dig("format", "duration")&.to_f
+    end
+
+    # Bitrate in kb/s
+    def bitrate
+      @metadata.dig("format", "bit_rate")&.to_i&./(1000)
+    end
+
+    # Video stream metadata
+    def video_stream
+      @video_stream ||= streams.find { |s| s["codec_type"] == "video" }
+    end
+
+    # Audio stream metadata
+    def audio_stream
+      @audio_stream ||= streams.find { |s| s["codec_type"] == "audio" }
+    end
+
+    def video_codec
+      video_stream&.dig("codec_name")
+    end
+
+    def audio_codec
+      audio_stream&.dig("codec_name")
+    end
+
+    def width
+      video_stream&.dig("width")
+    end
+
+    def height
+      video_stream&.dig("height")
+    end
+
+    def frame_rate
+      return nil unless video_stream
+
+      # Parse frame rate (e.g., "30000/1001" or "30")
+      r_frame_rate = video_stream["r_frame_rate"]
+      return nil unless r_frame_rate
+
+      if r_frame_rate.include?("/")
+        num, den = r_frame_rate.split("/").map(&:to_f)
+        num / den
+      else
+        r_frame_rate.to_f
+      end
+    end
+
+    def resolution
+      return nil unless width && height
+      "#{width}x#{height}"
+    end
+
+    def valid?
+      !video_stream.nil?
+    end
+
+    private
+
+    def streams
+      @metadata.fetch("streams", [])
+    end
+
+    def validate_file!
+      raise InvalidInputError, "File does not exist: #{path}" unless File.exist?(path)
+      raise InvalidInputError, "File is not readable: #{path}" unless File.readable?(path)
+    end
+
+    def probe!
+      command = [
+        FFmpegCore.configuration.ffprobe_binary,
+        "-v", "quiet",
+        "-print_format", "json",
+        "-show_format",
+        "-show_streams",
+        path
+      ]
+
+      stdout, stderr, status = Open3.capture3(*command)
+
+      unless status.success?
+        raise ProbeError.new(
+          "ffprobe failed for #{path}",
+          command: command.join(" "),
+          exit_status: status.exitstatus,
+          stdout: stdout,
+          stderr: stderr
+        )
+      end
+
+      @metadata = JSON.parse(stdout)
+    rescue JSON::ParserError => e
+      raise ProbeError, "Failed to parse ffprobe output: #{e.message}"
+    end
+  end
+end

data/lib/ffmpeg_core/screenshot.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module FFmpegCore
+  # Extract screenshots from video files
+  class Screenshot
+    attr_reader :input_path, :output_path, :options
+
+    def initialize(input_path, output_path, options = {})
+      @input_path = input_path.to_s
+      @output_path = output_path.to_s
+      @options = options
+    end
+
+    def extract
+      validate_input!
+      ensure_output_directory!
+
+      command = build_command
+      execute_command(command)
+    end
+
+    private
+
+    def validate_input!
+      raise InvalidInputError, "Input file does not exist: #{input_path}" unless File.exist?(input_path)
+    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]
+
+      # Seek to timestamp (before input for faster processing)
+      if options[:seek_time]
+        cmd += ["-ss", options[:seek_time].to_s]
+      end
+
+      # Input file
+      cmd += ["-i", input_path]
+
+      # Number of frames to extract (default: 1)
+      cmd += ["-vframes", "1"]
+
+      # Resolution
+      if options[:resolution]
+        cmd += ["-s", options[:resolution]]
+      end
+
+      # Quality (2-31, lower is better, default: 2)
+      quality = options[:quality] || 2
+      cmd += ["-q:v", quality.to_s]
+
+      # Overwrite output file
+      cmd += ["-y"]
+
+      # Output file
+      cmd += [output_path]
+
+      cmd
+    end
+
+    def execute_command(command)
+      stdout, stderr, status = Open3.capture3(*command)
+
+      unless status.success?
+        raise ScreenshotError.new(
+          "Screenshot extraction failed",
+          command: command.join(" "),
+          exit_status: status.exitstatus,
+          stdout: stdout,
+          stderr: stderr
+        )
+      end
+
+      output_path
+    end
+  end
+end

data/lib/ffmpeg_core/transcoder.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "open3"
+require "shellwords"
+
+module FFmpegCore
+  # Execute FFmpeg transcoding operations
+  class Transcoder
+    attr_reader :input_path, :output_path, :options
+
+    def initialize(input_path, output_path, options = {})
+      @input_path = input_path.to_s
+      @output_path = output_path.to_s
+      @options = options
+    end
+
+    def run
+      validate_input!
+      ensure_output_directory!
+
+      command = build_command
+      execute_command(command)
+    end
+
+    private
+
+    def validate_input!
+      raise InvalidInputError, "Input file does not exist: #{input_path}" unless File.exist?(input_path)
+    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 file
+      cmd += ["-i", input_path]
+
+      # Video codec
+      if options[:video_codec]
+        cmd += ["-c:v", options[:video_codec]]
+      end
+
+      # Audio codec
+      if options[:audio_codec]
+        cmd += ["-c:a", options[:audio_codec]]
+      end
+
+      # Video bitrate
+      if options[:video_bitrate]
+        cmd += ["-b:v", normalize_bitrate(options[:video_bitrate])]
+      end
+
+      # Audio bitrate
+      if options[:audio_bitrate]
+        cmd += ["-b:a", normalize_bitrate(options[:audio_bitrate])]
+      end
+
+      # Resolution
+      if options[:resolution]
+        cmd += ["-s", options[:resolution]]
+      end
+
+      # Frame rate
+      if options[:frame_rate]
+        cmd += ["-r", options[:frame_rate].to_s]
+      end
+
+      # Custom options (array of strings)
+      if options[:custom]
+        cmd += options[:custom]
+      end
+
+      # Overwrite output file
+      cmd += ["-y"]
+
+      # Output file
+      cmd += [output_path]
+
+      cmd
+    end
+
+    def normalize_bitrate(bitrate)
+      # Convert various formats to ffmpeg format
+      # "1000k" -> "1000k"
+      # 1000 -> "1000k"
+      # "1M" -> "1M"
+      return bitrate.to_s if bitrate.to_s.match?(/\d+[kKmM]/)
+      "#{bitrate}k"
+    end
+
+    def execute_command(command)
+      stdout, stderr, status = Open3.capture3(*command)
+
+      unless status.success?
+        raise TranscodingError.new(
+          "FFmpeg transcoding failed",
+          command: command.join(" "),
+          exit_status: status.exitstatus,
+          stdout: stdout,
+          stderr: stderr
+        )
+      end
+
+      output_path
+    end
+  end
+end

data/lib/ffmpeg_core/version.rb

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

data/lib/ffmpeg_core.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "forwardable"
+
+# FFmpegCore - Modern Ruby wrapper for FFmpeg
+#
+# A clean, well-tested alternative to streamio-ffmpeg with:
+# - Modern Ruby 3+ conventions
+# - Proper error handling with detailed context
+# - Zero Rails dependencies (gem-ready architecture)
+#
+# @example Basic usage
+#   movie = FFmpegCore::Movie.new("input.mp4")
+#   movie.transcode("output.mp4", video_codec: "libx264", video_bitrate: "1000k")
+#   movie.screenshot("thumb.jpg", seek_time: 1, resolution: "640x360")
+module FFmpegCore
+end
+
+# Load core components
+require_relative "ffmpeg_core/version"
+require_relative "ffmpeg_core/errors"
+require_relative "ffmpeg_core/configuration"
+require_relative "ffmpeg_core/probe"
+require_relative "ffmpeg_core/transcoder"
+require_relative "ffmpeg_core/screenshot"
+require_relative "ffmpeg_core/movie"

data/sig/ffmpeg_core.rbs

@@ -0,0 +1,4 @@
+module FfmpegCore
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,58 @@
+--- !ruby/object:Gem::Specification
+name: ffmpeg_core
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Alexey Poimtsev
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: A clean, well-tested FFmpeg wrapper with modern Ruby conventions, proper
+  error handling, and zero dependencies.
+email:
+- alexey.poimtsev@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/ffmpeg_core.rb
+- lib/ffmpeg_core/configuration.rb
+- lib/ffmpeg_core/errors.rb
+- lib/ffmpeg_core/movie.rb
+- lib/ffmpeg_core/probe.rb
+- lib/ffmpeg_core/screenshot.rb
+- lib/ffmpeg_core/transcoder.rb
+- lib/ffmpeg_core/version.rb
+- sig/ffmpeg_core.rbs
+homepage: https://github.com/alec-c4/ffmpeg_core
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/alec-c4/ffmpeg_core
+  source_code_uri: https://github.com/alec-c4/ffmpeg_core
+  changelog_uri: https://github.com/alec-c4/ffmpeg_core/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.3
+specification_version: 4
+summary: Modern Ruby wrapper for FFmpeg
+test_files: []