ogg-ruby 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: '05859e9062f2f93116ce07130ae3af402a2065027956733c88dc7dbe90f32efb'
+  data.tar.gz: 33ed5b81ba61efa72ef8d318a888b28ed84ee729b26f9eb595a10143df8a4630
+SHA512:
+  metadata.gz: c3d5fdd2167a1b3a200484e3d8a5538b3e3a467f024777614be8f1b594702418eb3e5b04c156f3197f824566fb16a00285144ec3f7537aedb64217a323aed53f
+  data.tar.gz: 7ef459bdbe68ac85d88c3d28151cfd83fb7dc0e033901d5794522e0d3162f0a04dcf1aceb844d0bce451c84e02c61173c71ffb8ec71ec2ce34dfbffa79e69e7e

data/CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on Keep a Changelog and this project follows Semantic Versioning.
+
+## [Unreleased]
+
+## 0.1.0 (2026-02-28)
+
+- Initial release.

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,108 @@
+# ogg-ruby
+
+Ruby FFI bindings for [libogg](https://xiph.org/ogg/), the OGG container format library.
+
+## Requirements
+
+- Ruby 3.1+
+- libogg installed on your system
+
+### Installing libogg
+
+**macOS:**
+
+```bash
+brew install libogg
+```
+
+**Debian/Ubuntu:**
+
+```bash
+sudo apt-get install libogg-dev
+```
+
+**Fedora/RHEL:**
+
+```bash
+sudo dnf install libogg-devel
+```
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem "ogg-ruby"
+```
+
+And then execute:
+
+```bash
+bundle install
+```
+
+Or install it yourself as:
+
+```bash
+gem install ogg-ruby
+```
+
+## Usage
+
+### Encoding (Packet → StreamState → Page)
+
+```ruby
+require "ogg"
+
+stream = Ogg::StreamState.new(1) # serial number
+
+# Add packets to the stream
+packet = Ogg::Packet.new(data: "Hello, OGG!", bos: true, granulepos: 0, packetno: 0)
+stream.packetin(packet)
+
+packet2 = Ogg::Packet.new(data: "More data", eos: true, granulepos: 1, packetno: 1)
+stream.packetin(packet2)
+
+# Extract pages
+pages = []
+while (page = stream.flush)
+  pages << page.to_s
+end
+
+stream.clear
+```
+
+### Decoding (SyncState → Page → StreamState → Packet)
+
+```ruby
+require "ogg"
+
+sync = Ogg::SyncState.new
+
+# Write encoded data into sync
+sync.write(encoded_page_data)
+
+# Extract pages
+while (page = sync.pageout)
+  # Create a stream decoder with the same serial number
+  stream = Ogg::StreamState.new(page.serialno)
+  stream.pagein(page)
+
+  # Extract packets
+  while (packet = stream.packetout)
+    puts packet.data
+  end
+
+  stream.clear
+end
+
+sync.clear
+```
+
+## Thread Safety
+
+libogg functions are not thread-safe. Do not share `SyncState` or `StreamState` objects across threads without external synchronization.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec

data/lib/ogg/native.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Ogg
+  module Native
+    extend FFI::Library
+    ffi_lib ["libogg.so.0", "libogg.0.dylib", "libogg", "ogg"]
+
+    # --- Structs ---
+
+    class OggSyncState < FFI::Struct
+      layout :data,         :pointer,
+             :storage,      :int,
+             :fill,         :int,
+             :returned,     :int,
+             :unsynced,     :int,
+             :headerbytes,  :int,
+             :bodybytes,    :int
+    end
+
+    class OggStreamState < FFI::Struct
+      layout :body_data,       :pointer,
+             :body_storage,    :long,
+             :body_fill,       :long,
+             :body_returned,   :long,
+             :lacing_vals,     :pointer,
+             :granule_vals,    :pointer,
+             :lacing_storage,  :long,
+             :lacing_fill,     :long,
+             :lacing_packet,   :long,
+             :lacing_returned, :long,
+             :header,          [:uchar, 282],
+             :header_fill,     :int,
+             :e_o_s,           :int,
+             :b_o_s,           :int,
+             :serialno,        :long,
+             :pageno,          :long,
+             :packetno,        :int64,
+             :granulepos,      :int64
+    end
+
+    class OggPage < FFI::Struct
+      layout :header,     :pointer,
+             :header_len, :long,
+             :body,       :pointer,
+             :body_len,   :long
+    end
+
+    class OggPacket < FFI::Struct
+      layout :packet,     :pointer,
+             :bytes,      :long,
+             :b_o_s,      :long,
+             :e_o_s,      :long,
+             :granulepos, :int64,
+             :packetno,   :int64
+    end
+
+    # --- Sync API ---
+
+    attach_function :ogg_sync_init,     [:pointer],              :int
+    attach_function :ogg_sync_clear,    [:pointer],              :int
+    attach_function :ogg_sync_reset,    [:pointer],              :int
+    attach_function :ogg_sync_buffer,   [:pointer, :long],       :pointer
+    attach_function :ogg_sync_wrote,    [:pointer, :long],       :int
+    attach_function :ogg_sync_pageout,  [:pointer, :pointer],    :int
+    attach_function :ogg_sync_pageseek, [:pointer, :pointer],    :long
+
+    # --- Stream API ---
+
+    attach_function :ogg_stream_init,           [:pointer, :int],              :int
+    attach_function :ogg_stream_clear,          [:pointer],                    :int
+    attach_function :ogg_stream_reset,          [:pointer],                    :int
+    attach_function :ogg_stream_reset_serialno, [:pointer, :int],             :int
+    attach_function :ogg_stream_packetin,       [:pointer, :pointer],          :int
+    attach_function :ogg_stream_pageout,        [:pointer, :pointer],          :int
+    attach_function :ogg_stream_pageout_fill,   [:pointer, :pointer, :int],   :int
+    attach_function :ogg_stream_flush,          [:pointer, :pointer],          :int
+    attach_function :ogg_stream_flush_fill,     [:pointer, :pointer, :int],   :int
+    attach_function :ogg_stream_pagein,         [:pointer, :pointer],          :int
+    attach_function :ogg_stream_packetout,      [:pointer, :pointer],          :int
+    attach_function :ogg_stream_packetpeek,     [:pointer, :pointer],          :int
+    attach_function :ogg_stream_eos,            [:pointer],                    :int
+
+    # --- Page API ---
+
+    attach_function :ogg_page_version,       [:pointer], :int
+    attach_function :ogg_page_continued,     [:pointer], :int
+    attach_function :ogg_page_bos,           [:pointer], :int
+    attach_function :ogg_page_eos,           [:pointer], :int
+    attach_function :ogg_page_granulepos,    [:pointer], :int64
+    attach_function :ogg_page_serialno,      [:pointer], :int
+    attach_function :ogg_page_pageno,        [:pointer], :long
+    attach_function :ogg_page_packets,       [:pointer], :int
+    attach_function :ogg_page_checksum_set,  [:pointer], :void
+
+    # --- Packet API ---
+
+    attach_function :ogg_packet_clear, [:pointer], :void
+  end
+end

data/lib/ogg/packet.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Ogg
+  class Packet
+    attr_reader :native
+
+    def initialize(data: nil, bos: false, eos: false, granulepos: 0, packetno: 0, owner: nil)
+      @owner = owner
+      @ptr = FFI::MemoryPointer.new(Native::OggPacket.size)
+      @native = Native::OggPacket.new(@ptr)
+
+      if data
+        @data_ptr = FFI::MemoryPointer.new(:uint8, data.bytesize)
+        @data_ptr.put_bytes(0, data)
+        @native[:packet] = @data_ptr
+        @native[:bytes] = data.bytesize
+        @native[:b_o_s] = bos ? 1 : 0
+        @native[:e_o_s] = eos ? 1 : 0
+        @native[:granulepos] = granulepos
+        @native[:packetno] = packetno
+      end
+    end
+
+    def data
+      ensure_owner_active!
+      length = @native[:bytes]
+      raise Error, "packet bytes cannot be negative" if length.negative?
+      return +"".b if length.zero?
+
+      pointer = @native[:packet]
+      raise Error, "packet pointer is null while bytes=#{length}" if pointer.null?
+
+      pointer.read_bytes(length)
+    end
+
+    def bytes
+      @native[:bytes]
+    end
+
+    def bos?
+      @native[:b_o_s] != 0
+    end
+
+    def eos?
+      @native[:e_o_s] != 0
+    end
+
+    def granulepos
+      @native[:granulepos]
+    end
+
+    def packetno
+      @native[:packetno]
+    end
+
+    private
+
+    def ensure_owner_active!
+      return unless @owner&.cleared?
+
+      raise ReleasedResourceError, "cannot read packet data after owner state is cleared"
+    end
+  end
+end

data/lib/ogg/page.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Ogg
+  class Page
+    attr_reader :native
+
+    def initialize(native_page = nil, owner: nil)
+      @owner = owner
+      if native_page
+        @ptr = native_page
+        @native = native_page.is_a?(Native::OggPage) ? native_page : Native::OggPage.new(native_page)
+      else
+        @ptr = FFI::MemoryPointer.new(Native::OggPage.size)
+        @native = Native::OggPage.new(@ptr)
+      end
+    end
+
+    def version
+      ensure_owner_active!
+      Native.ogg_page_version(@ptr)
+    end
+
+    def continued?
+      ensure_owner_active!
+      Native.ogg_page_continued(@ptr) != 0
+    end
+
+    def bos?
+      ensure_owner_active!
+      Native.ogg_page_bos(@ptr) != 0
+    end
+
+    def eos?
+      ensure_owner_active!
+      Native.ogg_page_eos(@ptr) != 0
+    end
+
+    def granulepos
+      ensure_owner_active!
+      Native.ogg_page_granulepos(@ptr)
+    end
+
+    def serialno
+      ensure_owner_active!
+      Native.ogg_page_serialno(@ptr)
+    end
+
+    def pageno
+      ensure_owner_active!
+      Native.ogg_page_pageno(@ptr)
+    end
+
+    def packets
+      ensure_owner_active!
+      Native.ogg_page_packets(@ptr)
+    end
+
+    def header_data
+      read_segment(:header, :header_len)
+    end
+
+    def body_data
+      read_segment(:body, :body_len)
+    end
+
+    def to_s
+      header_data + body_data
+    end
+
+    private
+
+    def read_segment(pointer_field, length_field)
+      ensure_owner_active!
+      length = @native[length_field]
+      raise Error, "#{length_field} cannot be negative" if length.negative?
+      return +"".b if length.zero?
+
+      pointer = @native[pointer_field]
+      raise Error, "#{pointer_field} is null while #{length_field}=#{length}" if pointer.null?
+
+      pointer.read_bytes(length)
+    end
+
+    def ensure_owner_active!
+      return unless @owner&.cleared?
+
+      raise ReleasedResourceError, "cannot read page data after owner state is cleared"
+    end
+  end
+end

data/lib/ogg/stream_state.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Ogg
+  class StreamState
+    attr_reader :serialno
+
+    def initialize(serialno)
+      @serialno = serialno
+      @ptr = FFI::MemoryPointer.new(Native::OggStreamState.size)
+      result = Native.ogg_stream_init(@ptr, serialno)
+      raise StreamError, "ogg_stream_init failed with status #{result}" unless result == 0
+
+      @clear_state = [false]
+      ObjectSpace.define_finalizer(self, self.class.finalizer_for(@ptr, @clear_state))
+    end
+
+    def packetin(packet)
+      ensure_active!
+      result = Native.ogg_stream_packetin(@ptr, packet.native)
+      raise StreamError, "ogg_stream_packetin failed with status #{result}" unless result == 0
+    end
+
+    def pageout
+      ensure_active!
+      page = Page.new(owner: self)
+      result = Native.ogg_stream_pageout(@ptr, page.native)
+      case result
+      when 1 then page
+      when 0 then nil
+      when -1 then raise StreamCorruptDataError, "ogg_stream_pageout detected stream corruption"
+      else raise StreamError, "ogg_stream_pageout returned unexpected status #{result}"
+      end
+    end
+
+    def flush
+      ensure_active!
+      page = Page.new(owner: self)
+      result = Native.ogg_stream_flush(@ptr, page.native)
+      case result
+      when 1 then page
+      when 0 then nil
+      when -1 then raise StreamCorruptDataError, "ogg_stream_flush detected stream corruption"
+      else raise StreamError, "ogg_stream_flush returned unexpected status #{result}"
+      end
+    end
+
+    def pagein(page)
+      ensure_active!
+      result = Native.ogg_stream_pagein(@ptr, page.native)
+      case result
+      when 0 then nil
+      when -1 then raise StreamCorruptDataError, "ogg_stream_pagein detected stream corruption"
+      else raise StreamError, "ogg_stream_pagein failed with status #{result}"
+      end
+    end
+
+    def packetout
+      ensure_active!
+      packet = Packet.new(owner: self)
+      result = Native.ogg_stream_packetout(@ptr, packet.native)
+      case result
+      when 1 then packet
+      when 0 then nil
+      when -1 then raise StreamCorruptDataError, "ogg_stream_packetout detected a hole in the stream"
+      else raise StreamError, "ogg_stream_packetout returned unexpected status #{result}"
+      end
+    end
+
+    def packetpeek
+      ensure_active!
+      packet = Packet.new(owner: self)
+      result = Native.ogg_stream_packetpeek(@ptr, packet.native)
+      case result
+      when 1 then packet
+      when 0 then nil
+      when -1 then raise StreamCorruptDataError, "ogg_stream_packetpeek detected a hole in the stream"
+      else raise StreamError, "ogg_stream_packetpeek returned unexpected status #{result}"
+      end
+    end
+
+    def eos?
+      ensure_active!
+      result = Native.ogg_stream_eos(@ptr)
+      case result
+      when 0 then false
+      when 1 then true
+      else
+        raise StreamError, "ogg_stream_eos returned unexpected status #{result}"
+      end
+    end
+
+    def reset
+      ensure_active!
+      result = Native.ogg_stream_reset(@ptr)
+      raise StreamError, "ogg_stream_reset failed with status #{result}" unless result == 0
+    end
+
+    def reset_serialno(serialno)
+      ensure_active!
+      result = Native.ogg_stream_reset_serialno(@ptr, serialno)
+      raise StreamError, "ogg_stream_reset_serialno failed with status #{result}" unless result == 0
+
+      @serialno = serialno
+    end
+
+    def clear
+      return if cleared?
+
+      result = Native.ogg_stream_clear(@ptr)
+      raise StreamError, "ogg_stream_clear failed with status #{result}" unless result == 0
+
+      @clear_state[0] = true
+    end
+
+    def cleared?
+      @clear_state[0]
+    end
+
+    def self.finalizer_for(ptr, clear_state)
+      proc do
+        Native.ogg_stream_clear(ptr) unless clear_state[0]
+      end
+    end
+
+    private
+
+    def ensure_active!
+      return unless cleared?
+
+      raise ReleasedResourceError, "stream state has been cleared"
+    end
+  end
+end

data/lib/ogg/sync_state.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Ogg
+  class SyncState
+    def initialize
+      @ptr = FFI::MemoryPointer.new(Native::OggSyncState.size)
+      result = Native.ogg_sync_init(@ptr)
+      raise SyncError, "ogg_sync_init failed with status #{result}" unless result == 0
+
+      @clear_state = [false]
+      ObjectSpace.define_finalizer(self, self.class.finalizer_for(@ptr, @clear_state))
+    end
+
+    def write(data)
+      ensure_active!
+      buffer = Native.ogg_sync_buffer(@ptr, data.bytesize)
+      raise SyncError, "ogg_sync_buffer returned null" if buffer.null?
+
+      buffer.put_bytes(0, data)
+      result = Native.ogg_sync_wrote(@ptr, data.bytesize)
+      raise SyncError, "ogg_sync_wrote failed with status #{result}" unless result == 0
+    end
+
+    def pageout
+      ensure_active!
+      page = Page.new(owner: self)
+      result = Native.ogg_sync_pageout(@ptr, page.native)
+      case result
+      when 1 then page
+      when 0 then nil
+      when -1 then raise SyncCorruptDataError, "ogg_sync_pageout detected unsynced/corrupt data"
+      else raise SyncError, "ogg_sync_pageout returned unexpected status #{result}"
+      end
+    end
+
+    def reset
+      ensure_active!
+      result = Native.ogg_sync_reset(@ptr)
+      raise SyncError, "ogg_sync_reset failed with status #{result}" unless result == 0
+    end
+
+    def clear
+      return if cleared?
+
+      result = Native.ogg_sync_clear(@ptr)
+      raise SyncError, "ogg_sync_clear failed with status #{result}" unless result == 0
+
+      @clear_state[0] = true
+    end
+
+    def cleared?
+      @clear_state[0]
+    end
+
+    def self.finalizer_for(ptr, clear_state)
+      proc do
+        Native.ogg_sync_clear(ptr) unless clear_state[0]
+      end
+    end
+
+    private
+
+    def ensure_active!
+      return unless cleared?
+
+      raise ReleasedResourceError, "sync state has been cleared"
+    end
+  end
+end

data/lib/ogg/version.rb

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

data/lib/ogg.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "ffi"
+require_relative "ogg/version"
+require_relative "ogg/native"
+require_relative "ogg/page"
+require_relative "ogg/packet"
+require_relative "ogg/sync_state"
+require_relative "ogg/stream_state"
+
+module Ogg
+  class Error < StandardError; end
+  class ReleasedResourceError < Error; end
+  class CorruptDataError < Error; end
+  class SyncError < Error; end
+  class SyncCorruptDataError < SyncError; end
+  class StreamError < Error; end
+  class StreamCorruptDataError < StreamError; end
+end

metadata

@@ -0,0 +1,68 @@
+--- !ruby/object:Gem::Specification
+name: ogg-ruby
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yudai Takada
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ffi
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.15'
+description: A Ruby FFI binding library for libogg, providing OGG container format
+  stream operations (page read/write, packet assembly/disassembly).
+email:
+- t.yudai92@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/ogg.rb
+- lib/ogg/native.rb
+- lib/ogg/packet.rb
+- lib/ogg/page.rb
+- lib/ogg/stream_state.rb
+- lib/ogg/sync_state.rb
+- lib/ogg/version.rb
+homepage: https://github.com/ydah/ogg-ruby
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/ydah/ogg-ruby
+  source_code_uri: https://github.com/ydah/ogg-ruby
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: Ruby FFI bindings for libogg
+test_files: []