eleven_rb 0.1.0

data/lib/eleven_rb/voice_slot_manager.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  # Manages voice slots to work within ElevenLabs account limits
+  #
+  # This is the key feature for switching voices in and out of your account
+  # when you're limited by your subscription tier.
+  #
+  # @example Basic usage
+  #   manager = client.voice_slots
+  #   manager.ensure_available(public_user_id: "abc", voice_id: "xyz", name: "Spanish Voice")
+  #
+  # @example Check status
+  #   status = client.voice_slots.status
+  #   puts "#{status[:used]}/#{status[:limit]} slots used"
+  class VoiceSlotManager
+    attr_reader :client
+
+    # Initialize the manager
+    #
+    # @param client [Client] the ElevenRb client
+    def initialize(client)
+      @client = client
+      @usage_tracker = {} # voice_id => last_used_at
+    end
+
+    # Ensure a voice from the library is available in your account
+    #
+    # This will:
+    # 1. Check if the voice is already in your account
+    # 2. If not, check if there's room for a new voice
+    # 3. If no room, remove the least recently used voice
+    # 4. Add the voice from the library
+    #
+    # @param public_user_id [String] the public user ID of the voice owner
+    # @param voice_id [String] the voice ID
+    # @param name [String] the name to give the voice
+    # @return [Objects::Voice] the voice (existing or newly added)
+    def ensure_available(public_user_id:, voice_id:, name:)
+      # Check if already in account
+      existing = find_in_account(voice_id)
+      if existing
+        track_usage(existing.voice_id)
+        return existing
+      end
+
+      # Make room if needed
+      make_room_if_needed!
+
+      # Add from library
+      voice = client.voice_library.add(
+        public_user_id: public_user_id,
+        voice_id: voice_id,
+        name: name
+      )
+
+      track_usage(voice.voice_id)
+      voice
+    end
+
+    # Get current slot status
+    #
+    # @return [Hash] status with :used, :limit, :available, :full keys
+    def status
+      subscription = client.user.subscription
+      voice_count = current_count
+
+      {
+        used: voice_count,
+        limit: subscription.voice_limit,
+        available: (subscription.voice_limit || 0) - voice_count,
+        full: subscription.voice_limit ? voice_count >= subscription.voice_limit : false
+      }
+    end
+
+    # Get current voice count
+    #
+    # @return [Integer]
+    def current_count
+      client.voices.list.size
+    end
+
+    # Get available slot count
+    #
+    # @return [Integer]
+    def available_slots
+      status[:available]
+    end
+
+    # Check if slots are full
+    #
+    # @return [Boolean]
+    def full?
+      status[:full]
+    end
+
+    # Track that a voice was used
+    #
+    # @param voice_id [String]
+    # @return [Time] the tracked time
+    def track_usage(voice_id)
+      @usage_tracker[voice_id] = Time.now
+    end
+
+    # Get voices sorted by last usage (least recent first)
+    #
+    # @return [Array<Objects::Voice>]
+    def voices_by_usage
+      voices = client.voices.list
+      voices.sort_by { |v| @usage_tracker[v.voice_id] || Time.at(0) }
+    end
+
+    # Get the least recently used voice
+    #
+    # @return [Objects::Voice, nil]
+    def least_recently_used
+      voices_by_usage.first
+    end
+
+    # Remove the least recently used voice
+    #
+    # @return [Objects::Voice] the removed voice
+    # @raise [Errors::VoiceSlotLimitError] if no voices to remove
+    def remove_lru!
+      lru_voice = least_recently_used
+      raise Errors::VoiceSlotLimitError, 'No voices available to remove' unless lru_voice
+
+      client.voices.destroy(lru_voice.voice_id)
+      @usage_tracker.delete(lru_voice.voice_id)
+      lru_voice
+    end
+
+    # Remove a specific voice
+    #
+    # @param voice_id [String]
+    # @return [Boolean]
+    def remove(voice_id)
+      result = client.voices.destroy(voice_id)
+      @usage_tracker.delete(voice_id) if result
+      result
+    end
+
+    # Clear usage tracking data
+    #
+    # @return [void]
+    def reset_tracking!
+      @usage_tracker.clear
+    end
+
+    # Check if a voice is in the account
+    #
+    # @param voice_id [String]
+    # @return [Boolean]
+    def in_account?(voice_id)
+      client.voices.list.include_voice?(voice_id)
+    end
+
+    # Find a voice in the account by ID
+    #
+    # @param voice_id [String]
+    # @return [Objects::Voice, nil]
+    def find_in_account(voice_id)
+      client.voices.list.find_by_id(voice_id)
+    end
+
+    # Prepare multiple voices at once
+    #
+    # @param voices [Array<Hash>] array of voice params (public_user_id, voice_id, name)
+    # @return [Array<Objects::Voice>]
+    def prepare_voices(voices)
+      voices.map do |params|
+        ensure_available(**params)
+      end
+    end
+
+    private
+
+    def make_room_if_needed!
+      return unless full?
+
+      remove_lru!
+    end
+  end
+end

data/lib/eleven_rb.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require 'httparty'
+require 'json'
+require 'base64'
+
+# ElevenRb - A Ruby client for the ElevenLabs Text-to-Speech 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 Using the module-level client
+#   ElevenRb.client.tts.generate("Hello", voice_id: "abc123")
+#
+# @example Voice slot management
+#   client.voice_slots.ensure_available(
+#     public_user_id: "owner123",
+#     voice_id: "voice456",
+#     name: "My Voice"
+#   )
+module ElevenRb
+  class << self
+    # Get a shared client instance
+    #
+    # @param api_key [String, nil] optional API key
+    # @return [Client]
+    def client(api_key: nil)
+      @client ||= Client.new(api_key: api_key)
+    end
+
+    # Configure the shared client
+    #
+    # @yield [Configuration] the configuration object
+    # @return [Client]
+    def configure
+      config = Configuration.new(api_key: ENV.fetch('ELEVENLABS_API_KEY', nil))
+      yield config if block_given?
+      config.validate!
+      @client = Client.new(**config_to_options(config))
+    end
+
+    # Reset the shared client
+    #
+    # @return [void]
+    def reset!
+      @client = nil
+    end
+
+    private
+
+    def config_to_options(config)
+      {
+        api_key: config.api_key,
+        base_url: config.base_url,
+        timeout: config.timeout,
+        open_timeout: config.open_timeout,
+        max_retries: config.max_retries,
+        retry_delay: config.retry_delay,
+        retry_statuses: config.retry_statuses,
+        logger: config.logger,
+        on_request: config.on_request,
+        on_response: config.on_response,
+        on_error: config.on_error,
+        on_audio_generated: config.on_audio_generated,
+        on_retry: config.on_retry,
+        on_rate_limit: config.on_rate_limit,
+        on_voice_added: config.on_voice_added,
+        on_voice_deleted: config.on_voice_deleted
+      }.compact
+    end
+  end
+end
+
+# Core modules
+require_relative 'eleven_rb/version'
+require_relative 'eleven_rb/errors'
+require_relative 'eleven_rb/callbacks'
+require_relative 'eleven_rb/instrumentation'
+require_relative 'eleven_rb/configuration'
+
+# HTTP layer
+require_relative 'eleven_rb/http/client'
+
+# Response objects
+require_relative 'eleven_rb/objects/base'
+require_relative 'eleven_rb/objects/voice_settings'
+require_relative 'eleven_rb/objects/voice'
+require_relative 'eleven_rb/objects/audio'
+require_relative 'eleven_rb/objects/model'
+require_relative 'eleven_rb/objects/subscription'
+require_relative 'eleven_rb/objects/user_info'
+require_relative 'eleven_rb/objects/library_voice'
+require_relative 'eleven_rb/objects/cost_info'
+
+# Collections
+require_relative 'eleven_rb/collections/base'
+require_relative 'eleven_rb/collections/voice_collection'
+require_relative 'eleven_rb/collections/library_voice_collection'
+
+# Resources
+require_relative 'eleven_rb/resources/base'
+require_relative 'eleven_rb/resources/voices'
+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'
+
+# High-level components
+require_relative 'eleven_rb/voice_slot_manager'
+require_relative 'eleven_rb/tts_adapter'
+require_relative 'eleven_rb/client'

metadata

@@ -0,0 +1,193 @@
+--- !ruby/object:Gem::Specification
+name: eleven_rb
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Web Ventures Ltd
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-01-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: base64
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.1'
+- !ruby/object:Gem::Dependency
+  name: httparty
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.21'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.12'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.57'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.57'
+- !ruby/object:Gem::Dependency
+  name: vcr
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '6.2'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.19'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+description: |
+  A well-structured Ruby gem for ElevenLabs TTS with voice library management,
+  streaming support, voice slot optimization, and comprehensive callbacks for
+  logging, error tracking, and cost monitoring.
+email:
+- gems@dev.webven.nz
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/eleven_rb.rb
+- lib/eleven_rb/callbacks.rb
+- lib/eleven_rb/client.rb
+- lib/eleven_rb/collections/base.rb
+- lib/eleven_rb/collections/library_voice_collection.rb
+- lib/eleven_rb/collections/voice_collection.rb
+- lib/eleven_rb/configuration.rb
+- lib/eleven_rb/errors.rb
+- lib/eleven_rb/http/client.rb
+- lib/eleven_rb/instrumentation.rb
+- lib/eleven_rb/objects/audio.rb
+- lib/eleven_rb/objects/base.rb
+- lib/eleven_rb/objects/cost_info.rb
+- lib/eleven_rb/objects/library_voice.rb
+- lib/eleven_rb/objects/model.rb
+- lib/eleven_rb/objects/subscription.rb
+- lib/eleven_rb/objects/user_info.rb
+- lib/eleven_rb/objects/voice.rb
+- lib/eleven_rb/objects/voice_settings.rb
+- lib/eleven_rb/resources/base.rb
+- lib/eleven_rb/resources/models.rb
+- lib/eleven_rb/resources/text_to_speech.rb
+- lib/eleven_rb/resources/user.rb
+- lib/eleven_rb/resources/voice_library.rb
+- lib/eleven_rb/resources/voices.rb
+- lib/eleven_rb/tts_adapter.rb
+- lib/eleven_rb/version.rb
+- lib/eleven_rb/voice_slot_manager.rb
+homepage: https://github.com/webventures/eleven_rb
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/webventures/eleven_rb
+  source_code_uri: https://github.com/webventures/eleven_rb
+  changelog_uri: https://github.com/webventures/eleven_rb/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.23
+signing_key:
+specification_version: 4
+summary: Ruby client for the ElevenLabs Text-to-Speech API
+test_files: []