libav-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: baa53a631a37482e35cdb6c5c93ccdd698852ef87b51958aecdbb7278078d320
+  data.tar.gz: 0ec4ac62f3fc523251cb3c0da083efa6538e0721031764cce71e6286ebfc4e70
+SHA512:
+  metadata.gz: 852262785ea88ea96eb09593559a669d9a752d6f5b11aace8af77f303b6eab3e34adf7ef5248c30e8f6dfc42bd83ef000b4b1a98ebdef3cb8117878365f92490
+  data.tar.gz: cb33b4511134f81247ea518ae5faad65278e126208ef5fcb644d1828e60a74db928a6feea78194e37679c283c993ea2d3c3e6701fcb44170c2c4c5db3ac8d94f

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yudai Takada
+
+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,256 @@
+# libav-ruby
+
+`libav-ruby` provides frame-level Ruby bindings for the FFmpeg libraries. It
+encodes packed RGBA frames without starting an `ffmpeg` subprocess, decodes
+video to RGBA, and reads or writes interleaved f32 audio.
+
+The current release supports FFmpeg 6 and 7 on 64-bit Ruby
+(`libavcodec` majors 60 and 61). The gem checks the complete FFmpeg library set
+at load time and raises `LoadError` for unsupported or mixed versions.
+
+## Installation
+
+Install FFmpeg's shared libraries first:
+
+```sh
+# macOS
+brew install ffmpeg@7
+
+# Ubuntu
+sudo apt install \
+  libavcodec-dev libavformat-dev libavutil-dev \
+  libswscale-dev libswresample-dev
+```
+
+Then add the gem:
+
+```sh
+bundle add libav-ruby
+```
+
+Homebrew's standard Intel and Apple Silicon `ffmpeg@6`/`ffmpeg@7` keg paths
+are detected automatically. For any other non-standard installation, set
+`LIBAV_LIBRARY_PATH` to the directory containing the shared libraries before
+requiring the gem.
+
+## Encode video
+
+Input is packed RGBA bytes, a `{width:, height:, data:}` Hash, or any object
+with `width`, `height`, and `data` methods. A `Texel::Image` is accepted when
+it has four channels and `dtype: :u8`, which is the format returned by
+Stagecraft's offscreen renderer.
+
+```ruby
+require "libav"
+
+width = 1_280
+height = 720
+
+LibAV::VideoWriter.open(
+  "output.mp4",
+  width: width,
+  height: height,
+  fps: 60,
+  codec: :h264,
+  crf: 18,
+  preset: "medium"
+) do |writer|
+  frames.each do |rgba|
+    writer << rgba
+  end
+end
+```
+
+Supported video codec names are `:h264`, `:hevc`, `:vp9`, `:prores`, and
+`:png`. The matching encoder must be present in the system FFmpeg build.
+H.264/HEVC use `yuv420p` by default, ProRes uses `yuv422p10le`, and PNG uses
+`rgba`. For ProRes, `pixel_format: :rgba` selects alpha-preserving
+`yuva444p10le`, while `:yuv444p` selects `yuv444p10le`. Extra keyword options
+are forwarded to the codec's FFmpeg option set; underscores in Ruby keyword
+names become hyphens.
+
+For a PNG sequence, use a numbered output pattern:
+
+```ruby
+LibAV::VideoWriter.open(
+  "frames/frame-%06d.png",
+  width: 640,
+  height: 480,
+  fps: 30,
+  codec: :png
+) { |writer| frames.each { |frame| writer << frame } }
+```
+
+### Async encoding
+
+Async mode overlaps rendering and encoding with a bounded queue of four
+frames. Input strings are copied before being queued.
+
+```ruby
+writer = LibAV::VideoWriter.open(
+  "output.mp4", width: 1_280, height: 720, fps: 60
+)
+writer.async = true
+frames.each { |frame| writer << frame }
+writer.close
+```
+
+An encoder-thread exception is re-raised by `push` or `close`.
+
+## Decode video
+
+`read_frame` returns a `LibAV::VideoFrame` with `width`, `height`, `data`, and
+`pts`. `data` is a packed RGBA String.
+
+```ruby
+LibAV::VideoReader.open("input.mp4") do |reader|
+  puts "#{reader.width}x#{reader.height} at #{reader.fps} fps"
+
+  reader.each_frame do |frame, pts_seconds|
+    texture.update(frame.data)
+  end
+
+  reader.seek(12.5)
+  frame = reader.read_frame
+end
+```
+
+Pass `frame_type: :texel` to return `Texel::Image` objects instead. Texel is an
+optional dependency and must be installed separately by applications using
+this mode. Timestamps remain the second value yielded by `each_frame`.
+
+```ruby
+LibAV::VideoReader.open("input.mp4", frame_type: :texel) do |reader|
+  reader.each_frame { |image, pts| texture.update(image) }
+end
+```
+
+Set `reader.reuse_buffer = true` to keep replacing the same decoded String.
+Previously returned frames then observe later decoded data, so this mode is
+intended for immediate uploads or other zero-retention processing.
+Buffer reuse is unavailable with immutable Texel output.
+
+`fps`, `duration`, and `frame_count` are container metadata or estimates and
+can be `nil` when the input does not provide enough timing information.
+
+## Audio
+
+Add an AAC or Opus track by passing audio options when the video writer is
+opened. `push_audio` accepts packed, interleaved native-endian f32 PCM in
+arbitrary sample-aligned chunks, or an Array of floats.
+
+```ruby
+LibAV::VideoWriter.open(
+  "music-video.mp4",
+  width: 1_920,
+  height: 1_080,
+  fps: 60,
+  audio: {
+    codec: :aac,
+    sample_rate: 48_000,
+    channels: 2,
+    bitrate: 192_000
+  }
+) do |writer|
+  writer.push_audio(pcm_f32_stereo)
+  frames.each { |frame| writer << frame }
+end
+```
+
+Audio-only files use `AudioWriter`. WAV defaults to f32 PCM, WebM/Ogg/Opus
+containers default to Opus, and other containers default to AAC. A WebM
+`VideoWriter` audio track also defaults to Opus when `audio[:codec]` is
+omitted.
+
+```ruby
+LibAV::AudioWriter.open(
+  "tone.wav", sample_rate: 48_000, channels: 2
+) { |writer| writer << pcm }
+
+LibAV::AudioReader.open("tone.wav") do |reader|
+  reader.seek(1.5)
+  reader.each_frame do |frame, pts_seconds|
+    consume(frame.data, frame.samples)
+  end
+end
+```
+
+Audio input is converted with libswresample and accumulated in FFmpeg's
+`AVAudioFifo`, then submitted in the encoder's native frame size. Calls may
+therefore use any chunk size that contains complete interleaved samples.
+
+`AudioReader#seek` performs a backward native seek, discards decoded audio
+before the requested time, and trims the first overlapping frame to a sample
+boundary.
+
+## Renderer integration
+
+[`examples/stagecraft_offscreen_to_mp4.rb`](examples/stagecraft_offscreen_to_mp4.rb)
+renders a Stagecraft scene offscreen and passes each returned `Texel::Image`
+directly to an asynchronous video writer:
+
+```sh
+ruby examples/stagecraft_offscreen_to_mp4.rb output.mp4
+```
+
+[`examples/vizcore_scene_to_mp4.rb`](examples/vizcore_scene_to_mp4.rb) runs a
+Vizcore scene with deterministic dummy audio analysis and encodes its software
+snapshots without temporary frame files:
+
+```sh
+ruby examples/vizcore_scene_to_mp4.rb path/to/scene.rb output.mp4
+```
+
+Both examples accept `WIDTH`, `HEIGHT`, `FPS`, and `FRAMES` environment
+variables. Their renderer gems are optional application dependencies and are
+not installed with libav-ruby.
+
+`AudioReader#read_samples` returns only the packed String.
+`AudioReader#each_chunk` yields the String and PTS instead of an `AudioFrame`.
+
+## Errors and logging
+
+Negative FFmpeg return codes become `LibAV::NativeError` instances with the
+native error string, numeric code, and operation name. EAGAIN and EOF remain
+internal control flow. Public objects have idempotent `close` methods, and all
+block-form `open` methods close in an `ensure`.
+
+FFmpeg logs are forwarded to `LibAV.logger`. The default logger writes warnings
+and errors to stderr.
+
+```ruby
+LibAV.logger = my_logger
+LibAV.log_level = :info
+```
+
+Levels are `:quiet`, `:panic`, `:fatal`, `:error`, `:warn`, `:info`,
+`:verbose`, `:debug`, and `:trace`. Set `LibAV.logger = nil` to discard logs.
+
+## Development
+
+```sh
+bundle install
+bundle exec rspec
+bundle exec gem build libav.gemspec
+```
+
+The integration specs create short media files in temporary directories and
+use `ffprobe` for container assertions. `native/abi_probe.c` prints the native
+offsets used by the version-specific layouts. Regenerate a layout against
+matching FFmpeg development headers with:
+
+```sh
+ruby native/generate_layout.rb \
+  --codec-major 61 \
+  --include /path/to/ffmpeg/include
+```
+
+Use `--verify` instead of rewriting the file to compare the checked-in layout
+against the selected headers. CI performs this check on FFmpeg 6 and FFmpeg 7
+across Linux, macOS, and Windows.
+
+## License
+
+The gem is available under the MIT License. FFmpeg and optional encoders have
+their own licenses; the effective FFmpeg license depends on how the system
+libraries were built.

data/Rakefile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+desc "Check bundled examples for Ruby syntax errors"
+task :examples do
+  Dir[File.join(__dir__, "examples", "*.rb")].sort.each do |path|
+    ruby "-c", path
+  end
+end
+
+task default: %i[spec examples]

data/examples/frames_to_mp4.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+require "libav"
+
+width = 640
+height = 360
+frame_count = 120
+
+LibAV::VideoWriter.open(
+  ARGV.fetch(0, "gradient.mp4"),
+  width:,
+  height:,
+  fps: 60,
+  codec: :h264,
+  crf: 18,
+  preset: "medium"
+) do |writer|
+  frame_count.times do |index|
+    red = index * 255 / (frame_count - 1)
+    pixel = [red, 80, 255 - red, 255].pack("C4")
+    writer << pixel * (width * height)
+  end
+end

data/examples/stagecraft_offscreen_to_mp4.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require "libav"
+require "stagecraft"
+
+width = Integer(ENV.fetch("WIDTH", 1_280))
+height = Integer(ENV.fetch("HEIGHT", 720))
+fps = Integer(ENV.fetch("FPS", 60))
+frame_count = Integer(ENV.fetch("FRAMES", fps * 5))
+output = ARGV.first || "stagecraft.mp4"
+
+scene = Stagecraft::Scene.new
+scene.background = "#10141d"
+scene.add(Stagecraft::Lights::Ambient.new(intensity: 0.3))
+sun = Stagecraft::Lights::Directional.new(intensity: 3.0)
+sun.position.set(4, 7, 5)
+scene.add(sun)
+
+cube = Stagecraft::Mesh.new(
+  Stagecraft::Geometries.box,
+  Stagecraft::Materials::PBR.new(
+    base_color: "#e91e63", roughness: 0.35, metallic: 0.15
+  )
+)
+scene.add(cube)
+
+camera = Stagecraft::Cameras::Perspective.new(
+  fov: 55, aspect: width.to_f / height, near: 0.1, far: 200
+)
+camera.position.set(0, 2, 6)
+renderer = Stagecraft::Renderer.offscreen(width:, height:, msaa: 4)
+
+begin
+  LibAV::VideoWriter.open(
+    output, width:, height:, fps:, codec: :h264,
+    preset: "medium", crf: 18, async: true
+  ) do |writer|
+    frame_count.times do
+      cube.rotation.rotate_y!(1.0 / fps)
+      writer << renderer.render(scene, camera).read_pixels
+    end
+  end
+ensure
+  renderer.dispose
+end
+
+puts output

data/examples/vizcore_scene_to_mp4.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require "libav"
+require "texel"
+require "vizcore"
+require "vizcore/config"
+require "vizcore/renderer"
+
+scene_path = ARGV.fetch(0) do
+  abort "Usage: ruby examples/vizcore_scene_to_mp4.rb SCENE.rb [OUTPUT.mp4]"
+end
+output = ARGV[1] || "vizcore.mp4"
+width = Integer(ENV.fetch("WIDTH", 1_280))
+height = Integer(ENV.fetch("HEIGHT", 720))
+fps = Integer(ENV.fetch("FPS", 60))
+frame_count = Integer(ENV.fetch("FRAMES", fps * 5))
+
+config = Vizcore::Config.new(scene_file: scene_path, audio_source: :dummy)
+source = Vizcore::Renderer::SceneFrameSource.new(config:, frame_rate: fps)
+renderer = Vizcore::Renderer::SnapshotRenderer.new(width:, height:)
+
+begin
+  source.start
+  LibAV::VideoWriter.open(
+    output, width:, height:, fps:, codec: :h264,
+    preset: "medium", crf: 18, async: true
+  ) do |writer|
+    frame_count.times do
+      frame = source.capture
+      png = renderer.render(
+        scene: frame.fetch(:scene), audio: frame.fetch(:audio)
+      )
+      writer << Texel.load(png, channels: 4, dtype: :u8)
+    end
+  end
+ensure
+  source.stop
+end
+
+puts output