elevenlabs_client 0.3.0 → 0.5.0

data/lib/elevenlabs_client/endpoints/websocket_text_to_speech.rb

@@ -0,0 +1,250 @@
+# frozen_string_literal: true
+
+require 'websocket-client-simple'
+require 'json'
+
+module ElevenlabsClient
+  class WebSocketTextToSpeech
+    def initialize(client)
+      @client = client
+      @base_url = client.base_url.gsub('https://', 'wss://').gsub('http://', 'ws://')
+    end
+
+    # Creates a WebSocket connection for real-time text-to-speech streaming
+    # Documentation: https://elevenlabs.io/docs/api-reference/websockets/text-to-speech
+    #
+    # @param voice_id [String] The unique identifier for the voice
+    # @param options [Hash] Optional parameters
+    # @option options [String] :model_id The model ID to use
+    # @option options [String] :language_code ISO 639-1 language code
+    # @option options [Boolean] :enable_logging Enable logging (default: true)
+    # @option options [Boolean] :enable_ssml_parsing Enable SSML parsing (default: false)
+    # @option options [String] :output_format Output audio format
+    # @option options [Integer] :inactivity_timeout Timeout in seconds (default: 20, max: 180)
+    # @option options [Boolean] :sync_alignment Include timing data (default: false)
+    # @option options [Boolean] :auto_mode Reduce latency mode (default: false)
+    # @option options [String] :apply_text_normalization Text normalization ("auto", "on", "off")
+    # @option options [Integer] :seed Deterministic sampling seed (0-4294967295)
+    # @return [WebSocket::Client::Simple::Client] WebSocket client instance
+    def connect_stream_input(voice_id, **options)
+      endpoint = "/v1/text-to-speech/#{voice_id}/stream-input"
+      
+      # Build query parameters in the same order as provided in options
+      allowed_keys = [:model_id, :language_code, :enable_logging, :enable_ssml_parsing, :output_format, :inactivity_timeout, :sync_alignment, :auto_mode, :apply_text_normalization, :seed]
+      pairs = []
+      options.each do |k, v|
+        next unless allowed_keys.include?(k)
+        next if v.nil?
+        next if (k == :language_code || k == :apply_text_normalization) && v.to_s.empty?
+        pairs << [k, v]
+      end
+      if pairs.any?
+        query_string = pairs.map { |k, v| "#{k}=#{v}" }.join("&")
+        endpoint += "?#{query_string}"
+      end
+      
+      url = "#{@base_url}#{endpoint}"
+      headers = { "xi-api-key" => @client.api_key }
+      
+      WebSocket::Client::Simple.connect(url, headers: headers)
+    end
+
+    # Creates a WebSocket connection for multi-context text-to-speech streaming
+    # Documentation: https://elevenlabs.io/docs/api-reference/websockets/multi-context
+    #
+    # @param voice_id [String] The unique identifier for the voice
+    # @param options [Hash] Optional parameters (same as connect_stream_input)
+    # @return [WebSocket::Client::Simple::Client] WebSocket client instance
+    def connect_multi_stream_input(voice_id, **options)
+      endpoint = "/v1/text-to-speech/#{voice_id}/multi-stream-input"
+      
+      # Build query parameters in the same order as provided in options
+      allowed_keys = [:model_id, :language_code, :enable_logging, :enable_ssml_parsing, :output_format, :inactivity_timeout, :sync_alignment, :auto_mode, :apply_text_normalization, :seed]
+      pairs = []
+      options.each do |k, v|
+        next unless allowed_keys.include?(k)
+        next if v.nil?
+        next if (k == :language_code || k == :apply_text_normalization) && v.to_s.empty?
+        pairs << [k, v]
+      end
+      if pairs.any?
+        query_string = pairs.map { |k, v| "#{k}=#{v}" }.join("&")
+        endpoint += "?#{query_string}"
+      end
+      
+      url = "#{@base_url}#{endpoint}"
+      headers = { "xi-api-key" => @client.api_key }
+      
+      WebSocket::Client::Simple.connect(url, headers: headers)
+    end
+
+    # Helper method to send initialization message for single stream
+    # @param ws [WebSocket::Client::Simple::Client] WebSocket client
+    # @param options [Hash] Initialization options
+    # @option options [String] :text Initial text (usually a space)
+    # @option options [Hash] :voice_settings Voice settings hash
+    # @option options [String] :xi_api_key API key (will use client's key if not provided)
+    def send_initialize_connection(ws, **options)
+      message = {
+        text: options[:text] || " ",
+        voice_settings: options[:voice_settings] || {},
+        xi_api_key: options[:xi_api_key] || @client.api_key
+      }
+      
+      ws.send(message.to_json)
+    end
+
+    # Helper method to send text for single stream
+    # @param ws [WebSocket::Client::Simple::Client] WebSocket client
+    # @param text [String] Text to convert to speech
+    # @param options [Hash] Optional parameters
+    # @option options [Boolean] :try_trigger_generation Try to trigger generation
+    # @option options [Hash] :voice_settings Voice settings override
+    def send_text(ws, text, **options)
+      message = { text: text }
+      message[:try_trigger_generation] = options[:try_trigger_generation] unless options[:try_trigger_generation].nil?
+      message[:voice_settings] = options[:voice_settings] if options[:voice_settings]
+      
+      ws.send(message.to_json)
+    end
+
+    # Helper method to close connection for single stream
+    # @param ws [WebSocket::Client::Simple::Client] WebSocket client
+    def send_close_connection(ws)
+      message = { text: "" }
+      ws.send(message.to_json)
+    end
+
+    # Helper method to send initialization message for multi-context stream
+    # @param ws [WebSocket::Client::Simple::Client] WebSocket client
+    # @param context_id [String] Context identifier
+    # @param options [Hash] Initialization options
+    def send_initialize_connection_multi(ws, context_id, **options)
+      message = {
+        text: options[:text] || " ",
+        voice_settings: options[:voice_settings] || {},
+        context_id: context_id
+      }
+      
+      ws.send(message.to_json)
+    end
+
+    # Helper method to initialize a new context in multi-stream
+    # @param ws [WebSocket::Client::Simple::Client] WebSocket client
+    # @param context_id [String] Context identifier
+    # @param options [Hash] Context options
+    def send_initialize_context(ws, context_id, **options)
+      message = {
+        context_id: context_id,
+        voice_settings: options[:voice_settings] || {}
+      }
+      message[:model_id] = options[:model_id] if options[:model_id]
+      message[:language_code] = options[:language_code] if options[:language_code]
+      
+      ws.send(message.to_json)
+    end
+
+    # Helper method to send text for multi-context stream
+    # @param ws [WebSocket::Client::Simple::Client] WebSocket client
+    # @param context_id [String] Context identifier
+    # @param text [String] Text to convert to speech
+    # @param options [Hash] Optional parameters
+    def send_text_multi(ws, context_id, text, **options)
+      message = {
+        text: text,
+        context_id: context_id
+      }
+      message[:flush] = options[:flush] unless options[:flush].nil?
+      
+      ws.send(message.to_json)
+    end
+
+    # Helper method to flush a context
+    # @param ws [WebSocket::Client::Simple::Client] WebSocket client
+    # @param context_id [String] Context identifier
+    def send_flush_context(ws, context_id)
+      message = {
+        context_id: context_id,
+        flush: true
+      }
+      
+      ws.send(message.to_json)
+    end
+
+    # Helper method to close a specific context
+    # @param ws [WebSocket::Client::Simple::Client] WebSocket client
+    # @param context_id [String] Context identifier
+    def send_close_context(ws, context_id)
+      message = {
+        context_id: context_id,
+        close_context: true
+      }
+      
+      ws.send(message.to_json)
+    end
+
+    # Helper method to keep a context alive
+    # @param ws [WebSocket::Client::Simple::Client] WebSocket client
+    # @param context_id [String] Context identifier
+    def send_keep_context_alive(ws, context_id)
+      message = {
+        context_id: context_id,
+        keep_context_alive: true
+      }
+      
+      ws.send(message.to_json)
+    end
+
+    # Helper method to close the entire socket
+    # @param ws [WebSocket::Client::Simple::Client] WebSocket client
+    def send_close_socket(ws)
+      message = { close_socket: true }
+      ws.send(message.to_json)
+    end
+
+    # Convenience method to create a complete streaming session
+    # @param voice_id [String] The unique identifier for the voice
+    # @param text_chunks [Array<String>] Array of text chunks to stream
+    # @param options [Hash] Connection and voice options
+    # @param block [Proc] Block to handle audio chunks
+    def stream_text_to_speech(voice_id, text_chunks, **options, &block)
+      ws = connect_stream_input(voice_id, **options)
+      
+      ws.on :open do
+        # Initialize connection
+        send_initialize_connection(ws, **options)
+        
+        # Send text chunks
+        text_chunks.each_with_index do |chunk, index|
+          send_text(ws, chunk, try_trigger_generation: (index == text_chunks.length - 1))
+        end
+        
+        # Close connection
+        send_close_connection(ws)
+      end
+      
+      ws.on :message do |msg|
+        data = JSON.parse(msg.data)
+        if data['audio'] && block_given?
+          # Decode base64 audio and yield to block
+          audio_data = Base64.decode64(data['audio'])
+          block.call(audio_data, data)
+        end
+      end
+      
+      ws.on :error do |e|
+        raise APIError, "WebSocket error: #{e.message}"
+      end
+      
+      ws
+    end
+
+    # Alias methods for convenience
+    alias_method :connect_single_stream, :connect_stream_input
+    alias_method :connect_multi_context, :connect_multi_stream_input
+
+    private
+
+    attr_reader :client
+  end
+end

data/lib/elevenlabs_client/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ElevenlabsClient
-  VERSION = "0.3.0"
+  VERSION = "0.5.0"
 end

data/lib/elevenlabs_client.rb

@@ -6,17 +6,24 @@ require_relative "elevenlabs_client/settings"
 require_relative "elevenlabs_client/endpoints/dubs"
 require_relative "elevenlabs_client/endpoints/text_to_speech"
 require_relative "elevenlabs_client/endpoints/text_to_speech_stream"
+require_relative "elevenlabs_client/endpoints/text_to_speech_with_timestamps"
+require_relative "elevenlabs_client/endpoints/text_to_speech_stream_with_timestamps"
 require_relative "elevenlabs_client/endpoints/text_to_dialogue"
+require_relative "elevenlabs_client/endpoints/text_to_dialogue_stream"
 require_relative "elevenlabs_client/endpoints/sound_generation"
 require_relative "elevenlabs_client/endpoints/text_to_voice"
 require_relative "elevenlabs_client/endpoints/models"
 require_relative "elevenlabs_client/endpoints/voices"
 require_relative "elevenlabs_client/endpoints/music"
+require_relative "elevenlabs_client/endpoints/audio_isolation"
+require_relative "elevenlabs_client/endpoints/audio_native"
+require_relative "elevenlabs_client/endpoints/forced_alignment"
+require_relative "elevenlabs_client/endpoints/speech_to_speech"
+require_relative "elevenlabs_client/endpoints/speech_to_text"
+require_relative "elevenlabs_client/endpoints/websocket_text_to_speech"
 require_relative "elevenlabs_client/client"
 
 module ElevenlabsClient
-  class Error < StandardError; end
-
   # Convenience method to create a new client
   def self.new(**options)
     Client.new(**options)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: elevenlabs_client
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.5.0
 platform: ruby
 authors:
 - Vitor Oliveira
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-09-13 00:00:00.000000000 Z
+date: 2025-09-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -38,6 +38,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: websocket-client-simple
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.8'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -121,15 +135,24 @@ files:
 - README.md
 - lib/elevenlabs_client.rb
 - lib/elevenlabs_client/client.rb
+- lib/elevenlabs_client/endpoints/audio_isolation.rb
+- lib/elevenlabs_client/endpoints/audio_native.rb
 - lib/elevenlabs_client/endpoints/dubs.rb
+- lib/elevenlabs_client/endpoints/forced_alignment.rb
 - lib/elevenlabs_client/endpoints/models.rb
 - lib/elevenlabs_client/endpoints/music.rb
 - lib/elevenlabs_client/endpoints/sound_generation.rb
+- lib/elevenlabs_client/endpoints/speech_to_speech.rb
+- lib/elevenlabs_client/endpoints/speech_to_text.rb
 - lib/elevenlabs_client/endpoints/text_to_dialogue.rb
+- lib/elevenlabs_client/endpoints/text_to_dialogue_stream.rb
 - lib/elevenlabs_client/endpoints/text_to_speech.rb
 - lib/elevenlabs_client/endpoints/text_to_speech_stream.rb
+- lib/elevenlabs_client/endpoints/text_to_speech_stream_with_timestamps.rb
+- lib/elevenlabs_client/endpoints/text_to_speech_with_timestamps.rb
 - lib/elevenlabs_client/endpoints/text_to_voice.rb
 - lib/elevenlabs_client/endpoints/voices.rb
+- lib/elevenlabs_client/endpoints/websocket_text_to_speech.rb
 - lib/elevenlabs_client/errors.rb
 - lib/elevenlabs_client/settings.rb
 - lib/elevenlabs_client/version.rb