eleven_rb 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2402cc8af1a30f52cf74017c0f24adc423ae932616fe74296e1fe09a635c628b
+  data.tar.gz: f149ab57fc621a178b5e2b4443a6cc02fb830769e2053152b86b246dbc8ca2cb
+SHA512:
+  metadata.gz: 42df0d9c9095233697e41aa08e98297090fc1def3f5e16c4c3f248ddd60650d5be8fb85456ab41b352c92bc3dbd8208041010764a61b7143bdcfda706b890b7f
+  data.tar.gz: 50ba905bccdddb14a8148345f69461a98cdc58659e1a6a3c75098de02744962a76d354fcd48326fc29722c3d03a81c9cd426be47706f5e5eb0d91faf38a4161b

data/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-01-21
+
+### Added
+
+- Initial release
+- Text-to-Speech generation with `client.tts.generate`
+- Streaming TTS with `client.tts.stream`
+- Voice management (list, get, create, update, delete)
+- Voice Library access (search, add shared voices)
+- Voice Slot Manager for automatic slot management
+- Models resource for listing available TTS models
+- User/subscription information
+- Comprehensive callback system:
+  - `on_request` - before each API call
+  - `on_response` - after successful response
+  - `on_error` - when errors occur
+  - `on_audio_generated` - after TTS generation (includes cost info)
+  - `on_retry` - before retry attempts
+  - `on_rate_limit` - when rate limited
+  - `on_voice_added` / `on_voice_deleted` - voice changes
+- Automatic retry with exponential backoff
+- Structured response objects
+- TTSAdapter for future wrapper gem compatibility
+- ActiveSupport::Notifications integration (optional)

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Web Ventures Ltd - www.webven.nz
+
+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,311 @@
+# ElevenRb
+
+[![Gem Version](https://badge.fury.io/rb/eleven_rb.svg)](https://badge.fury.io/rb/eleven_rb)
+[![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.
+
+## Features
+
+- Text-to-Speech generation and streaming
+- 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
+- Comprehensive callback system for logging, monitoring, and cost tracking
+- Automatic retry with configurable backoff
+- Structured response objects
+- Future-ready adapter for multi-provider wrapper gems
+
+## Requirements
+
+- Ruby >= 3.0
+- An [ElevenLabs API key](https://elevenlabs.io/app/settings/api-keys)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'eleven_rb'
+```
+
+Or install directly:
+
+```bash
+gem install eleven_rb
+```
+
+## Quick Start
+
+```ruby
+require 'eleven_rb'
+
+# Initialize with API key
+client = ElevenRb::Client.new(api_key: "your-api-key")
+
+# Or use environment variable ELEVENLABS_API_KEY
+client = ElevenRb::Client.new
+
+# Generate speech
+audio = client.tts.generate("Hello world!", voice_id: "JBFqnCBsd6RMkjVDRZzb")
+audio.save_to_file("output.mp3")
+
+# List voices
+client.voices.list.each do |voice|
+  puts "#{voice.name} (#{voice.voice_id})"
+end
+```
+
+## Usage
+
+### Text-to-Speech
+
+```ruby
+# Basic generation
+audio = client.tts.generate("Hello world", voice_id: "voice_id")
+audio.save_to_file("output.mp3")
+
+# With options
+audio = client.tts.generate(
+  "Hello world",
+  voice_id: "voice_id",
+  model_id: "eleven_multilingual_v2",
+  voice_settings: {
+    stability: 0.5,
+    similarity_boost: 0.75
+  },
+  output_format: "mp3_44100_192"
+)
+
+# Streaming
+File.open("output.mp3", "wb") do |file|
+  client.tts.stream("Long text here...", voice_id: "voice_id") do |chunk|
+    file.write(chunk)
+  end
+end
+```
+
+### Voice Management
+
+```ruby
+# List all voices
+voices = client.voices.list
+voices.each { |v| puts v.display_name }
+
+# Get a specific voice
+voice = client.voices.find("voice_id")
+puts voice.name
+
+# Delete a voice
+client.voices.destroy("voice_id")
+
+# Filter voices
+spanish_voices = voices.by_language("spanish")
+female_voices = voices.by_gender("female")
+```
+
+### Voice Library
+
+Search and add voices from ElevenLabs' 10,000+ community voice library:
+
+```ruby
+# Search for Spanish female voices
+results = client.voice_library.search(
+  language: "Spanish",
+  gender: "female",
+  page_size: 20
+)
+
+results.each do |voice|
+  puts "#{voice.name} - #{voice.accent}"
+end
+
+# Add a voice from the library to your account
+voice = client.voice_library.add(
+  public_user_id: voice.public_owner_id,
+  voice_id: voice.voice_id,
+  name: "My Spanish Voice"
+)
+```
+
+### Voice Slot Management
+
+Automatically manage voice slots when you're limited by your subscription:
+
+```ruby
+# Check current slot status
+status = client.voice_slots.status
+puts "#{status[:used]}/#{status[:limit]} slots used"
+
+# Ensure a voice is available (adds from library if needed, removes LRU if full)
+voice = client.voice_slots.ensure_available(
+  public_user_id: "owner_id",
+  voice_id: "voice_id",
+  name: "Spanish Voice"
+)
+
+# Now use the voice
+audio = client.tts.generate("Hola mundo", voice_id: voice.voice_id)
+
+# Prepare multiple voices for a conversation
+voices = client.voice_slots.prepare_voices([
+  { public_user_id: "abc", voice_id: "v1", name: "Maria" },
+  { public_user_id: "def", voice_id: "v2", name: "Carlos" }
+])
+```
+
+### Callbacks
+
+Set up callbacks for logging, monitoring, and cost tracking:
+
+```ruby
+client = ElevenRb::Client.new(
+  api_key: ENV['ELEVENLABS_API_KEY'],
+
+  # Logging
+  on_request: ->(method:, path:, body:) {
+    Rails.logger.info("[ElevenLabs] #{method.upcase} #{path}")
+  },
+
+  on_response: ->(method:, path:, response:, duration:) {
+    Rails.logger.info("[ElevenLabs] #{method.upcase} #{path} (#{duration}ms)")
+  },
+
+  # Error tracking
+  on_error: ->(error:, method:, path:, context:) {
+    Sentry.capture_exception(error, extra: { path: path })
+  },
+
+  # Cost tracking
+  on_audio_generated: ->(audio:, voice_id:, text:, cost_info:) {
+    UsageRecord.create!(
+      characters: cost_info[:character_count],
+      estimated_cost: cost_info[:estimated_cost]
+    )
+  },
+
+  # Rate limit handling
+  on_rate_limit: ->(retry_after:, error:) {
+    SlackNotifier.notify("Rate limited, retry in #{retry_after}s")
+  }
+)
+```
+
+### Models
+
+```ruby
+# List available models
+models = client.models.list
+models.each { |m| puts "#{m.name} (#{m.model_id})" }
+
+# Get multilingual models
+client.models.multilingual
+
+# Get turbo/fast models
+client.models.turbo
+```
+
+### User Information
+
+```ruby
+# Get subscription info
+sub = client.user.subscription
+puts "Characters: #{sub.character_count}/#{sub.character_limit}"
+puts "Resets at: #{sub.next_reset_at}"
+
+# Get user info
+info = client.user.info
+puts "Email: #{info.email}"
+```
+
+## Configuration
+
+```ruby
+client = ElevenRb::Client.new(
+  api_key: "your-api-key",
+  timeout: 120,              # Request timeout in seconds
+  open_timeout: 10,          # Connection timeout
+  max_retries: 3,            # Max retry attempts
+  retry_delay: 1.0,          # Base delay between retries
+  logger: Rails.logger       # Optional logger
+)
+```
+
+## Error Handling
+
+```ruby
+begin
+  audio = client.tts.generate("Hello", voice_id: "invalid")
+rescue ElevenRb::Errors::NotFoundError => e
+  puts "Voice not found: #{e.message}"
+rescue ElevenRb::Errors::RateLimitError => e
+  puts "Rate limited, retry after #{e.retry_after} seconds"
+rescue ElevenRb::Errors::AuthenticationError => e
+  puts "Invalid API key"
+rescue ElevenRb::Errors::ValidationError => e
+  puts "Validation error: #{e.message}"
+rescue ElevenRb::Errors::APIError => e
+  puts "API error: #{e.message} (status: #{e.http_status})"
+end
+```
+
+## Rails Integration
+
+```ruby
+# config/initializers/eleven_rb.rb
+ElevenRb.configure do |config|
+  config.api_key = Rails.application.credentials.dig(:elevenlabs, :api_key)
+
+  config.on_error = ->(error:, **) {
+    Sentry.capture_exception(error, tags: { service: "elevenlabs" })
+  }
+
+  config.on_audio_generated = ->(cost_info:, **) {
+    TtsUsage.create!(cost_info)
+  }
+end
+
+# Then use anywhere
+audio = ElevenRb.client.tts.generate("Hello", voice_id: "abc123")
+```
+
+## Voice Slot Limits by Plan
+
+| Plan | Voice Slots |
+|------|-------------|
+| Free | 3 |
+| Starter | 10 |
+| Creator | 30 |
+| Pro | 160 |
+| Scale | 660 |
+| Business | 660 |
+
+## References
+
+- [ElevenLabs API Documentation](https://elevenlabs.io/docs/api-reference)
+- [ElevenLabs Developer Portal](https://try.elevenlabs.io/qyk2j8gumrjz)
+- [Voice Library](https://elevenlabs.io/voice-library)
+
+## Changelog
+
+For a detailed list of changes for each version of this project, please see the [CHANGELOG](CHANGELOG.md).
+
+## Development
+
+After checking out the repo, run `bundle install` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bundle exec rake console` for an interactive prompt that will allow you to experiment.
+
+```bash
+bundle install          # Install dependencies
+bundle exec rspec       # Run tests
+bundle exec rubocop     # Run linter
+bundle exec rake build  # Build gem
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/webventures/eleven_rb.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](LICENSE).

data/lib/eleven_rb/callbacks.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  # Provides a callback/hook system for monitoring and extending gem behavior
+  #
+  # @example Setting up callbacks
+  #   client = ElevenRb::Client.new(
+  #     api_key: "...",
+  #     on_error: ->(error:, method:, path:, context:) {
+  #       Sentry.capture_exception(error)
+  #     }
+  #   )
+  module Callbacks
+    CALLBACK_NAMES = %i[
+      on_request
+      on_response
+      on_error
+      on_audio_generated
+      on_retry
+      on_rate_limit
+      on_voice_added
+      on_voice_deleted
+    ].freeze
+
+    def self.included(base)
+      base.attr_accessor(*CALLBACK_NAMES)
+    end
+
+    # Trigger a callback if it's configured
+    #
+    # @param callback_name [Symbol] the name of the callback
+    # @param kwargs [Hash] keyword arguments to pass to the callback
+    # @return [Object, nil] the return value of the callback, or nil
+    def trigger(callback_name, **kwargs)
+      callback = send(callback_name)
+      return unless callback.respond_to?(:call)
+
+      begin
+        callback.call(**kwargs)
+      rescue StandardError => e
+        # Don't let callback errors break the main flow
+        warn "[ElevenRb] Callback error in #{callback_name}: #{e.message}"
+        nil
+      end
+    end
+  end
+end

data/lib/eleven_rb/client.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  # Main client for interacting with the ElevenLabs API
+  #
+  # @example Basic usage
+  #   client = ElevenRb::Client.new(api_key: "your-api-key")
+  #   audio = client.tts.generate("Hello world", voice_id: "abc123")
+  #   audio.save_to_file("output.mp3")
+  #
+  # @example With callbacks
+  #   client = ElevenRb::Client.new(
+  #     api_key: "your-api-key",
+  #     on_error: ->(error:, **) { Sentry.capture_exception(error) },
+  #     on_audio_generated: ->(cost_info:, **) { track_cost(cost_info) }
+  #   )
+  #
+  # @example Voice slot management
+  #   client.voice_slots.ensure_available(
+  #     public_user_id: "abc",
+  #     voice_id: "xyz",
+  #     name: "Spanish Voice"
+  #   )
+  class Client
+    attr_reader :config, :http_client
+
+    # Initialize a new client
+    #
+    # @param api_key [String, nil] API key (defaults to ELEVENLABS_API_KEY env var)
+    # @param options [Hash] additional configuration options
+    # @see Configuration#initialize for all available options
+    def initialize(api_key: nil, **options)
+      @config = Configuration.new(
+        api_key: api_key || ENV.fetch('ELEVENLABS_API_KEY', nil),
+        **options
+      )
+      @config.validate!
+      @http_client = HTTP::Client.new(@config)
+    end
+
+    # Voice management resource
+    #
+    # @return [Resources::Voices]
+    def voices
+      @voices ||= Resources::Voices.new(http_client)
+    end
+
+    # Text-to-speech resource
+    #
+    # @return [Resources::TextToSpeech]
+    def tts
+      @tts ||= Resources::TextToSpeech.new(http_client)
+    end
+
+    # Voice library resource
+    #
+    # @return [Resources::VoiceLibrary]
+    def voice_library
+      @voice_library ||= Resources::VoiceLibrary.new(http_client)
+    end
+
+    # Models resource
+    #
+    # @return [Resources::Models]
+    def models
+      @models ||= Resources::Models.new(http_client)
+    end
+
+    # User/account resource
+    #
+    # @return [Resources::User]
+    def user
+      @user ||= Resources::User.new(http_client)
+    end
+
+    # Voice slot manager
+    #
+    # @return [VoiceSlotManager]
+    def voice_slots
+      @voice_slots ||= VoiceSlotManager.new(self)
+    end
+
+    # Convenience method: generate speech
+    #
+    # @param text [String] the text to convert
+    # @param voice_id [String] the voice ID
+    # @param options [Hash] additional options
+    # @return [Objects::Audio]
+    def generate_speech(text, voice_id:, **options)
+      tts.generate(text, voice_id: voice_id, **options)
+    end
+
+    # Convenience method: stream speech
+    #
+    # @param text [String] the text to convert
+    # @param voice_id [String] the voice ID
+    # @param options [Hash] additional options
+    # @yield [String] each chunk of audio
+    def stream_speech(text, voice_id:, **options, &block)
+      tts.stream(text, voice_id: voice_id, **options, &block)
+    end
+
+    # Get the TTS adapter for wrapper compatibility
+    #
+    # @return [TTSAdapter]
+    def adapter
+      @adapter ||= TTSAdapter.new(self)
+    end
+  end
+end

data/lib/eleven_rb/collections/base.rb

@@ -0,0 +1,92 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Collections
+    # Base class for collections of objects
+    #
+    # Provides Enumerable support and pagination helpers
+    class Base
+      include Enumerable
+
+      attr_reader :items, :raw_response
+
+      # Create collection from API response
+      #
+      # @param response [Hash] the API response
+      # @return [Base]
+      def self.from_response(response)
+        new(response)
+      end
+
+      # Initialize collection
+      #
+      # @param response [Hash] the API response
+      def initialize(response)
+        @raw_response = response
+        @items = parse_items(response)
+      end
+
+      # Iterate over items
+      #
+      # @yield [Object] each item
+      def each(&block)
+        items.each(&block)
+      end
+
+      # Get item by index
+      #
+      # @param index [Integer]
+      # @return [Object, nil]
+      def [](index)
+        items[index]
+      end
+
+      # Get collection size
+      #
+      # @return [Integer]
+      def size
+        items.size
+      end
+      alias length size
+      alias count size
+
+      # Check if collection is empty
+      #
+      # @return [Boolean]
+      def empty?
+        items.empty?
+      end
+
+      # Get first item
+      #
+      # @return [Object, nil]
+      def first
+        items.first
+      end
+
+      # Get last item
+      #
+      # @return [Object, nil]
+      def last
+        items.last
+      end
+
+      # Convert to array
+      #
+      # @return [Array]
+      def to_a
+        items.dup
+      end
+
+      private
+
+      # Override in subclasses to parse items
+      #
+      # @param response [Hash] the API response
+      # @return [Array]
+      def parse_items(response)
+        raise NotImplementedError, 'Subclasses must implement #parse_items'
+      end
+    end
+  end
+end

data/lib/eleven_rb/collections/library_voice_collection.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Collections
+    # Collection of LibraryVoice objects from the shared voice library
+    class LibraryVoiceCollection < Base
+      # Check if there are more results
+      #
+      # @return [Boolean]
+      def has_more?
+        raw_response['has_more'] == true
+      end
+
+      # Get the cursor for next page
+      #
+      # @return [String, nil]
+      def next_cursor
+        raw_response['last_sort_id']
+      end
+
+      # Find voice by ID
+      #
+      # @param voice_id [String]
+      # @return [Objects::LibraryVoice, nil]
+      def find_by_id(voice_id)
+        items.find { |v| v.voice_id == voice_id }
+      end
+
+      # Find voice by name (case-insensitive)
+      #
+      # @param name [String]
+      # @return [Objects::LibraryVoice, nil]
+      def find_by_name(name)
+        items.find { |v| v.name&.downcase == name.downcase }
+      end
+
+      # Filter voices by gender
+      #
+      # @param gender [String]
+      # @return [Array<Objects::LibraryVoice>]
+      def by_gender(gender)
+        items.select { |v| v.gender&.downcase == gender.downcase }
+      end
+
+      # Filter voices by language
+      #
+      # @param language [String]
+      # @return [Array<Objects::LibraryVoice>]
+      def by_language(language)
+        items.select { |v| v.language&.downcase == language.downcase }
+      end
+
+      # Filter voices by accent
+      #
+      # @param accent [String]
+      # @return [Array<Objects::LibraryVoice>]
+      def by_accent(accent)
+        items.select { |v| v.accent&.downcase&.include?(accent.downcase) }
+      end
+
+      # Get popular voices (high usage)
+      #
+      # @param threshold [Integer]
+      # @return [Array<Objects::LibraryVoice>]
+      def popular(threshold: 10_000)
+        items.select { |v| v.popular?(threshold: threshold) }
+      end
+
+      # Get voices available for free users
+      #
+      # @return [Array<Objects::LibraryVoice>]
+      def free_tier
+        items.select(&:available_for_free?)
+      end
+
+      # Get verified voices only
+      #
+      # @return [Array<Objects::LibraryVoice>]
+      def verified
+        items.select(&:verified)
+      end
+
+      private
+
+      def parse_items(response)
+        voices = response['voices'] || []
+        voices.map { |v| Objects::LibraryVoice.from_response(v) }
+      end
+    end
+  end
+end