eleven_rb 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2402cc8af1a30f52cf74017c0f24adc423ae932616fe74296e1fe09a635c628b
-  data.tar.gz: f149ab57fc621a178b5e2b4443a6cc02fb830769e2053152b86b246dbc8ca2cb
+  metadata.gz: 80d8ceea950da279e7f35661aa4597eef9f6ff51fb67e38e607f634eaaa54feb
+  data.tar.gz: 8afa2939e1c267ee50c74ae2c6fe4fe8ea4f9fe0618ebb3d3cb52bc09f0c2683
 SHA512:
-  metadata.gz: 42df0d9c9095233697e41aa08e98297090fc1def3f5e16c4c3f248ddd60650d5be8fb85456ab41b352c92bc3dbd8208041010764a61b7143bdcfda706b890b7f
-  data.tar.gz: 50ba905bccdddb14a8148345f69461a98cdc58659e1a6a3c75098de02744962a76d354fcd48326fc29722c3d03a81c9cd426be47706f5e5eb0d91faf38a4161b
+  metadata.gz: 0cb196287b9bad7eafa9e34ac6b3c30933f9d9e316d42728fd9a609cb83db95e0b63d307568a8000bfcaf1613d059026c63ff83e75cd70e9c2f686874be72d0a
+  data.tar.gz: 22e29e9eab3a7e04a3ca040bf4cd564b70dd0077a777acbf095dc17eb5f64f3958578c457eb9f487c95a3194b7b62a9b97cf590bc8744c50f392c14af3532027

data/CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2026-02-07
+
+### Added
+
+- Sound effects generation via `client.sound_effects.generate` (`POST /v1/sound-generation`)
+- `ElevenRb::Error` top-level alias for `ElevenRb::Errors::Base`
+- `Client#configured?` and `Configuration#configured?` predicate methods
+
+### Changed
+
+- API key validation deferred to first API call (lazy configuration) — `Client.new` no longer raises without a key
+
 ## [0.1.0] - 2026-01-21
 
 ### Added

data/README.md

@@ -4,11 +4,12 @@
 [![CI](https://github.com/webventures/eleven_rb/actions/workflows/ci.yml/badge.svg)](https://github.com/webventures/eleven_rb/actions/workflows/ci.yml)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A Ruby client for the [ElevenLabs](https://try.elevenlabs.io/qyk2j8gumrjz) Text-to-Speech API.
+A Ruby client for the [ElevenLabs](https://try.elevenlabs.io/qyk2j8gumrjz) Text-to-Speech and Sound Effects API.
 
 ## Features
 
 - Text-to-Speech generation and streaming
+- Sound effects generation from text descriptions
 - Voice management (list, get, create, update, delete)
 - Voice Library access (search 10,000+ community voices)
 - Voice Slot Manager for automatic slot management within account limits
@@ -86,6 +87,28 @@ File.open("output.mp3", "wb") do |file|
 end
 ```
 
+### Sound Effects
+
+```ruby
+# Generate a sound effect from a text description
+audio = client.sound_effects.generate("thunder rumbling in the distance")
+audio.save_to_file("thunder.mp3")
+
+# With options
+audio = client.sound_effects.generate(
+  "footsteps on gravel",
+  duration_seconds: 3.0,
+  prompt_influence: 0.5,
+  output_format: "mp3_44100_192"
+)
+
+# Generate a loopable sound effect
+audio = client.sound_effects.generate("gentle rain", loop: true)
+
+# Convenience method
+audio = client.generate_sound_effect("explosion")
+```
+
 ### Voice Management
 
 ```ruby
@@ -248,10 +271,20 @@ rescue ElevenRb::Errors::ValidationError => e
 rescue ElevenRb::Errors::APIError => e
   puts "API error: #{e.message} (status: #{e.http_status})"
 end
+
+# Or use the top-level alias to catch all ElevenRb errors
+begin
+  audio = client.tts.generate("Hello", voice_id: "abc123")
+rescue ElevenRb::Error => e
+  puts "Something went wrong: #{e.message}"
+end
 ```
 
 ## Rails Integration
 
+The client can be initialized without an API key and won't raise until the first API call,
+making it safe to use in test/CI environments where the key may not be set.
+
 ```ruby
 # config/initializers/eleven_rb.rb
 ElevenRb.configure do |config|

data/lib/eleven_rb/client.rb

@@ -34,10 +34,16 @@ module ElevenRb
         api_key: api_key || ENV.fetch('ELEVENLABS_API_KEY', nil),
         **options
       )
-      @config.validate!
       @http_client = HTTP::Client.new(@config)
     end
 
+    # Check if the client is configured with an API key
+    #
+    # @return [Boolean]
+    def configured?
+      config.configured?
+    end
+
     # Voice management resource
     #
     # @return [Resources::Voices]
@@ -73,6 +79,13 @@ module ElevenRb
       @user ||= Resources::User.new(http_client)
     end
 
+    # Sound effects resource
+    #
+    # @return [Resources::SoundEffects]
+    def sound_effects
+      @sound_effects ||= Resources::SoundEffects.new(http_client)
+    end
+
     # Voice slot manager
     #
     # @return [VoiceSlotManager]
@@ -90,6 +103,15 @@ module ElevenRb
       tts.generate(text, voice_id: voice_id, **options)
     end
 
+    # Convenience method: generate sound effect
+    #
+    # @param text [String] description of the sound effect
+    # @param options [Hash] additional options
+    # @return [Objects::Audio]
+    def generate_sound_effect(text, **options)
+      sound_effects.generate(text, **options)
+    end
+
     # Convenience method: stream speech
     #
     # @param text [String] the text to convert

data/lib/eleven_rb/configuration.rb

@@ -57,6 +57,13 @@ module ElevenRb
       end
     end
 
+    # Check if the configuration has an API key
+    #
+    # @return [Boolean]
+    def configured?
+      !api_key.nil? && !api_key.to_s.empty?
+    end
+
     # Validate the configuration
     #
     # @raise [Errors::ConfigurationError] if configuration is invalid

data/lib/eleven_rb/errors.rb

@@ -55,4 +55,9 @@ module ElevenRb
     class ConnectionError < Base; end
     class TimeoutError < ConnectionError; end
   end
+
+  # Top-level error alias for conventional rescue usage
+  # @example
+  #   rescue ElevenRb::Error => e
+  Error = Errors::Base
 end

data/lib/eleven_rb/http/client.rb

@@ -68,6 +68,7 @@ module ElevenRb
 
       def request(method, path, body: nil, params: nil, response_type: :json, multipart: false, stream: false,
                   attempt: 1, &block)
+        config.validate!
         url = "#{config.base_url}#{path}"
         start_time = Time.now
 

data/lib/eleven_rb/resources/sound_effects.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Resources
+    # Sound effects generation resource
+    #
+    # @example Generate a sound effect
+    #   audio = client.sound_effects.generate("thunder rumbling in the distance")
+    #   audio.save_to_file("thunder.mp3")
+    #
+    # @example With options
+    #   audio = client.sound_effects.generate(
+    #     "footsteps on gravel",
+    #     duration_seconds: 3.0,
+    #     prompt_influence: 0.5
+    #   )
+    class SoundEffects < Base
+      DEFAULT_MODEL = 'eleven_text_to_sound_v2'
+
+      # Generate a sound effect from a text description
+      #
+      # @param text [String] description of the sound effect to generate
+      # @param model_id [String] the model to use (default: eleven_text_to_sound_v2)
+      # @param duration_seconds [Float, nil] desired duration in seconds (optional, API decides if omitted)
+      # @param prompt_influence [Float, nil] how closely to follow the prompt (0.0-1.0)
+      # @param loop [Boolean, nil] whether to generate a loopable sound effect
+      # @param output_format [String] audio output format
+      # @return [Objects::Audio]
+      def generate(text, model_id: DEFAULT_MODEL, duration_seconds: nil, prompt_influence: nil, loop: nil,
+                   output_format: 'mp3_44100_128')
+        validate_presence!(text, 'text')
+
+        body = {
+          text: text,
+          model_id: model_id
+        }
+        body[:duration_seconds] = duration_seconds unless duration_seconds.nil?
+        body[:prompt_influence] = prompt_influence unless prompt_influence.nil?
+        body[:loop] = loop unless loop.nil?
+
+        path = "/sound-generation?output_format=#{output_format}"
+        response = post_binary(path, body)
+
+        audio = Objects::Audio.new(
+          data: response,
+          format: output_format,
+          voice_id: nil,
+          text: text,
+          model_id: model_id
+        )
+
+        cost_info = Objects::CostInfo.new(text: text, voice_id: 'sound_effect', model_id: model_id)
+        http_client.config.trigger(
+          :on_audio_generated,
+          audio: audio,
+          voice_id: nil,
+          text: text,
+          cost_info: cost_info.to_h
+        )
+
+        audio
+      end
+    end
+  end
+end

data/lib/eleven_rb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ElevenRb
-  VERSION = '0.1.0'
+  VERSION = '0.2.0'
 end

data/lib/eleven_rb.rb

@@ -106,6 +106,7 @@ require_relative 'eleven_rb/resources/text_to_speech'
 require_relative 'eleven_rb/resources/voice_library'
 require_relative 'eleven_rb/resources/models'
 require_relative 'eleven_rb/resources/user'
+require_relative 'eleven_rb/resources/sound_effects'
 
 # High-level components
 require_relative 'eleven_rb/voice_slot_manager'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: eleven_rb
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Web Ventures Ltd
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-21 00:00:00.000000000 Z
+date: 2026-02-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -156,6 +156,7 @@ files:
 - lib/eleven_rb/objects/voice_settings.rb
 - lib/eleven_rb/resources/base.rb
 - lib/eleven_rb/resources/models.rb
+- lib/eleven_rb/resources/sound_effects.rb
 - lib/eleven_rb/resources/text_to_speech.rb
 - lib/eleven_rb/resources/user.rb
 - lib/eleven_rb/resources/voice_library.rb
@@ -186,7 +187,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.23
+rubygems_version: 3.5.3
 signing_key:
 specification_version: 4
 summary: Ruby client for the ElevenLabs Text-to-Speech API