eleven_rb 0.1.0

data/lib/eleven_rb/resources/text_to_speech.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Resources
+    # Text-to-speech resource
+    #
+    # @example Generate audio
+    #   audio = client.tts.generate("Hello world", voice_id: "voice_id")
+    #   audio.save_to_file("output.mp3")
+    #
+    # @example Stream audio
+    #   client.tts.stream("Hello world", voice_id: "voice_id") do |chunk|
+    #     io.write(chunk)
+    #   end
+    class TextToSpeech < Base
+      DEFAULT_MODEL = 'eleven_multilingual_v2'
+      MAX_TEXT_LENGTH = 5000
+
+      OUTPUT_FORMATS = %w[
+        mp3_44100_128
+        mp3_44100_192
+        pcm_16000
+        pcm_22050
+        pcm_24000
+        pcm_44100
+        ulaw_8000
+      ].freeze
+
+      # Generate audio from text
+      #
+      # @param text [String] the text to convert
+      # @param voice_id [String] the voice ID to use
+      # @param model_id [String] the model to use (default: eleven_multilingual_v2)
+      # @param voice_settings [Hash] voice settings overrides
+      # @param output_format [String] audio output format
+      # @return [Objects::Audio]
+      def generate(text, voice_id:, model_id: DEFAULT_MODEL, voice_settings: {}, output_format: 'mp3_44100_128')
+        validate_text!(text)
+        validate_presence!(voice_id, 'voice_id')
+
+        settings = Objects::VoiceSettings::DEFAULTS.merge(voice_settings)
+
+        body = {
+          text: text,
+          model_id: model_id,
+          voice_settings: settings
+        }
+
+        path = "/text-to-speech/#{voice_id}?output_format=#{output_format}"
+        response = post_binary(path, body)
+
+        audio = Objects::Audio.new(
+          data: response,
+          format: output_format,
+          voice_id: voice_id,
+          text: text,
+          model_id: model_id
+        )
+
+        # Trigger cost tracking callback
+        cost_info = Objects::CostInfo.new(text: text, voice_id: voice_id, model_id: model_id)
+        http_client.config.trigger(
+          :on_audio_generated,
+          audio: audio,
+          voice_id: voice_id,
+          text: text,
+          cost_info: cost_info.to_h
+        )
+
+        audio
+      end
+
+      # Stream audio from text
+      #
+      # @param text [String] the text to convert
+      # @param voice_id [String] the voice ID to use
+      # @param model_id [String] the model to use
+      # @param voice_settings [Hash] voice settings overrides
+      # @param output_format [String] audio output format
+      # @yield [String] each chunk of audio data
+      # @return [void]
+      def stream(text, voice_id:, model_id: DEFAULT_MODEL, voice_settings: {}, output_format: 'mp3_44100_128', &block)
+        validate_text!(text)
+        validate_presence!(voice_id, 'voice_id')
+        raise ArgumentError, 'Block required for streaming' unless block_given?
+
+        settings = Objects::VoiceSettings::DEFAULTS.merge(voice_settings)
+
+        body = {
+          text: text,
+          model_id: model_id,
+          voice_settings: settings
+        }
+
+        path = "/text-to-speech/#{voice_id}/stream?output_format=#{output_format}"
+        post_stream(path, body, &block)
+
+        # Trigger cost tracking callback after streaming completes
+        cost_info = Objects::CostInfo.new(text: text, voice_id: voice_id, model_id: model_id)
+        http_client.config.trigger(
+          :on_audio_generated,
+          audio: nil, # No audio object for streaming
+          voice_id: voice_id,
+          text: text,
+          cost_info: cost_info.to_h
+        )
+      end
+
+      # Generate audio with timestamps
+      #
+      # @param text [String] the text to convert
+      # @param voice_id [String] the voice ID to use
+      # @param model_id [String] the model to use
+      # @param voice_settings [Hash] voice settings overrides
+      # @param output_format [String] audio output format
+      # @return [Hash] contains :audio and :alignment data
+      def generate_with_timestamps(text, voice_id:, model_id: DEFAULT_MODEL, voice_settings: {},
+                                   output_format: 'mp3_44100_128')
+        validate_text!(text)
+        validate_presence!(voice_id, 'voice_id')
+
+        settings = Objects::VoiceSettings::DEFAULTS.merge(voice_settings)
+
+        body = {
+          text: text,
+          model_id: model_id,
+          voice_settings: settings
+        }
+
+        path = "/text-to-speech/#{voice_id}/with-timestamps?output_format=#{output_format}"
+        response = post(path, body)
+
+        # Decode base64 audio
+        audio_data = Base64.decode64(response['audio_base64']) if response['audio_base64']
+
+        audio = if audio_data
+                  Objects::Audio.new(
+                    data: audio_data,
+                    format: output_format,
+                    voice_id: voice_id,
+                    text: text,
+                    model_id: model_id
+                  )
+                end
+
+        {
+          audio: audio,
+          alignment: response['alignment']
+        }
+      end
+
+      private
+
+      def validate_text!(text)
+        validate_presence!(text, 'text')
+
+        return unless text.length > MAX_TEXT_LENGTH
+
+        raise Errors::ValidationError,
+              "text exceeds maximum length of #{MAX_TEXT_LENGTH} characters (got #{text.length})"
+      end
+    end
+  end
+end

data/lib/eleven_rb/resources/user.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Resources
+    # User/account resource
+    #
+    # @example Get subscription info
+    #   sub = client.user.subscription
+    #   puts sub.characters_remaining
+    #
+    # @example Get user info
+    #   info = client.user.info
+    class User < Base
+      # Get subscription information
+      #
+      # @return [Objects::Subscription]
+      def subscription
+        response = get('/user/subscription')
+        Objects::Subscription.from_response(response)
+      end
+
+      # Get user account information
+      #
+      # @return [Objects::UserInfo]
+      def info
+        response = get('/user')
+        Objects::UserInfo.from_response(response)
+      end
+
+      # Get subscription with current voice count
+      # This makes an additional API call to count voices
+      #
+      # @return [Objects::Subscription]
+      def subscription_with_voice_count(voices_count)
+        sub = subscription
+        sub.voice_slots_used = voices_count
+        sub
+      end
+
+      # Check if user can add more voices
+      #
+      # @param current_voice_count [Integer]
+      # @return [Boolean]
+      def can_add_voice?(current_voice_count)
+        sub = subscription
+        return true unless sub.voice_limit
+
+        current_voice_count < sub.voice_limit
+      end
+
+      # Get character usage summary
+      #
+      # @return [Hash]
+      def character_usage
+        sub = subscription
+        {
+          used: sub.character_count,
+          limit: sub.character_limit,
+          remaining: sub.characters_remaining,
+          percentage: sub.characters_used_percentage,
+          resets_at: sub.next_reset_at
+        }
+      end
+    end
+  end
+end

data/lib/eleven_rb/resources/voice_library.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Resources
+    # Voice library resource for accessing shared voices
+    #
+    # @example Search for Spanish voices
+    #   voices = client.voice_library.search(language: "Spanish", gender: "female")
+    #
+    # @example Add a voice from the library
+    #   voice = client.voice_library.add(
+    #     public_user_id: "abc123",
+    #     voice_id: "xyz789",
+    #     name: "My Spanish Voice"
+    #   )
+    class VoiceLibrary < Base
+      CATEGORIES = %w[professional famous high_quality].freeze
+      MAX_PAGE_SIZE = 100
+
+      # Search the shared voice library
+      #
+      # @param page_size [Integer] results per page (max 100)
+      # @param category [String] voice category filter
+      # @param gender [String] gender filter
+      # @param age [String] age filter
+      # @param accent [String] accent filter
+      # @param language [String] language filter
+      # @param locale [String] locale filter
+      # @param search [String] search term
+      # @param use_cases [Array<String>] use case filters
+      # @param featured [Boolean] only featured voices
+      # @param reader_app_enabled [Boolean] only reader app enabled
+      # @param owner_id [String] filter by owner
+      # @param sort [String] sort order
+      # @param page [String] pagination cursor
+      # @return [Collections::LibraryVoiceCollection]
+      def search(
+        page_size: 30,
+        category: nil,
+        gender: nil,
+        age: nil,
+        accent: nil,
+        language: nil,
+        locale: nil,
+        search: nil,
+        use_cases: nil,
+        featured: nil,
+        reader_app_enabled: nil,
+        owner_id: nil,
+        sort: nil,
+        page: nil
+      )
+        params = {
+          page_size: [page_size.to_i, MAX_PAGE_SIZE].min,
+          category: category,
+          gender: gender,
+          age: age,
+          accent: accent,
+          language: language,
+          locale: locale,
+          search: search,
+          use_cases: use_cases&.join(','),
+          featured: featured,
+          reader_app_enabled: reader_app_enabled,
+          owner_id: owner_id,
+          sort: sort,
+          cursor: page
+        }.compact
+
+        response = get('/shared-voices', params)
+        Collections::LibraryVoiceCollection.from_response(response)
+      end
+
+      # Add a shared voice to your account
+      #
+      # @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 in your account
+      # @return [Objects::Voice]
+      def add(public_user_id:, voice_id:, name:)
+        validate_presence!(public_user_id, 'public_user_id')
+        validate_presence!(voice_id, 'voice_id')
+        validate_presence!(name, 'name')
+
+        response = post("/voices/add/#{public_user_id}/#{voice_id}", { new_name: name })
+
+        # Trigger callback
+        http_client.config.trigger(:on_voice_added, voice_id: response['voice_id'], name: name)
+
+        # Return a Voice object with the info we have
+        Objects::Voice.from_response({
+                                       'voice_id' => response['voice_id'],
+                                       'name' => name
+                                     })
+      end
+
+      # Search for voices by keyword
+      #
+      # @param query [String] search query
+      # @param options [Hash] additional search options
+      # @return [Collections::LibraryVoiceCollection]
+      def find(query, **options)
+        search(search: query, **options)
+      end
+
+      # Get all Spanish voices
+      #
+      # @param options [Hash] additional search options
+      # @return [Collections::LibraryVoiceCollection]
+      def spanish(**options)
+        search(language: 'Spanish', **options)
+      end
+
+      # Get all professional voices
+      #
+      # @param options [Hash] additional search options
+      # @return [Collections::LibraryVoiceCollection]
+      def professional(**options)
+        search(category: 'professional', **options)
+      end
+
+      # Iterate through all pages of results
+      #
+      # @param options [Hash] search options
+      # @yield [Collections::LibraryVoiceCollection] each page of results
+      # @return [Enumerator] if no block given
+      def each_page(**options)
+        return enum_for(:each_page, **options) unless block_given?
+
+        cursor = nil
+        loop do
+          collection = search(**options, page: cursor)
+          yield collection
+
+          break unless collection.has_more?
+
+          cursor = collection.next_cursor
+        end
+      end
+
+      # Get all voices matching criteria (auto-paginates)
+      #
+      # @param max_pages [Integer] maximum pages to fetch (safety limit)
+      # @param options [Hash] search options
+      # @return [Array<Objects::LibraryVoice>]
+      def all(max_pages: 10, **options)
+        voices = []
+        pages = 0
+
+        each_page(**options) do |collection|
+          voices.concat(collection.to_a)
+          pages += 1
+          break if pages >= max_pages
+        end
+
+        voices
+      end
+    end
+  end
+end

data/lib/eleven_rb/resources/voices.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Resources
+    # Voice management resource
+    #
+    # @example List all voices
+    #   client.voices.list
+    #
+    # @example Get a specific voice
+    #   client.voices.get("voice_id")
+    #
+    # @example Delete a voice
+    #   client.voices.delete("voice_id")
+    class Voices < Base
+      # List all voices in your account
+      #
+      # @return [Collections::VoiceCollection]
+      def list
+        response = get('/voices')
+        Collections::VoiceCollection.from_response(response)
+      end
+
+      # Get details for a specific voice
+      #
+      # @param voice_id [String] the voice ID
+      # @return [Objects::Voice]
+      def find(voice_id)
+        validate_presence!(voice_id, 'voice_id')
+        response = get("/voices/#{voice_id}")
+        Objects::Voice.from_response(response)
+      end
+
+      # Delete a voice from your account
+      #
+      # @param voice_id [String] the voice ID
+      # @return [Boolean] true if successful
+      def destroy(voice_id)
+        validate_presence!(voice_id, 'voice_id')
+        response = delete("/voices/#{voice_id}")
+
+        # Trigger callback
+        http_client.config.trigger(:on_voice_deleted, voice_id: voice_id)
+
+        response['status'] == 'ok'
+      end
+
+      # Create a new voice from audio samples (Instant Voice Cloning)
+      #
+      # @param name [String] voice name
+      # @param samples [Array<File>] audio sample files
+      # @param description [String, nil] voice description
+      # @param labels [Hash] voice labels (e.g., { "accent" => "British" })
+      # @return [Objects::Voice]
+      def create(name:, samples:, description: nil, labels: {})
+        validate_presence!(name, 'name')
+        validate_samples!(samples)
+
+        params = {
+          name: name,
+          files: samples
+        }
+        params[:description] = description if description
+        params[:labels] = labels.to_json unless labels.empty?
+
+        response = post_multipart('/voices/add', params)
+
+        # Trigger callback
+        http_client.config.trigger(:on_voice_added, voice_id: response['voice_id'], name: name)
+
+        Objects::Voice.from_response(response)
+      end
+
+      # Update an existing voice
+      #
+      # @param voice_id [String] the voice ID
+      # @param name [String, nil] new name
+      # @param description [String, nil] new description
+      # @param samples [Array<File>, nil] additional audio samples
+      # @param labels [Hash, nil] new labels
+      # @return [Objects::Voice]
+      def update(voice_id, name: nil, description: nil, samples: nil, labels: nil)
+        validate_presence!(voice_id, 'voice_id')
+
+        params = {}
+        params[:name] = name if name
+        params[:description] = description if description
+        params[:labels] = labels.to_json if labels
+        params[:files] = samples if samples
+
+        response = if samples
+                     post_multipart("/voices/#{voice_id}/edit", params)
+                   else
+                     post("/voices/#{voice_id}/edit", params)
+                   end
+
+        Objects::Voice.from_response(response)
+      end
+
+      # Get default voice settings
+      #
+      # @return [Objects::VoiceSettings]
+      def default_settings
+        response = get('/voices/settings/default')
+        Objects::VoiceSettings.from_response(response)
+      end
+
+      # Get settings for a specific voice
+      #
+      # @param voice_id [String] the voice ID
+      # @return [Objects::VoiceSettings]
+      def settings(voice_id)
+        validate_presence!(voice_id, 'voice_id')
+        response = get("/voices/#{voice_id}/settings")
+        Objects::VoiceSettings.from_response(response)
+      end
+
+      # Update settings for a voice
+      #
+      # @param voice_id [String] the voice ID
+      # @param settings [Hash] the settings to update
+      # @return [Boolean]
+      def update_settings(voice_id, settings)
+        validate_presence!(voice_id, 'voice_id')
+        response = post("/voices/#{voice_id}/settings/edit", settings)
+        response['status'] == 'ok'
+      end
+
+      private
+
+      def validate_samples!(samples)
+        return if samples.is_a?(Array) && samples.any?
+
+        raise Errors::ValidationError, 'samples must be an array of files'
+      end
+    end
+  end
+end

data/lib/eleven_rb/tts_adapter.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  # Adapter for potential future voiceagent wrapper gem
+  #
+  # Implements a standard interface that other TTS provider gems could follow,
+  # allowing a wrapper gem to provide a unified API across providers.
+  #
+  # @example Using the adapter directly
+  #   adapter = ElevenRb::TTSAdapter.new
+  #   audio = adapter.generate("Hello", voice_id: "abc123")
+  #
+  # @example With a hypothetical wrapper gem
+  #   agent = VoiceAgent.new
+  #   agent.register(:elevenlabs, ElevenRb::TTSAdapter.new)
+  #   agent.generate("Hello", provider: :elevenlabs, voice_id: "abc123")
+  class TTSAdapter
+    attr_reader :client
+
+    # Initialize the adapter
+    #
+    # @param client [Client, nil] optional client (creates one if not provided)
+    def initialize(client = nil)
+      @client = client || Client.new
+    end
+
+    # Provider identifier
+    #
+    # @return [Symbol]
+    def provider_name
+      :elevenlabs
+    end
+
+    # List available voices
+    #
+    # @return [Array<Hash>] normalized voice data
+    def list_voices
+      @client.voices.list.map do |voice|
+        {
+          provider: :elevenlabs,
+          voice_id: voice.voice_id,
+          name: voice.name,
+          gender: voice.gender,
+          language: voice.language,
+          accent: voice.accent,
+          category: voice.category,
+          preview_url: voice.preview_url,
+          metadata: voice.to_h
+        }
+      end
+    end
+
+    # Generate audio from text
+    #
+    # @param text [String] the text to convert
+    # @param voice_id [String] the voice ID
+    # @param options [Hash] additional options
+    # @return [Objects::Audio]
+    def generate(text, voice_id:, **options)
+      @client.tts.generate(text, voice_id: voice_id, **options)
+    end
+
+    # Stream audio from text
+    #
+    # @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(text, voice_id:, **options, &block)
+      @client.tts.stream(text, voice_id: voice_id, **options, &block)
+    end
+
+    # Check if streaming is supported
+    #
+    # @return [Boolean]
+    def supports_streaming?
+      true
+    end
+
+    # Get available models
+    #
+    # @return [Array<Hash>] normalized model data
+    def list_models
+      @client.models.list.map do |model|
+        {
+          provider: :elevenlabs,
+          model_id: model.model_id,
+          name: model.name,
+          multilingual: model.multilingual?,
+          languages: model.supported_language_codes,
+          metadata: model.to_h
+        }
+      end
+    end
+
+    # Get subscription/quota info
+    #
+    # @return [Hash] normalized quota data
+    def quota
+      sub = @client.user.subscription
+      {
+        provider: :elevenlabs,
+        tier: sub.tier,
+        characters_used: sub.character_count,
+        characters_limit: sub.character_limit,
+        characters_remaining: sub.characters_remaining,
+        resets_at: sub.next_reset_at
+      }
+    end
+
+    # Search voice library
+    #
+    # @param options [Hash] search options
+    # @return [Array<Hash>] normalized voice data
+    def search_voices(**options)
+      @client.voice_library.search(**options).map do |voice|
+        {
+          provider: :elevenlabs,
+          voice_id: voice.voice_id,
+          public_owner_id: voice.public_owner_id,
+          name: voice.name,
+          gender: voice.gender,
+          language: voice.language,
+          accent: voice.accent,
+          metadata: voice.to_h
+        }
+      end
+    end
+
+    # Ensure a library voice is available (for voice slot management)
+    #
+    # @param public_user_id [String]
+    # @param voice_id [String]
+    # @param name [String]
+    # @return [Hash] normalized voice data
+    def ensure_voice_available(public_user_id:, voice_id:, name:)
+      voice = @client.voice_slots.ensure_available(
+        public_user_id: public_user_id,
+        voice_id: voice_id,
+        name: name
+      )
+
+      {
+        provider: :elevenlabs,
+        voice_id: voice.voice_id,
+        name: voice.name,
+        metadata: voice.to_h
+      }
+    end
+  end
+end

data/lib/eleven_rb/version.rb

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