ffi-shout 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3afeb4f1d4e446f230a11be7e907e5ca99cc60bfe591cb10902b951ba7fc9a41
+  data.tar.gz: efc7c5332efca1d45ffba08ca66357796bf3a800e2584189214fc974807bd8a7
+SHA512:
+  metadata.gz: 3b3de3046e1fb2875a36481ac428e2142b761291597f0a959e34480845cfef5ee8c2c6a73df322e94896eead1b68c7acbc0bc77366edc324bbbe710941ed9657
+  data.tar.gz: ff0ab48f10510901e8a4321eeefd73f4609cb2423262897c942c0ca80f0d03880f078d4f8e36c4ac9bfebd694fa10682186f765fb412f04b6d7a0031aaf3bf46

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release.

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2026 Roel van Dijk
+
+MIT License
+
+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,278 @@
+# ffi-shout
+
+Ruby FFI bindings for [libshout](https://icecast.org/), the streaming library for Icecast.
+
+See [CHANGELOG.md](CHANGELOG.md) for what changed.
+
+## Installation
+
+### Requirements
+
+- Ruby 3.2 or newer
+- libshout 2.4.6 or newer, including its development files:
+  - Ubuntu / Debian: `sudo apt-get install libshout3-dev`
+  - Arch Linux: `sudo pacman -S libshout`
+  - macOS (Homebrew): `brew install libshout`
+
+Older distributions may ship an older libshout; check with `pkg-config --modversion shout`. With libshout older than 2.4.6, `require "shout"` raises a `LoadError` that names the version it found.
+
+### Gem Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "ffi-shout"
+```
+
+And run:
+
+```bash
+bundle install
+```
+
+Then load it with `require "shout"` (or `require "ffi-shout"`; Bundler's auto-require uses that one). The library lives in the `Shout` module.
+
+The older, unmaintained [ruby-shout](https://rubygems.org/gems/ruby-shout) gem (a C extension) also installs `shout.rb` and defines a top-level `Shout` class, so the two gems can't be used together.
+
+## Usage
+
+### Connecting and Streaming to Icecast
+
+#### 1. Automatic Lifecycle (Block Form)
+
+You can pass a block to `connect`, which automatically handles disconnecting when the block completes (even if an exception is raised). `connect` returns the block's value.
+
+```ruby
+require "shout"
+
+connection = Shout::Connection.new do |conn|
+  conn.configuration.host = "127.0.0.1"
+  conn.configuration.port = 8000
+  conn.configuration.mount = "/stream.mp3"
+  conn.configuration.user = "source"
+  conn.configuration.password = "hackme"
+  conn.configuration.protocol = :http
+  conn.configuration.set_content_format(:mp3)
+
+  # Audio information
+  conn.configuration.audio_info.bitrate = 128
+  conn.configuration.audio_info.samplerate = 44100
+  conn.configuration.audio_info.channels = 2
+
+  # Stream metadata
+  conn.configuration.meta.name = "My Radio Station"
+  conn.configuration.meta.genre = "Rock"
+  conn.configuration.meta.description = "Awesome Radio Stream"
+  conn.configuration.meta.url = "https://example.com"
+end
+
+# Connect to Icecast with automatic disconnect
+connection.connect do |conn|
+  # Update song metadata
+  conn.update_metadata(song: "Queen - Bohemian Rhapsody")
+
+  # Stream audio chunks
+  File.open("audio.mp3", "rb") do |file|
+    while (chunk = file.read(4096))
+      conn.send_data(chunk)
+
+      # Wait for the server timing synchronization
+      conn.sync
+    end
+  end
+end
+# Automatically disconnected once the block exits
+```
+
+Configuration attributes can also be passed as keyword arguments, and `Connection.open` creates and connects in one step:
+
+```ruby
+Shout::Connection.open(host: "127.0.0.1", port: 8000, mount: "/stream.mp3",
+                       user: "source", password: "hackme") do |conn|
+  conn.update_metadata(song: "Daft Punk - One More Time")
+  # ...
+end
+```
+
+An unknown attribute raises `ArgumentError` (for example `unknown attribute(s): hots`). Settings without a keyword form, such as `set_content_format` or `audio_info`, go in a block as above.
+
+#### 2. Manual Lifecycle (Holding the Connection in a Field)
+
+If you need a long-running stream managed across multiple methods or worker events, call `connect` without a block. This returns the connection instance, allowing you to store it in an instance variable (field) and explicitly call `disconnect` (or `close`) later:
+
+```ruby
+require "shout"
+
+class RadioBroadcaster
+  attr_reader :connection
+
+  def initialize
+    @connection = Shout::Connection.new do |conn|
+      conn.configuration.host = "127.0.0.1"
+      conn.configuration.port = 8000
+      conn.configuration.mount = "/stream.mp3"
+      conn.configuration.user = "source"
+      conn.configuration.password = "hackme"
+      conn.configuration.protocol = :http
+      conn.configuration.set_content_format(:mp3)
+    end
+  end
+
+  def start
+    # Connects and keeps the socket open
+    @connection.connect
+  end
+
+  def broadcast(chunk)
+    @connection.send_data(chunk).sync
+  end
+
+  def change_track(title)
+    @connection.update_metadata(song: title)
+  end
+
+  def stop
+    # Manually close the connection when done
+    @connection.disconnect if @connection.connected?
+  end
+end
+
+# Example usage:
+broadcaster = RadioBroadcaster.new
+broadcaster.start
+
+broadcaster.change_track("Led Zeppelin - Immigrant Song")
+broadcaster.broadcast(audio_data) # audio_data: a chunk of MP3 data, e.g. from File#read
+
+# ... later in your application lifecycle:
+broadcaster.stop
+```
+
+`send_data` (and its aliases `write` and `<<`), `sync` and `disconnect` return the connection, so calls can be chained: `connection << chunk1 << chunk2`.
+
+#### Blocking and threads
+
+libshout calls that wait on the network (`connect`, `send_data`, `sync`, `disconnect`) block the calling thread but let other Ruby threads keep running.
+
+Non-blocking mode (`nonblocking = :none`) is not supported yet: in that mode libshout reports a busy connection, which this gem raises as `Shout::BusyError` instead of retrying.
+
+### Sending Metadata
+
+You can update stream metadata dynamically at any time while connected:
+
+```ruby
+# Using a String (defaults to "song" metadata)
+connection.metadata = "Artist - Song Title"
+
+# Using a Hash
+connection.update_metadata(song: "Artist - Song Title")
+
+# Using a Shout::Metadata object
+metadata = Shout::Metadata.new(song: "Artist - Song Title")
+connection.send_metadata(metadata)
+```
+
+`Shout::Metadata` behaves like a small hash of strings: `metadata["song"]` reads a value, `metadata.add("artist", "Queen")` (or `metadata["artist"] = "Queen"`) adds one, it is `Enumerable` (`each` yields key and value), and two instances with the same keys and values are equal.
+
+With the HTTP protocol (the default), metadata updates don't go through libshout's `shout_set_metadata_utf8`. With Icecast 2.5, libshout 2.4.6 never returns from that call ([icecast-libshout#2341](https://gitlab.xiph.org/xiph/icecast-libshout/-/issues/2341)). Instead, this gem sends the request to Icecast's `/admin/metadata` endpoint itself, with the source credentials included in the first request. Other protocols still use libshout.
+
+- Requests time out after 5 seconds. Change this with `connection.metadata_timeout = 2`.
+- Failures raise `Shout::LoginError` (credentials rejected), `Shout::MetadataError` (the server refused the update) or `Shout::ConnectionError` (network error or timeout).
+- For TLS, set `tls` to `:rfc2818` (HTTPS) or `:disabled`/`:auto` (plain HTTP). `:auto_no_plain` and `:rfc2817` raise `Shout::UnsupportedError` for metadata updates.
+
+> **Security note:** with `tls = :auto` (libshout's default), libshout may upgrade the audio connection to TLS, but metadata updates are sent over plain HTTP, so the source password is sent unencrypted. If you rely on TLS, set `tls = :rfc2818`.
+
+### Configuration Options
+
+The configuration object exposes all properties supported by `shout.h`:
+
+```ruby
+connection.configure do |config|
+  # Server parameters
+  config.host = "localhost"
+  config.port = 8000
+  config.mount = "/mountpoint"
+  config.user = "source"
+  config.password = "secret"
+  config.agent = "CustomAgent/1.0"
+
+  # Protocol & Format
+  config.protocol = :http       # :http, :xaudiocast, :icy, :roaraudio
+  config.set_content_format(:mp3) # :mp3, :ogg, :webm, :matroska, :text
+
+  # TLS options
+  config.tls = :auto            # :disabled, :auto, :auto_no_plain, :rfc2818, :rfc2817
+  config.ca_directory = "/etc/ssl/certs"
+  config.ca_file = "/etc/ssl/cert.pem"
+
+  # Streaming options
+  config.public = false
+  config.nonblocking = :full    # :full (blocking); :none is not supported yet, see above
+  config.content_language = "en-US"
+
+  # Audio info
+  config.audio_info.bitrate = 320
+  config.audio_info.samplerate = 44100
+  config.audio_info.channels = 2
+  config.audio_info.quality = 5
+
+  # Station meta
+  config.meta.name = "My Station"
+  config.meta.url = "http://myradio.fm"
+  config.meta.genre = "Electronic"
+  config.meta.description = "24/7 Electronic Music"
+end
+```
+
+Settings that take a symbol also read back as one: `config.protocol` returns `:http`, `config.tls` returns `:auto`, and `config.content_format.format` returns `:mp3`. Setting an unknown symbol raises `ArgumentError`. The on/off flags also have a `?` reader: `config.public?` and `config.nonblocking?`.
+
+`config.format=`, `config.name=`, `config.url=`, `config.genre=`, `config.description=` and `config.dumpfile=` call libshout functions that libshout marks obsolete. They still work, but print a deprecation warning when Ruby's deprecation warnings are on (`ruby -W:deprecated`). Use `set_content_format` and `config.meta.*` instead.
+
+### Errors
+
+Every libshout error is raised as a subclass of `Shout::ShoutError`, so `rescue Shout::ShoutError` catches them all. The message is libshout's own error text where available.
+
+| Class | libshout error |
+|---|---|
+| `Shout::InsaneError` | `SHOUTERR_INSANE`: invalid parameters or state |
+| `Shout::ConnectionError` | `SHOUTERR_NOCONNECT`: couldn't connect (also network errors in HTTP metadata updates) |
+| `Shout::LoginError` | `SHOUTERR_NOLOGIN`: the server rejected the login |
+| `Shout::SocketIOError` | `SHOUTERR_SOCKET`: error while talking to the server |
+| `Shout::MallocError` | `SHOUTERR_MALLOC`: out of memory |
+| `Shout::MetadataError` | `SHOUTERR_METADATA`: metadata update failed |
+| `Shout::ConnectedError` | `SHOUTERR_CONNECTED`: can't change this while connected |
+| `Shout::UnconnectedError` | `SHOUTERR_UNCONNECTED`: not connected |
+| `Shout::UnsupportedError` | `SHOUTERR_UNSUPPORTED`: not supported by this server, protocol or format |
+| `Shout::BusyError` | `SHOUTERR_BUSY`: busy, try again later (non-blocking mode) |
+| `Shout::NoTLSError` | `SHOUTERR_NOTLS`: TLS requested but not available |
+| `Shout::TLSBadCertError` | `SHOUTERR_TLSBADCERT`: the server's TLS certificate failed verification |
+| `Shout::RetryError` | `SHOUTERR_RETRY`: try again |
+
+### libshout Version
+
+`Shout.version` describes the loaded libshout library:
+
+```ruby
+Shout.version.to_s        # => "2.4.6"
+Shout.version >= "2.4.6"  # => true
+```
+
+### Low-level libshout Functions
+
+Every function in `shout.h` is attached to `Shout::Native`, an `FFI::Library`, for anything `Shout::Connection` doesn't cover. `Native.shout_new` returns a handle that frees itself when it is garbage collected, and settings with libshout constants take and return symbols:
+
+```ruby
+shout = Shout::Native.shout_new
+Shout::Native.shout_set_protocol(shout, :icy)
+Shout::Native.shout_get_protocol(shout)  # => :icy
+```
+
+These functions return libshout's error codes instead of raising, and their API follows libshout rather than this gem.
+
+## Development
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for how to set up the project, run the specs (including the integration specs against a local Icecast server) and which Ruby versions changes need to support.
+
+## License
+
+MIT License. See [LICENSE.txt](LICENSE.txt).

data/lib/ffi-shout.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+# Entry point matching the gem name, so `require "ffi-shout"` and
+# `Bundler.require` load the library. Same as `require "shout"`.
+require "shout"

data/lib/shout/configuration.rb

@@ -0,0 +1,157 @@
+# frozen_string_literal: true
+
+module Shout
+  # Base class for configuration objects that read and write settings on a
+  # libshout handle.
+  class ConfigurationBase
+    extend Delegation
+
+    attr_reader :shout
+
+    def initialize(shout)
+      @shout = shout
+    end
+  end
+
+  # Connection settings (host, mount, credentials, protocol, ...) stored on a
+  # libshout handle. Each attribute reads and writes the matching
+  # shout_get_*/shout_set_* function.
+  class Configuration < ConfigurationBase
+    delegate_alias_to_shout username: :user,
+                            pass: :password,
+                            mountpoint: :mount,
+                            user_agent: :agent
+
+    delegate_to_shout :host, :port, :agent, :tls, :ca_directory, :ca_file,
+                      :allowed_ciphers, :user, :password, :client_certificate,
+                      :mount, :content_language, :protocol, :nonblocking
+
+    delegate_to_shout :public, predicate: true
+
+    # Settings that libshout marks obsolete. Their writers print a deprecation
+    # warning (shown with `ruby -W:deprecated`).
+    OBSOLETE_SETTINGS = {
+      name: "meta.name=",
+      url: "meta.url=",
+      genre: "meta.genre=",
+      description: "meta.description=",
+      format: "set_content_format",
+      dumpfile: nil # only useful with the deprecated xaudiocast protocol
+    }.freeze
+
+    delegate_to_shout(*OBSOLETE_SETTINGS.keys)
+
+    prepend(Module.new do
+      OBSOLETE_SETTINGS.each do |name, replacement|
+        define_method(:"#{name}=") do |value|
+          advice = replacement ? "; use #{replacement} instead" : ""
+          warn "Shout::Configuration##{name}= is obsolete in libshout#{advice}", category: :deprecated, uplevel: 1
+          super(value)
+        end
+      end
+    end)
+
+    def nonblocking?
+      nonblocking == :none
+    end
+
+    def audio_info
+      @audio_info ||= AudioInfo.new(shout)
+    end
+
+    def meta
+      @meta ||= Meta.new(shout)
+    end
+
+    def content_format
+      @content_format ||= ContentFormat.new(shout)
+    end
+
+    def set_content_format(format, usage = SHOUT_USAGE_AUDIO, codecs = nil)
+      content_format.set(format, usage, codecs)
+    end
+
+    # Base for settings that libshout stores as string key/value pairs. Each
+    # subclass names its getter and setter function and its known keys; every
+    # known key gets a reader and a writer, and any key works with [] / []=.
+    class KeyValueSettings < ConfigurationBase
+      def self.settings(getter:, setter:, **keys)
+        define_method(:[]) do |key|
+          Native.public_send(getter, shout, key.to_s)
+        end
+
+        define_method(:[]=) do |key, value|
+          Error.check_error(Native.public_send(setter, shout, key.to_s, value&.to_s), shout)
+        end
+
+        keys.each { |name, key| define_key_accessors(name, key) }
+      end
+
+      def self.define_key_accessors(name, key)
+        define_method(name) { self[key] }
+        define_method(:"#{name}=") { |value| self[key] = value }
+      end
+      private_class_method :define_key_accessors
+    end
+
+    # Audio parameters advertised to the server (shout_set_audio_info).
+    class AudioInfo < KeyValueSettings
+      settings getter: :shout_get_audio_info, setter: :shout_set_audio_info,
+               bitrate: SHOUT_AI_BITRATE,
+               samplerate: SHOUT_AI_SAMPLERATE,
+               channels: SHOUT_AI_CHANNELS,
+               quality: SHOUT_AI_QUALITY
+    end
+
+    # Stream description such as name, genre and URL (shout_set_meta).
+    class Meta < KeyValueSettings
+      settings getter: :shout_get_meta, setter: :shout_set_meta,
+               name: SHOUT_META_NAME,
+               url: SHOUT_META_URL,
+               genre: SHOUT_META_GENRE,
+               description: SHOUT_META_DESCRIPTION,
+               irc: SHOUT_META_IRC,
+               aim: SHOUT_META_AIM,
+               icq: SHOUT_META_ICQ
+    end
+
+    # Content format, usage and codecs of the stream (shout_set_content_format).
+    class ContentFormat < ConfigurationBase
+      def set(format, usage = SHOUT_USAGE_AUDIO, codecs = nil)
+        format = Delegation::TypeConvertor.convert(format)
+        Error.check_error(Native.shout_set_content_format(shout, format, usage, codecs), shout)
+        self
+      end
+
+      # The format as a symbol such as :mp3 (or the raw value if unknown).
+      def format
+        value = info[0]
+        Native.enum_type(:shout_format)[value] || value
+      end
+
+      def usage
+        info[1]
+      end
+
+      def codecs
+        info[2]
+      end
+
+      private
+
+      def info
+        format_ptr = FFI::MemoryPointer.new(:uint)
+        usage_ptr  = FFI::MemoryPointer.new(:uint)
+        codecs_ptr = FFI::MemoryPointer.new(:pointer)
+
+        ret = Native.shout_get_content_format(shout, format_ptr, usage_ptr, codecs_ptr)
+        Error.check_error(ret, shout)
+
+        c_str_ptr = codecs_ptr.read_pointer
+        codecs_str = c_str_ptr.null? ? nil : c_str_ptr.read_string
+
+        [format_ptr.read_uint, usage_ptr.read_uint, codecs_str]
+      end
+    end
+  end
+end

data/lib/shout/connection.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module Shout
+  # A source connection to an Icecast server: configure it, connect, send
+  # audio data and update the stream's metadata.
+  #
+  # Commands (disconnect, send_data, sync, configure) return the connection,
+  # so they can be chained: `connection << chunk1 << chunk2`.
+  class Connection
+    attr_reader :shout
+
+    # Seconds to wait for the server when updating metadata over HTTP.
+    attr_writer :metadata_timeout
+
+    def metadata_timeout
+      @metadata_timeout || HttpMetadata::DEFAULT_TIMEOUT
+    end
+
+    # Creates a connection and connects. With a block, yields the connection,
+    # disconnects afterwards and returns the block's value.
+    def self.open(**, &)
+      new(**).connect(&)
+    end
+
+    # Creates a connection, optionally setting configuration attributes, e.g.
+    # Connection.new(host: "localhost", port: 8000, mount: "/live.mp3").
+    # Raises ArgumentError for attributes the configuration doesn't have.
+    def initialize(**attributes)
+      @shout = Native.shout_new
+      assign_attributes(attributes)
+
+      yield self if block_given?
+    end
+
+    def configure
+      yield configuration
+      self
+    end
+
+    def configuration
+      @configuration ||= Configuration.new(shout)
+    end
+
+    # Connects to the server. Without a block, returns the connection. With a
+    # block, yields the connection, disconnects afterwards (also when the
+    # block raises) and returns the block's value.
+    def connect
+      Error.check_error(Native.shout_open(shout), shout)
+      return self unless block_given?
+
+      begin
+        yield self
+      ensure
+        disconnect
+      end
+    end
+    alias open connect
+
+    # Disconnects; does nothing when not connected.
+    def disconnect
+      ret = Native.shout_close(shout)
+      Error.check_error(ret, shout) unless ret == SHOUTERR_UNCONNECTED
+      self
+    end
+    alias close disconnect
+
+    def connected?
+      Native.shout_get_connected(shout) == SHOUTERR_CONNECTED
+    end
+
+    # Sends audio data, which libshout parses for timing information.
+    def send_data(data)
+      with_buffer(data) { |ptr, len| Error.check_error(Native.shout_send(shout, ptr, len), shout) }
+      self
+    end
+    alias write send_data
+    alias << send_data
+
+    # Sends data without parsing it. Returns the number of bytes written.
+    def send_raw(data)
+      with_buffer(data) do |ptr, len|
+        Native.shout_send_raw(shout, ptr, len).tap { |ret| Error.check_error(ret, shout) }
+      end
+    end
+
+    # Number of bytes waiting in the send queue (only useful in nonblocking mode).
+    def queuelen
+      Native.shout_queuelen(shout).tap { |ret| Error.check_error(ret, shout) }
+    end
+
+    # Sleeps until it is time to send more data.
+    def sync
+      Native.shout_sync(shout)
+      self
+    end
+
+    # Milliseconds to wait before sending more data.
+    def delay
+      Native.shout_delay(shout).tap { |ret| Error.check_error(ret, shout) }
+    end
+
+    # Updates the stream's metadata. Accepts a Metadata, a Hash or a String
+    # (used as the "song" value). Returns the Metadata that was sent.
+    def send_metadata(metadata_or_hash)
+      raise UnconnectedError, "Cannot send metadata to an unconnected stream" unless connected?
+
+      metadata = coerce_metadata(metadata_or_hash)
+      if http_protocol?
+        # libshout's own HTTP metadata update can loop forever; see HttpMetadata.
+        HttpMetadata.new(configuration, timeout: metadata_timeout).update(metadata)
+      else
+        Error.check_error(Native.shout_set_metadata_utf8(shout, metadata.handle), shout)
+      end
+      metadata
+    end
+    alias update_metadata send_metadata
+    alias metadata= send_metadata
+
+    def error
+      Native.shout_get_error(shout)
+    end
+
+    def errno
+      Native.shout_get_errno(shout)
+    end
+
+    private
+
+    def http_protocol?
+      configuration.protocol == :http
+    end
+
+    # Copies +data+ into native memory for the duration of the block. libshout
+    # calls release the GVL, so they must not read a Ruby string's memory.
+    def with_buffer(data)
+      bytes = data.to_s
+      ptr = FFI::MemoryPointer.new(:char, bytes.bytesize)
+      ptr.put_bytes(0, bytes)
+      yield ptr, bytes.bytesize
+    end
+
+    def assign_attributes(attributes)
+      unknown = attributes.keys.reject { |key| configuration.respond_to?(:"#{key}=") }
+      raise ArgumentError, "unknown attribute(s): #{unknown.join(", ")}" if unknown.any?
+
+      attributes.each { |key, value| configuration.public_send(:"#{key}=", value) }
+    end
+
+    def coerce_metadata(value)
+      case value
+      when Metadata then value
+      when Hash then Metadata.new(value)
+      when String then Metadata.new("song" => value)
+      else raise ArgumentError, "Expected Metadata, Hash, or String, got #{value.class}"
+      end
+    end
+  end
+
+  Client = Connection
+end