libav-ruby 0.1.0

data/lib/libav/audio_writer.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+require_relative "output_context"
+require_relative "audio_encoder"
+
+module LibAV
+  class AudioWriter
+    DEFAULT_CODECS = {
+      ".wav" => :pcm_f32le,
+      ".webm" => :opus,
+      ".opus" => :opus,
+      ".ogg" => :opus
+    }.freeze
+
+    attr_reader :sample_rate, :channels
+
+    def self.open(path, **options)
+      writer = new(path, **options)
+      return writer unless block_given?
+
+      begin
+        yield writer
+      ensure
+        writer.close
+      end
+    end
+
+    def initialize(path, codec: nil, **options)
+      @output = OutputContext.new(path)
+      codec ||= DEFAULT_CODECS.fetch(File.extname(File.path(path)).downcase, :aac)
+      @encoder = AudioEncoder.new(@output, codec:, **options)
+      @sample_rate = @encoder.sample_rate
+      @channels = @encoder.channels
+      @output.open!
+    rescue StandardError
+      close_resources
+      raise
+    end
+
+    def <<(pcm_f32_interleaved)
+      push(pcm_f32_interleaved)
+    end
+
+    def push(pcm_f32_interleaved)
+      raise ClosedError, "audio writer is closed" if closed?
+
+      @encoder.push(pcm_f32_interleaved)
+      self
+    end
+
+    def close
+      return if closed?
+
+      error = nil
+      begin
+        @encoder.flush
+      rescue StandardError => caught
+        error = caught
+      ensure
+        cleanup_error = close_resources
+        error ||= cleanup_error
+        @closed = true
+      end
+      raise error if error
+
+      nil
+    end
+
+    def closed?
+      @closed == true
+    end
+
+    private
+
+    def close_resources
+      error = nil
+      begin
+        @output&.close
+      rescue StandardError => caught
+        error = caught
+      ensure
+        @encoder&.close
+      end
+      error
+    end
+  end
+end

data/lib/libav/errors.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module LibAV
+  class Error < StandardError; end
+
+  class NativeError < Error
+    attr_reader :code, :operation
+
+    def initialize(code, operation = nil)
+      @code = Integer(code)
+      @operation = operation
+
+      prefix = operation ? "#{operation}: " : ""
+      super("#{prefix}#{Native.error_string(@code)} (#{@code})")
+    end
+  end
+
+  class ClosedError < Error; end
+  class EncodingError < Error; end
+end

data/lib/libav/native/layout.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module LibAV
+  module Native
+    module Layout
+      module_function
+
+      def for_codec_major(major)
+        require_relative "v#{major}/layout"
+        const_get(:"V#{major}")
+      end
+
+      def read_int(pointer, type, field)
+        pointer.get_int32(offset(type, field))
+      end
+
+      def write_int(pointer, type, field, value)
+        pointer.put_int32(offset(type, field), Integer(value))
+      end
+
+      def read_int64(pointer, type, field)
+        pointer.get_int64(offset(type, field))
+      end
+
+      def write_int64(pointer, type, field, value)
+        pointer.put_int64(offset(type, field), Integer(value))
+      end
+
+      def read_pointer(pointer, type, field)
+        pointer.get_pointer(offset(type, field))
+      end
+
+      def write_pointer(pointer, type, field, value)
+        pointer.put_pointer(offset(type, field), value)
+      end
+
+      def read_rational(pointer, type, field)
+        position = offset(type, field)
+        numerator = pointer.get_int32(position)
+        denominator = pointer.get_int32(position + 4)
+        Rational(numerator, denominator.zero? ? 1 : denominator)
+      end
+
+      def write_rational(pointer, type, field, value)
+        rational = value.to_r
+        position = offset(type, field)
+        pointer.put_int32(position, rational.numerator)
+        pointer.put_int32(position + 4, rational.denominator)
+      end
+
+      def field_pointer(pointer, type, field)
+        pointer + offset(type, field)
+      end
+
+      def offset(type, field)
+        Native.layout.fetch(type).fetch(field)
+      end
+    end
+  end
+end

data/lib/libav/native/v60/layout.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module LibAV
+  module Native
+    module Layout
+      V60 = {
+        output_format: {flags: 44},
+        format_context: {oformat: 16, pb: 32, nb_streams: 44, streams: 48, duration: 72},
+        stream: {
+          index: 8, codecpar: 16, time_base: 32, start_time: 40, duration: 48,
+          nb_frames: 56, avg_frame_rate: 88, r_frame_rate: 216
+        },
+        codec_context: {
+          codec_type: 12, priv_data: 32, bit_rate: 56, flags: 76, time_base: 100,
+          width: 116, height: 120, gop_size: 132, pix_fmt: 136, sample_rate: 352,
+          sample_fmt: 360, frame_size: 364, framerate: 704, ch_layout: 912
+        },
+        frame: {
+          data: 0, linesize: 64, extended_data: 96, width: 104, height: 108,
+          nb_samples: 112, format: 116, pts: 136, sample_rate: 208,
+          best_effort_timestamp: 344, ch_layout: 448, duration: 472
+        },
+        packet: {
+          pts: 8, dts: 16, data: 24, size: 32, stream_index: 36,
+          duration: 64, time_base: 96
+        }
+      }.freeze
+    end
+  end
+end

data/lib/libav/native/v61/layout.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module LibAV
+  module Native
+    module Layout
+      V61 = {
+        output_format: {flags: 44},
+        format_context: {oformat: 16, pb: 32, nb_streams: 44, streams: 48, duration: 104},
+        stream: {
+          index: 8, codecpar: 16, time_base: 32, start_time: 40, duration: 48,
+          nb_frames: 56, avg_frame_rate: 88, r_frame_rate: 216
+        },
+        codec_context: {
+          codec_type: 12, priv_data: 32, bit_rate: 56, flags: 64, time_base: 84,
+          framerate: 100, width: 116, height: 120, pix_fmt: 140, gop_size: 332,
+          sample_rate: 344, sample_fmt: 348, ch_layout: 352, frame_size: 376
+        },
+        frame: {
+          data: 0, linesize: 64, extended_data: 96, width: 104, height: 108,
+          nb_samples: 112, format: 116, pts: 136, sample_rate: 192,
+          best_effort_timestamp: 320, ch_layout: 408, duration: 432
+        },
+        packet: {
+          pts: 8, dts: 16, data: 24, size: 32, stream_index: 36,
+          duration: 64, time_base: 96
+        }
+      }.freeze
+    end
+  end
+end

data/lib/libav/native.rb

@@ -0,0 +1,311 @@
+# frozen_string_literal: true
+
+require "ffi"
+require_relative "native/layout"
+
+module LibAV
+  module Native
+    class RationalValue < FFI::Struct
+      layout :numerator, :int,
+             :denominator, :int
+    end
+
+    SUPPORTED = {
+      60 => {avformat: 60, avutil: 58, swscale: 7, swresample: 4},
+      61 => {avformat: 61, avutil: 59, swscale: 8, swresample: 5}
+    }.freeze
+
+    AVERROR_EOF = -541_478_725
+    AVERROR_EAGAIN = -Errno::EAGAIN::Errno
+    AV_NOPTS_VALUE = -(1 << 63)
+    AV_TIME_BASE = 1_000_000
+    AVIO_FLAG_WRITE = 2
+    AVSEEK_FLAG_BACKWARD = 1
+    AVFMT_NOFILE = 0x0001
+    AVFMT_GLOBALHEADER = 0x0040
+    AV_CODEC_FLAG_GLOBAL_HEADER = 1 << 22
+    AVMEDIA_TYPE_VIDEO = 0
+    AVMEDIA_TYPE_AUDIO = 1
+    AV_CHANNEL_LAYOUT_SIZE = 24
+    SWS_BICUBIC = 4
+    AV_SAMPLE_FMT_FLT = 3
+    LOG_LEVELS = {
+      quiet: -8, panic: 0, fatal: 8, error: 16,
+      warn: 24, info: 32, verbose: 40, debug: 48, trace: 56
+    }.freeze
+
+    COMPONENT_NAMES = {
+      avcodec: "avcodec",
+      avformat: "avformat",
+      avutil: "avutil",
+      swscale: "swscale",
+      swresample: "swresample"
+    }.freeze
+
+    class << self
+      attr_reader :codec, :format, :util, :scale, :resample, :layout, :versions
+
+      def load!
+        return if @loaded
+        raise LoadError, "libav-ruby requires a 64-bit Ruby process" unless FFI.type_size(:pointer) == 8
+
+        @codec = library(:avcodec, [61, 60], allow_unversioned: true)
+        attach(@codec, :avcodec_version, [], :uint)
+        codec_major = version_major(@codec.avcodec_version)
+        expected = SUPPORTED[codec_major]
+        raise unsupported_version(codec_major) unless expected
+
+        @format = library(:avformat, [expected[:avformat]])
+        @util = library(:avutil, [expected[:avutil]])
+        @scale = library(:swscale, [expected[:swscale]])
+        @resample = library(:swresample, [expected[:swresample]])
+        bind_functions
+        detect_versions(codec_major)
+        validate_versions!(expected)
+        @layout = Layout.for_codec_major(codec_major)
+        @loaded = true
+      rescue FFI::NotFoundError => e
+        raise LoadError, "Unable to load FFmpeg shared libraries: #{e.message}. Install FFmpeg 6 or 7."
+      end
+
+      def check(code, operation = nil)
+        raise NativeError.new(code, operation) if code.negative?
+
+        code
+      end
+
+      def control_flow?(code)
+        code == AVERROR_EAGAIN || code == AVERROR_EOF
+      end
+
+      def error_string(code)
+        buffer = FFI::MemoryPointer.new(:char, 256)
+        result = @util.av_strerror(code, buffer, buffer.size)
+        return "FFmpeg error" if result.negative?
+
+        buffer.read_string
+      end
+
+      def version_major(version)
+        version >> 16
+      end
+
+      def rational(value)
+        value = value.to_r
+        RationalValue.new.tap do |rational|
+          rational[:numerator] = value.numerator
+          rational[:denominator] = value.denominator
+        end
+      end
+
+      def log_level=(level)
+        numeric = level.is_a?(Integer) ? level : LOG_LEVELS.fetch(level.to_sym) do
+          raise ArgumentError, "unknown FFmpeg log level: #{level.inspect}"
+        end
+        @util.av_log_set_level(numeric)
+      end
+
+      def install_log_callback!
+        return if @log_callback
+
+        @log_callback = proc do |context, level, format, arguments|
+          forward_log(context, level, format, arguments)
+        rescue StandardError
+          nil
+        end
+        @util.av_log_set_callback(@log_callback)
+      end
+
+      private
+
+      def bind_functions
+        bind_version_functions
+        bind_util_functions
+        bind_codec_functions
+        bind_format_functions
+        bind_scale_functions
+        bind_resample_functions
+      end
+
+      def bind_version_functions
+        attach(@format, :avformat_version, [], :uint)
+        attach(@util, :avutil_version, [], :uint)
+        attach(@scale, :swscale_version, [], :uint)
+        attach(@resample, :swresample_version, [], :uint)
+      end
+
+      def bind_util_functions
+        attach(@util, :av_strerror, %i[int pointer size_t], :int)
+        attach(@util, :av_get_pix_fmt, [:string], :int)
+        attach(@util, :av_get_sample_fmt, [:string], :int)
+        attach(@util, :av_opt_set, %i[pointer string string int], :int)
+        attach(@util, :av_opt_set_int, %i[pointer string int64 int], :int)
+        attach(@util, :av_opt_set_q, %i[pointer string av_rational int], :int)
+        attach(@util, :av_frame_alloc, [], :pointer)
+        attach(@util, :av_frame_free, [:pointer], :void)
+        attach(@util, :av_frame_get_buffer, %i[pointer int], :int)
+        attach(@util, :av_frame_make_writable, [:pointer], :int)
+        attach(@util, :av_frame_unref, [:pointer], :void)
+        attach(@util, :av_audio_fifo_alloc, %i[int int int], :pointer)
+        attach(@util, :av_audio_fifo_free, [:pointer], :void)
+        attach(@util, :av_audio_fifo_realloc, %i[pointer int], :int)
+        attach(@util, :av_audio_fifo_size, [:pointer], :int)
+        attach(@util, :av_audio_fifo_write, %i[pointer pointer int], :int)
+        attach(@util, :av_audio_fifo_read, %i[pointer pointer int], :int)
+        attach(@util, :av_samples_alloc_array_and_samples,
+               %i[pointer pointer int int int int], :int)
+        attach(@util, :av_samples_set_silence, %i[pointer int int int int], :int)
+        attach(@util, :av_freep, [:pointer], :void)
+        attach(@util, :av_channel_layout_default, %i[pointer int], :void)
+        attach(@util, :av_channel_layout_copy, %i[pointer pointer], :int)
+        attach(@util, :av_channel_layout_uninit, [:pointer], :void)
+        attach(@util, :av_log_set_level, [:int], :void)
+        attach(@util, :av_log_format_line2,
+               %i[pointer int string pointer pointer int pointer], :int)
+        @util.callback(:libav_log_callback, %i[pointer int string pointer], :void)
+        attach(@util, :av_log_set_callback, [:libav_log_callback], :void)
+      end
+
+      def bind_codec_functions
+        attach(@codec, :avcodec_find_encoder, [:int], :pointer)
+        attach(@codec, :avcodec_find_encoder_by_name, [:string], :pointer)
+        attach(@codec, :avcodec_find_decoder, [:int], :pointer)
+        attach(@codec, :avcodec_alloc_context3, [:pointer], :pointer)
+        attach(@codec, :avcodec_free_context, [:pointer], :void)
+        attach(@codec, :avcodec_open2, %i[pointer pointer pointer], :int, blocking: true)
+        attach(@codec, :avcodec_parameters_from_context, %i[pointer pointer], :int)
+        attach(@codec, :avcodec_parameters_to_context, %i[pointer pointer], :int)
+        attach(@codec, :avcodec_send_frame, %i[pointer pointer], :int, blocking: true)
+        attach(@codec, :avcodec_receive_packet, %i[pointer pointer], :int, blocking: true)
+        attach(@codec, :avcodec_send_packet, %i[pointer pointer], :int, blocking: true)
+        attach(@codec, :avcodec_receive_frame, %i[pointer pointer], :int, blocking: true)
+        attach(@codec, :avcodec_flush_buffers, [:pointer], :void)
+        attach(@codec, :av_packet_alloc, [], :pointer)
+        attach(@codec, :av_packet_free, [:pointer], :void)
+        attach(@codec, :av_packet_unref, [:pointer], :void)
+        attach(@codec, :av_packet_rescale_ts, %i[pointer av_rational av_rational], :void)
+      end
+
+      def bind_format_functions
+        attach(@format, :avformat_alloc_output_context2, %i[pointer pointer string string], :int)
+        attach(@format, :avformat_new_stream, %i[pointer pointer], :pointer)
+        attach(@format, :avformat_write_header, %i[pointer pointer], :int, blocking: true)
+        attach(@format, :av_interleaved_write_frame, %i[pointer pointer], :int, blocking: true)
+        attach(@format, :av_write_trailer, [:pointer], :int, blocking: true)
+        attach(@format, :avformat_free_context, [:pointer], :void)
+        attach(@format, :avio_open, %i[pointer string int], :int, blocking: true)
+        attach(@format, :avio_closep, [:pointer], :int, blocking: true)
+        attach(@format, :avformat_open_input, %i[pointer string pointer pointer], :int, blocking: true)
+        attach(@format, :avformat_find_stream_info, %i[pointer pointer], :int, blocking: true)
+        attach(@format, :av_find_best_stream, %i[pointer int int int pointer int], :int)
+        attach(@format, :av_read_frame, %i[pointer pointer], :int, blocking: true)
+        attach(@format, :av_seek_frame, %i[pointer int int64 int], :int, blocking: true)
+        attach(@format, :avformat_close_input, [:pointer], :void)
+      end
+
+      def bind_scale_functions
+        attach(@scale, :sws_getContext,
+               %i[int int int int int int int pointer pointer pointer], :pointer)
+        attach(@scale, :sws_scale, %i[pointer pointer pointer int int pointer pointer], :int,
+               blocking: true)
+        attach(@scale, :sws_freeContext, [:pointer], :void)
+      end
+
+      def bind_resample_functions
+        attach(@resample, :swr_alloc_set_opts2,
+               %i[pointer pointer int int pointer int int int pointer], :int)
+        attach(@resample, :swr_init, [:pointer], :int)
+        attach(@resample, :swr_convert, %i[pointer pointer int pointer int], :int, blocking: true)
+        attach(@resample, :swr_get_delay, %i[pointer int64], :int64)
+        attach(@resample, :swr_get_out_samples, %i[pointer int], :int)
+        attach(@resample, :swr_free, [:pointer], :void)
+      end
+
+      def attach(library, name, arguments, returns, **options)
+        library.attach_function(name, arguments, returns, options)
+      end
+
+      def library(component, majors, allow_unversioned: false)
+        candidates = library_candidates(component, majors, allow_unversioned:)
+        Module.new.tap do |library|
+          library.extend(FFI::Library)
+          library.typedef(RationalValue.by_value, :av_rational)
+          library.ffi_lib(candidates)
+        end
+      end
+
+      def library_candidates(component, majors, allow_unversioned:)
+        base = COMPONENT_NAMES.fetch(component)
+        names = majors.flat_map do |major|
+          ["lib#{base}.#{major}.dylib", "lib#{base}.so.#{major}", "#{base}-#{major}.dll", "#{base}-#{major}"]
+        end
+        directories = library_directories
+        names.concat(["lib#{base}.dylib", "lib#{base}.so", base]) if
+          allow_unversioned || ENV["LIBAV_LIBRARY_PATH"]
+        directories.flat_map { |directory| names.map { |name| File.join(directory, name) } } + names
+      end
+
+      def library_directories
+        [
+          ENV["LIBAV_LIBRARY_PATH"],
+          "/opt/homebrew/opt/ffmpeg@7/lib",
+          "/opt/homebrew/opt/ffmpeg@6/lib",
+          "/usr/local/opt/ffmpeg@7/lib",
+          "/usr/local/opt/ffmpeg@6/lib"
+        ].compact
+      end
+
+      def detect_versions(codec_major)
+        @versions = {
+          avcodec: codec_major,
+          avformat: version_major(@format.avformat_version),
+          avutil: version_major(@util.avutil_version),
+          swscale: version_major(@scale.swscale_version),
+          swresample: version_major(@resample.swresample_version)
+        }.freeze
+      end
+
+      def validate_versions!(expected)
+        mismatches = expected.filter_map do |component, major|
+          actual = @versions.fetch(component)
+          "#{component}=#{actual} (expected #{major})" unless actual == major
+        end
+        return if mismatches.empty?
+
+        raise LoadError, "Incompatible FFmpeg library set: #{mismatches.join(", ")}"
+      end
+
+      def unsupported_version(codec_major)
+        LoadError.new(
+          "Unsupported libavcodec major #{codec_major}; libav-ruby supports FFmpeg 6/7 " \
+          "(libavcodec 60/61)"
+        )
+      end
+
+      def forward_log(context, level, format, arguments)
+        logger = LibAV.logger
+        return unless logger
+
+        buffer = FFI::MemoryPointer.new(:char, 2_048)
+        prefix = FFI::MemoryPointer.new(:int)
+        prefix.write_int(1)
+        @util.av_log_format_line2(
+          context, level, format, arguments, buffer, buffer.size, prefix
+        )
+        message = buffer.read_string.strip
+        return if message.empty?
+
+        logger.public_send(ruby_log_level(level), message)
+      end
+
+      def ruby_log_level(level)
+        return :fatal if level <= LOG_LEVELS[:fatal]
+        return :error if level <= LOG_LEVELS[:error]
+        return :warn if level <= LOG_LEVELS[:warn]
+        return :info if level <= LOG_LEVELS[:info]
+
+        :debug
+      end
+    end
+  end
+end

data/lib/libav/output_context.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module LibAV
+  class OutputContext
+    attr_reader :pointer
+
+    def initialize(path)
+      @path = File.path(path)
+      @pointer_holder = FFI::MemoryPointer.new(:pointer)
+      result = Native.format.avformat_alloc_output_context2(
+        @pointer_holder, nil, nil, @path
+      )
+      Native.check(result, "avformat_alloc_output_context2")
+      @pointer = @pointer_holder.read_pointer
+      raise EncodingError, "FFmpeg could not determine an output container for #{@path}" if @pointer.null?
+
+      @io_open = false
+      @header_written = false
+      @trailer_written = false
+    end
+
+    def new_stream(codec)
+      stream = Native.format.avformat_new_stream(pointer, codec)
+      raise EncodingError, "avformat_new_stream returned NULL" if stream.null?
+
+      stream
+    end
+
+    def global_header?
+      (output_flags & Native::AVFMT_GLOBALHEADER) != 0
+    end
+
+    def open!
+      open_io unless (output_flags & Native::AVFMT_NOFILE) != 0
+      Native.check(Native.format.avformat_write_header(pointer, nil), "avformat_write_header")
+      @header_written = true
+    end
+
+    def write_packet(packet, codec_time_base, stream)
+      stream_time_base = Native::Layout.read_rational(stream, :stream, :time_base)
+      Native.codec.av_packet_rescale_ts(
+        packet, Native.rational(codec_time_base), Native.rational(stream_time_base)
+      )
+      stream_index = Native::Layout.read_int(stream, :stream, :index)
+      Native::Layout.write_int(packet, :packet, :stream_index, stream_index)
+      Native.check(
+        Native.format.av_interleaved_write_frame(pointer, packet),
+        "av_interleaved_write_frame"
+      )
+    end
+
+    def close
+      return if @closed
+
+      error = write_trailer
+      io_error = close_io
+      error ||= io_error
+      Native.format.avformat_free_context(pointer) if pointer && !pointer.null?
+      @pointer = nil
+      @closed = true
+      raise error if error
+    end
+
+    private
+
+    def output_flags
+      output_format = Native::Layout.read_pointer(pointer, :format_context, :oformat)
+      Native::Layout.read_int(output_format, :output_format, :flags)
+    end
+
+    def open_io
+      pb = Native::Layout.field_pointer(pointer, :format_context, :pb)
+      Native.check(Native.format.avio_open(pb, @path, Native::AVIO_FLAG_WRITE), "avio_open")
+      @io_open = true
+    end
+
+    def write_trailer
+      return unless @header_written
+      return if @trailer_written
+
+      result = Native.format.av_write_trailer(pointer)
+      @trailer_written = true
+      NativeError.new(result, "av_write_trailer") if result.negative?
+    end
+
+    def close_io
+      return unless @io_open
+
+      pb = Native::Layout.field_pointer(pointer, :format_context, :pb)
+      result = Native.format.avio_closep(pb)
+      @io_open = false
+      NativeError.new(result, "avio_closep") if result.negative?
+    end
+  end
+end

data/lib/libav/texel_support.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module LibAV
+  module TexelSupport
+    module_function
+
+    def image(width:, height:, data:)
+      load!
+      Texel::Image.new(
+        width:, height:, channels: 4, dtype: :u8,
+        color_space: :srgb, data:
+      )
+    end
+
+    def load!
+      return if defined?(Texel::Image)
+
+      require "texel"
+    rescue LoadError => error
+      raise LoadError,
+            "Texel output requires the optional 'texel' gem (#{error.message})"
+    end
+  end
+end

data/lib/libav/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module LibAV
+  VERSION = "0.1.0"
+end
+
+Libav = LibAV unless defined?(Libav)