feat!: add non-blocking popen3 methods (#9)

* feat!: add non-blocking popen3 methods

BREAKING CHANGE: Dropped support for Ruby 3.1.

* docs: update docblocks on some methods

* fix: resolve RuboCop errors in the DASH preset class

* fix: resolve encoding issues in capture3 methods

* ci: add Ruby 3.4 to the test matrix

* docs: add CHANGELOG entry for 7.0.0-beta

* chore: update version to 7.0.0-beta.1 and document changes

Author: bajankristof

.github/workflows/ci.lint.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Set up Ruby
         uses: ruby/setup-ruby@v1
         with:
-          ruby-version: '3.3'
+          ruby-version: '3.2'
           bundler-cache: true
           rubygems: latest
 

.github/workflows/ci.test.yml

@@ -14,7 +14,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        ruby-version: ['3.1', '3.2', '3.3']
+        ruby-version: ['3.2', '3.3', '3.4']
         ffmpeg-version: ['release', '6.0.1', '5.1.1', '4.4.1']
 
         include:

.rubocop.yml

@@ -3,7 +3,7 @@ inherit_from: .rubocop_todo.yml
 AllCops:
   NewCops: enable
   SuggestExtensions: false
-  TargetRubyVersion: 3.1
+  TargetRubyVersion: 3.2
 
 Metrics/AbcSize:
   Enabled: false

CHANGELOG

@@ -1,4 +1,30 @@
+== 7.0.0-beta.1 2025-01-22
+
+Fixes:
+* Some incorrect or incomplete documentation comments.
+
+Improvements:
+* Added non-blocking popen3 methods for both ffmpeg and ffprobe.
+* Improved IO handling for ffmpeg and ffprobe processes.
+
+Breaking Changes:
+* Dropped support for Ruby 3.1, Ruby 3.2 is now the minimum supported version.
+
+== 7.0.0-beta 2024-11-29
+
+Breaking Changes:
+* Added new, more powerful (though less extensible) DSL to build ffmpeg commands.
+* Introduced new concept of long-lived presets and transcoders.
+* Removed full output storage during the transcoding process.
+* Added built-in presets that can be used out-of-the-box:
+  * H.264 360p all the way up to 4K resolution.
+  * AAC 128k all the way up to 320k bit rate.
+  * DASH H.264 360p all the way up to 4K resolution.
+  * DASH AAC 128k all the way up to 320k bit rate.
+* Dropped support for Ruby 3.0, Ruby 3.1 is now the minimum supported version.
+
 == 6.1.2 2024-11-07
+
 Fixes:
 * Calculate rotation correctly for media files with multiple side data elements
 
@@ -9,6 +35,7 @@ Fixes:
 
 == 6.1.0 2024-10-24
 
+Improvements:
 * Added new `default?` and `attached_pic?` helper methods to FFMPEG::Stream objects
 * Added new `audio_with_attached_pic?` helper method to FFMPEG::Media objects
 

ffmpeg.gemspec

@@ -13,7 +13,7 @@ Gem::Specification.new do |s|
   s.homepage    = 'https://github.com/instructure/ffmpeg'
   s.summary     = 'Wraps ffmpeg to read metadata and transcodes videos.'
 
-  s.required_ruby_version = '>= 3.1'
+  s.required_ruby_version = '>= 3.2'
 
   s.add_dependency('multi_json', '~> 1.8')
 

lib/ffmpeg.rb

@@ -3,7 +3,6 @@
 $LOAD_PATH.unshift File.dirname(__FILE__)
 
 require 'logger'
-require 'open3'
 
 require_relative 'ffmpeg/command_args'
 require_relative 'ffmpeg/errors'
@@ -38,18 +37,20 @@
   end
 end
 
-# The FFMPEG module allows you to customise the behaviour of the FFMPEG library.
+# The FFMPEG module allows you to customise the behaviour of the FFMPEG library,
+# and provides a set of methods to directly interact with the ffmpeg and ffprobe binaries.
 #
 # @example
 #   FFMPEG.logger = Logger.new($stdout)
 #   FFMPEG.io_timeout = 60
+#   FFMPEG.io_encoding = Encoding::UTF_8
 #   FFMPEG.ffmpeg_binary = '/usr/local/bin/ffmpeg'
 #   FFMPEG.ffprobe_binary = '/usr/local/bin/ffprobe'
 module FFMPEG
   SIGKILL = RUBY_PLATFORM =~ /(win|w)(32|64)$/ ? 1 : 'SIGKILL'
 
   class << self
-    attr_writer :logger, :io_timeout
+    attr_writer :logger
 
     # Get the FFMPEG logger.
     #
@@ -59,14 +60,29 @@ def logger
     end
 
     # Get the timeout that's used when waiting for ffmpeg output.
-    # This timeout is used by ffmpeg_execute calls and the Transcoder class.
     # Defaults to 30 seconds.
     #
     # @return [Integer]
     def io_timeout
-      return @io_timeout if defined?(@io_timeout)
+      FFMPEG::IO.timeout
+    end
+
+    # Set the timeout that's used when waiting for ffmpeg output.
+    def io_timeout=(timeout)
+      FFMPEG::IO.timeout = timeout
+    end
+
+    # Get the encoding that's used when reading ffmpeg output.
+    # Defaults to UTF-8.
+    #
+    # @return [Encoding]
+    def io_encoding
+      FFMPEG::IO.encoding
+    end
 
-      @io_timeout = 30
+    # Set the encoding that's used when reading ffmpeg output.
+    def io_encoding=(encoding)
+      FFMPEG::IO.encoding = encoding
     end
 
     # Set the path to the ffmpeg binary.
@@ -93,34 +109,27 @@ def ffmpeg_binary
 
     # Safely captures the standard output and the standard error of the ffmpeg command.
     #
-    # @return [Array] The standard output, the standard error, and the process status.
+    # @param args [Array<String>] The arguments to pass to ffmpeg.
+    # @return [Array<String, Process::Status>] The standard output, the standard error, and the process status.
     def ffmpeg_capture3(*args)
       logger.debug(self) { "ffmpeg -y #{args.join(' ')}" }
-      stdout, stderr, status = Open3.capture3(ffmpeg_binary, '-y', *args)
-      FFMPEG::IO.encode!(stdout)
-      FFMPEG::IO.encode!(stderr)
-      [stdout, stderr, status]
+      FFMPEG::IO.capture3(ffmpeg_binary, '-y', *args)
     end
 
     # Starts a new ffmpeg process with the given arguments.
     # Yields the standard input, the standard output
     # and the standard error streams, as well as the child process
     # to the specified block.
     #
+    # @param args [Array<String>] The arguments to pass to ffmpeg.
     # @yieldparam stdin (+IO+) The standard input stream.
     # @yieldparam stdout (+FFMPEG::IO+) The standard output stream.
     # @yieldparam stderr (+FFMPEG::IO+) The standard error stream.
     # @yieldparam wait_thr (+Thread+) The child process thread.
-    # @return [void]
-    def ffmpeg_popen3(*args, &block)
+    # @return [Process::Status, Array<IO, Thread>]
+    def ffmpeg_popen3(*args, &)
       logger.debug(self) { "ffmpeg -y #{args.join(' ')}" }
-      Open3.popen3(ffmpeg_binary, '-y', *args) do |stdin, stdout, stderr, wait_thr|
-        block.call(stdin, FFMPEG::IO.new(stdout), FFMPEG::IO.new(stderr), wait_thr)
-      rescue StandardError
-        wait_thr.kill
-        wait_thr.join
-        raise
-      end
+      FFMPEG::IO.popen3(ffmpeg_binary, '-y', *args, &)
     end
 
     # Execute a ffmpeg command.
@@ -131,12 +140,13 @@ def ffmpeg_popen3(*args, &block)
     # @return [Process::Status]
     def ffmpeg_execute(*args, reporters: [Reporters::Progress])
       ffmpeg_popen3(*args) do |_stdin, _stdout, stderr, wait_thr|
-        stderr.each do |line|
+        stderr.each(chomp: true) do |line|
           next unless block_given?
 
           reporter = reporters.find { |r| r.match?(line) }
           reporter ||= Reporters::Output
           report = reporter.new(line)
+
           yield report
         end
 
@@ -169,35 +179,28 @@ def ffprobe_binary=(path)
 
     # Safely captures the standard output and the standard error of the ffmpeg command.
     #
-    # @return [Array] The standard output, the standard error, and the process status.
+    # @param args [Array<String>] The arguments to pass to ffprobe.
+    # @return [Array<String, Process::Status>] The standard output, the standard error, and the process status.
     # @raise [Errno::ENOENT] If the ffprobe binary cannot be found.
     def ffprobe_capture3(*args)
       logger.debug(self) { "ffprobe -y #{args.join(' ')}" }
-      stdout, stderr, status = Open3.capture3(ffprobe_binary, '-y', *args)
-      FFMPEG::IO.encode!(stdout)
-      FFMPEG::IO.encode!(stderr)
-      [stdout, stderr, status]
+      FFMPEG::IO.capture3(ffprobe_binary, '-y', *args)
     end
 
     # Starts a new ffprobe process with the given arguments.
     # Yields the standard input, the standard output
     # and the standard error streams, as well as the child process
     # to the specified block.
     #
+    # @param args [Array<String>] The arguments to pass to ffprobe.
     # @yieldparam stdin (+IO+) The standard input stream.
     # @yieldparam stdout (+FFMPEG::IO+) The standard output stream.
     # @yieldparam stderr (+FFMPEG::IO+) The standard error stream.
-    # @return [void]
+    # @return [Process::Status, Array<IO, Thread>]
     # @raise [Errno::ENOENT] If the ffprobe binary cannot be found.
-    def ffprobe_popen3(*args, &block)
+    def ffprobe_popen3(*args, &)
       logger.debug(self) { "ffprobe -y #{args.join(' ')}" }
-      Open3.popen3(ffprobe_binary, '-y', *args) do |stdin, stdout, stderr, wait_thr|
-        block.call(stdin, FFMPEG::IO.new(stdout), FFMPEG::IO.new(stderr), wait_thr)
-      rescue StandardError
-        wait_thr.kill
-        wait_thr.join
-        raise
-      end
+      FFMPEG::IO.popen3(ffprobe_binary, '-y', *args, &)
     end
 
     # Cross-platform way of finding an executable in the $PATH.

lib/ffmpeg/io.rb

@@ -1,94 +1,75 @@
 # frozen_string_literal: true
 
 require 'English'
-require 'timeout'
-
-require_relative 'timeout'
+require 'open3'
 
 module FFMPEG
-  # The IO class is a simple wrapper around IO objects that adds a timeout
-  # to all read operations and fixes encoding issues.
-  class IO
-    attr_accessor :timeout
+  # The IO module provides low-level methods for opening, capturing, and encoding
+  # IO streams produced by the ffmpeg and ffprobe binaries.
+  module IO
+    class << self
+      attr_writer :timeout, :encoding
 
-    def self.encode!(chunk)
-      chunk[/test/]
-    rescue ArgumentError
-      chunk.encode!(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: '?')
-    end
+      def timeout
+        return @timeout if defined?(@timeout)
+
+        @timeout = 30
+      end
+
+      def encoding
+        @encoding ||= Encoding::UTF_8
+      end
+
+      def encode!(string)
+        string.encode!(encoding, invalid: :replace, undef: :replace)
+      end
 
-    def initialize(target)
-      @target = target
-      @timeout = FFMPEG.io_timeout
+      def extend!(io)
+        io.timeout = timeout
+        io.set_encoding(encoding, invalid: :replace, undef: :replace)
+        io.extend(FFMPEG::IO)
+      end
+
+      def capture3(*cmd)
+        *io, status = Open3.capture3(*cmd)
+        io.each(&method(:encode!))
+        [*io, status]
+      end
+
+      def popen3(*cmd, &block)
+        if block_given?
+          Open3.popen3(*cmd) do |*io, wait_thr|
+            io = io.map(&method(:extend!))
+            block.call(*io, wait_thr)
+          rescue StandardError
+            wait_thr.kill
+            wait_thr.join
+            raise
+          end
+        else
+          *io, wait_thr = Open3.popen3(*cmd)
+          io = io.map(&method(:extend!))
+          [*io, wait_thr]
+        end
+      end
     end
 
-    def each(&block)
-      timer = timeout.nil? ? nil : Timeout.start(timeout)
+    def each(chomp: false, &block)
       buffer = String.new
 
       until eof?
         char = getc
         case char
-        when "\n", "\r"
-          timer&.tick
-          timer&.pause
-          block.call(buffer)
-          timer&.resume
+        when "\r", "\n"
+          buffer << ($ORS || "\n") unless chomp
+          block.call(buffer) unless buffer.empty?
           buffer = String.new
         else
           buffer << char
         end
       end
 
       block.call(buffer) unless buffer.empty?
-    ensure
-      timer&.cancel
-    end
-
-    %i[
-      getc
-      gets
-      readchar
-      readline
-    ].each do |symbol|
-      define_method(symbol) do |*args|
-        data = @target.send(symbol, *args)
-        self.class.encode!(data) unless data.nil?
-        data
-      end
-    end
-
-    %i[
-      each_char
-      each_line
-    ].each do |symbol|
-      define_method(symbol) do |*args, &block|
-        timer = timeout.nil? ? nil : Timeout.start(timeout)
-        @target.send(symbol, *args) do |data|
-          timer&.tick
-          timer&.pause
-          block.call(self.class.encode!(data))
-          timer&.resume
-        end
-      ensure
-        timer&.cancel
-      end
-    end
-
-    def readlines(*args)
-      lines = []
-      each(*args) { |line| lines << line }
-      lines
-    end
-
-    private
-
-    def respond_to_missing?(symbol, include_private = false)
-      @target.respond_to?(symbol, include_private)
-    end
-
-    def method_missing(symbol, *args)
-      @target.send(symbol, *args)
     end
   end
 end

lib/ffmpeg/media.rb

@@ -59,7 +59,7 @@ class LoadError < FFMPEG::Error; end
                          :format_name, :format_long_name,
                          :start_time, :bit_rate, :duration
 
-    # @param path [String] The local path or remote URL to a multimedia file.
+    # @param path [String, Pathname, URI] The local path or remote URL to a multimedia file.
     # @param ffprobe_args [Array<String>] Additional arguments to pass to ffprobe.
     # @param load [Boolean] Whether to load the metadata immediately.
     # @param autoload [Boolean] Whether to autoload the metadata when accessing attributes.