elevenlabs_client 0.4.0 → 0.5.0

data/lib/elevenlabs_client/endpoints/speech_to_speech.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  class SpeechToSpeech
+    def initialize(client)
+      @client = client
+    end
+
+    # POST /v1/speech-to-speech/:voice_id
+    # Transform audio from one voice to another. Maintain full control over emotion, timing and delivery.
+    # Documentation: https://elevenlabs.io/docs/api-reference/speech-to-speech
+    #
+    # @param voice_id [String] ID of the voice to be used
+    # @param audio_file [IO, File] The audio file which holds the content and emotion
+    # @param filename [String] Original filename for the audio file
+    # @param options [Hash] Optional parameters
+    # @option options [Boolean] :enable_logging Enable logging (default: true)
+    # @option options [Integer] :optimize_streaming_latency Latency optimization level (0-4, deprecated)
+    # @option options [String] :output_format Output format (default: "mp3_44100_128")
+    # @option options [String] :model_id Model identifier (default: "eleven_english_sts_v2")
+    # @option options [String] :voice_settings JSON encoded voice settings
+    # @option options [Integer] :seed Deterministic sampling seed (0-4294967295)
+    # @option options [Boolean] :remove_background_noise Remove background noise (default: false)
+    # @option options [String] :file_format Input file format ("pcm_s16le_16" or "other")
+    # @return [String] Binary audio data
+    def convert(voice_id, audio_file, filename, **options)
+      endpoint = "/v1/speech-to-speech/#{voice_id}"
+      
+      # Build query parameters
+      query_params = {}
+      query_params[:enable_logging] = options[:enable_logging] unless options[:enable_logging].nil?
+      query_params[:optimize_streaming_latency] = options[:optimize_streaming_latency] if options[:optimize_streaming_latency]
+      query_params[:output_format] = options[:output_format] if options[:output_format]
+      
+      # Add query parameters to endpoint if any exist
+      if query_params.any?
+        query_string = query_params.map { |k, v| "#{k}=#{v}" }.join("&")
+        endpoint += "?#{query_string}"
+      end
+
+      # Build multipart payload
+      payload = {
+        audio: @client.file_part(audio_file, filename)
+      }
+      
+      # Add optional form parameters
+      payload[:model_id] = options[:model_id] if options[:model_id]
+      payload[:voice_settings] = options[:voice_settings] if options[:voice_settings]
+      payload[:seed] = options[:seed] if options[:seed]
+      payload[:remove_background_noise] = options[:remove_background_noise] unless options[:remove_background_noise].nil?
+      payload[:file_format] = options[:file_format] if options[:file_format]
+
+      @client.post_multipart(endpoint, payload)
+    end
+
+    # POST /v1/speech-to-speech/:voice_id/stream
+    # Stream audio from one voice to another. Maintain full control over emotion, timing and delivery.
+    # Documentation: https://elevenlabs.io/docs/api-reference/speech-to-speech/stream
+    #
+    # @param voice_id [String] ID of the voice to be used
+    # @param audio_file [IO, File] The audio file which holds the content and emotion
+    # @param filename [String] Original filename for the audio file
+    # @param options [Hash] Optional parameters
+    # @option options [Boolean] :enable_logging Enable logging (default: true)
+    # @option options [Integer] :optimize_streaming_latency Latency optimization level (0-4, deprecated)
+    # @option options [String] :output_format Output format (default: "mp3_44100_128")
+    # @option options [String] :model_id Model identifier (default: "eleven_english_sts_v2")
+    # @option options [String] :voice_settings JSON encoded voice settings
+    # @option options [Integer] :seed Deterministic sampling seed (0-4294967295)
+    # @option options [Boolean] :remove_background_noise Remove background noise (default: false)
+    # @option options [String] :file_format Input file format ("pcm_s16le_16" or "other")
+    # @param block [Proc] Block to handle each chunk of streaming audio data
+    # @return [Faraday::Response] Response object for streaming
+    def convert_stream(voice_id, audio_file, filename, **options, &block)
+      endpoint = "/v1/speech-to-speech/#{voice_id}/stream"
+      
+      # Build query parameters
+      query_params = {}
+      query_params[:enable_logging] = options[:enable_logging] unless options[:enable_logging].nil?
+      query_params[:optimize_streaming_latency] = options[:optimize_streaming_latency] if options[:optimize_streaming_latency]
+      query_params[:output_format] = options[:output_format] if options[:output_format]
+      
+      # Add query parameters to endpoint if any exist
+      if query_params.any?
+        query_string = query_params.map { |k, v| "#{k}=#{v}" }.join("&")
+        endpoint += "?#{query_string}"
+      end
+
+      # Build multipart payload
+      payload = {
+        audio: @client.file_part(audio_file, filename)
+      }
+      
+      # Add optional form parameters
+      payload[:model_id] = options[:model_id] if options[:model_id]
+      payload[:voice_settings] = options[:voice_settings] if options[:voice_settings]
+      payload[:seed] = options[:seed] if options[:seed]
+      payload[:remove_background_noise] = options[:remove_background_noise] unless options[:remove_background_noise].nil?
+      payload[:file_format] = options[:file_format] if options[:file_format]
+
+      # Use streaming multipart request
+      response = @client.instance_variable_get(:@conn).post(endpoint) do |req|
+        req.headers["xi-api-key"] = @client.api_key
+        req.body = payload
+        
+        # Set up streaming callback if block provided
+        if block_given?
+          req.options.on_data = proc do |chunk, _|
+            block.call(chunk)
+          end
+        end
+      end
+
+      @client.send(:handle_response, response)
+    end
+
+    # Alias methods for convenience
+    alias_method :voice_changer, :convert
+    alias_method :voice_changer_stream, :convert_stream
+
+    private
+
+    attr_reader :client
+  end
+end

data/lib/elevenlabs_client/endpoints/speech_to_text.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  class SpeechToText
+    def initialize(client)
+      @client = client
+    end
+
+    # POST /v1/speech-to-text
+    # Transcribe an audio or video file
+    # Documentation: https://elevenlabs.io/docs/api-reference/speech-to-text
+    #
+    # @param model_id [String] The ID of the model to use for transcription
+    # @param options [Hash] Optional parameters
+    # @option options [IO, File] :file The file to transcribe (required if no cloud_storage_url)
+    # @option options [String] :filename Original filename (required if file provided)
+    # @option options [String] :cloud_storage_url HTTPS URL of file to transcribe (required if no file)
+    # @option options [Boolean] :enable_logging Enable logging (default: true)
+    # @option options [String] :language_code ISO-639-1 or ISO-639-3 language code
+    # @option options [Boolean] :tag_audio_events Tag audio events like (laughter) (default: true)
+    # @option options [Integer] :num_speakers Maximum number of speakers (1-32)
+    # @option options [String] :timestamps_granularity Timestamp granularity ("none", "word", "character")
+    # @option options [Boolean] :diarize Annotate which speaker is talking (default: false)
+    # @option options [Float] :diarization_threshold Diarization threshold (0.1-0.4)
+    # @option options [Array] :additional_formats Additional export formats
+    # @option options [String] :file_format Input file format ("pcm_s16le_16" or "other")
+    # @option options [Boolean] :webhook Send result to webhook (default: false)
+    # @option options [String] :webhook_id Specific webhook ID
+    # @option options [Float] :temperature Randomness control (0.0-2.0)
+    # @option options [Integer] :seed Deterministic sampling seed (0-2147483647)
+    # @option options [Boolean] :use_multi_channel Multi-channel processing (default: false)
+    # @option options [String, Hash] :webhook_metadata Metadata for webhook
+    # @return [Hash] Transcription result or webhook response
+    def create(model_id, **options)
+      endpoint = "/v1/speech-to-text"
+      
+      # Build query parameters
+      query_params = {}
+      query_params[:enable_logging] = options[:enable_logging] unless options[:enable_logging].nil?
+      
+      # Add query parameters to endpoint if any exist
+      if query_params.any?
+        query_string = query_params.map { |k, v| "#{k}=#{v}" }.join("&")
+        endpoint += "?#{query_string}"
+      end
+
+      # Build multipart payload
+      payload = {
+        model_id: model_id
+      }
+      
+      # Add file or cloud storage URL (exactly one is required)
+      if options[:file] && options[:filename]
+        payload[:file] = @client.file_part(options[:file], options[:filename])
+      elsif options[:cloud_storage_url]
+        payload[:cloud_storage_url] = options[:cloud_storage_url]
+      else
+        raise ArgumentError, "Either :file with :filename or :cloud_storage_url must be provided"
+      end
+      
+      # Add optional form parameters
+      payload[:language_code] = options[:language_code] if options[:language_code]
+      payload[:tag_audio_events] = options[:tag_audio_events] unless options[:tag_audio_events].nil?
+      payload[:num_speakers] = options[:num_speakers] if options[:num_speakers]
+      payload[:timestamps_granularity] = options[:timestamps_granularity] if options[:timestamps_granularity]
+      payload[:diarize] = options[:diarize] unless options[:diarize].nil?
+      payload[:diarization_threshold] = options[:diarization_threshold] if options[:diarization_threshold]
+      payload[:additional_formats] = options[:additional_formats] if options[:additional_formats]
+      payload[:file_format] = options[:file_format] if options[:file_format]
+      payload[:webhook] = options[:webhook] unless options[:webhook].nil?
+      payload[:webhook_id] = options[:webhook_id] if options[:webhook_id]
+      payload[:temperature] = options[:temperature] if options[:temperature]
+      payload[:seed] = options[:seed] if options[:seed]
+      payload[:use_multi_channel] = options[:use_multi_channel] unless options[:use_multi_channel].nil?
+      
+      # Handle webhook_metadata (can be string or hash)
+      if options[:webhook_metadata]
+        if options[:webhook_metadata].is_a?(Hash)
+          payload[:webhook_metadata] = options[:webhook_metadata].to_json
+        else
+          payload[:webhook_metadata] = options[:webhook_metadata]
+        end
+      end
+
+      @client.post_multipart(endpoint, payload)
+    end
+
+    # GET /v1/speech-to-text/transcripts/:transcription_id
+    # Retrieve a previously generated transcript by its ID
+    # Documentation: https://elevenlabs.io/docs/api-reference/speech-to-text/get-transcript
+    #
+    # @param transcription_id [String] The unique ID of the transcript to retrieve
+    # @return [Hash] The transcript data
+    def get_transcript(transcription_id)
+      endpoint = "/v1/speech-to-text/transcripts/#{transcription_id}"
+      @client.get(endpoint)
+    end
+
+    # Alias methods for convenience
+    alias_method :transcribe, :create
+    alias_method :get_transcription, :get_transcript
+    alias_method :retrieve_transcript, :get_transcript
+
+    private
+
+    attr_reader :client
+  end
+end

data/lib/elevenlabs_client/endpoints/text_to_dialogue_stream.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  class TextToDialogueStream
+    def initialize(client)
+      @client = client
+    end
+
+    # POST /v1/text-to-dialogue/stream
+    # Converts a list of text and voice ID pairs into speech (dialogue) and returns an audio stream.
+    # Documentation: https://elevenlabs.io/docs/api-reference/text-to-dialogue/stream
+    #
+    # @param inputs [Array<Hash>] A list of dialogue inputs, each containing text and a voice ID
+    # @param options [Hash] Optional parameters
+    # @option options [String] :model_id Identifier of the model to be used (default: "eleven_v3")
+    # @option options [String] :language_code ISO 639-1 language code
+    # @option options [Hash] :settings Settings controlling the dialogue generation
+    # @option options [Array<Hash>] :pronunciation_dictionary_locators Pronunciation dictionary locators (max 3)
+    # @option options [Integer] :seed Deterministic sampling seed (0-4294967295)
+    # @option options [String] :apply_text_normalization Text normalization mode ("auto", "on", "off")
+    # @option options [String] :output_format Output format (defaults to "mp3_44100_128")
+    # @param block [Proc] Block to handle each audio chunk
+    # @return [Faraday::Response] The response object
+    def stream(inputs, **options, &block)
+      # Build endpoint with optional query params
+      output_format = options[:output_format] || "mp3_44100_128"
+      endpoint = "/v1/text-to-dialogue/stream?output_format=#{output_format}"
+
+      # Build request body
+      request_body = { inputs: inputs }
+      request_body[:model_id] = options[:model_id] if options[:model_id]
+      request_body[:language_code] = options[:language_code] if options[:language_code]
+      request_body[:settings] = options[:settings] if options[:settings]
+      request_body[:pronunciation_dictionary_locators] = options[:pronunciation_dictionary_locators] if options[:pronunciation_dictionary_locators]
+      request_body[:seed] = options[:seed] if options[:seed]
+      request_body[:apply_text_normalization] = options[:apply_text_normalization] if options[:apply_text_normalization]
+
+      @client.post_streaming(endpoint, request_body, &block)
+    end
+
+    # Alias for convenience
+    alias_method :text_to_dialogue_stream, :stream
+
+    private
+
+    attr_reader :client
+  end
+end
+
+

data/lib/elevenlabs_client/endpoints/text_to_speech_stream.rb

@@ -8,6 +8,7 @@ module ElevenlabsClient
 
     # POST /v1/text-to-speech/{voice_id}/stream
     # Stream text-to-speech audio in real-time chunks
+    # Documentation: https://elevenlabs.io/docs/api-reference/text-to-speech/stream
     #
     # @param voice_id [String] The ID of the voice to use
     # @param text [String] Text to synthesize

data/lib/elevenlabs_client/endpoints/text_to_speech_stream_with_timestamps.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  class TextToSpeechStreamWithTimestamps
+    def initialize(client)
+      @client = client
+    end
+
+    # POST /v1/text-to-speech/{voice_id}/stream/with-timestamps
+    # Stream text-to-speech audio with character-level timing information
+    # Documentation: https://elevenlabs.io/docs/api-reference/text-to-speech/stream-with-timestamps
+    #
+    # @param voice_id [String] Voice ID to be used
+    # @param text [String] The text that will get converted into speech
+    # @param options [Hash] Optional TTS parameters
+    # @option options [String] :model_id Model identifier (defaults to "eleven_multilingual_v2")
+    # @option options [String] :language_code ISO 639-1 language code for text normalization
+    # @option options [Hash] :voice_settings Voice settings overriding stored settings
+    # @option options [Array<Hash>] :pronunciation_dictionary_locators Pronunciation dictionary locators (max 3)
+    # @option options [Integer] :seed Deterministic sampling seed (0-4294967295)
+    # @option options [String] :previous_text Text that came before current request
+    # @option options [String] :next_text Text that comes after current request
+    # @option options [Array<String>] :previous_request_ids Request IDs of previous samples (max 3)
+    # @option options [Array<String>] :next_request_ids Request IDs of next samples (max 3)
+    # @option options [String] :apply_text_normalization Text normalization mode ("auto", "on", "off")
+    # @option options [Boolean] :apply_language_text_normalization Language text normalization
+    # @option options [Boolean] :use_pvc_as_ivc Use IVC version instead of PVC (deprecated)
+    # @option options [Boolean] :enable_logging Enable logging (defaults to true)
+    # @option options [Integer] :optimize_streaming_latency Latency optimizations (0-4, deprecated)
+    # @option options [String] :output_format Output format (defaults to "mp3_44100_128")
+    # @param block [Proc] Block to handle each streaming chunk containing audio and timing data
+    # @return [Faraday::Response] The response object
+    def stream(voice_id, text, **options, &block)
+      # Build query parameters
+      query_params = {}
+      query_params[:enable_logging] = options[:enable_logging] unless options[:enable_logging].nil?
+      query_params[:optimize_streaming_latency] = options[:optimize_streaming_latency] if options[:optimize_streaming_latency]
+      query_params[:output_format] = options[:output_format] if options[:output_format]
+      
+      # Build endpoint with query parameters
+      endpoint = "/v1/text-to-speech/#{voice_id}/stream/with-timestamps"
+      if query_params.any?
+        query_string = query_params.map { |k, v| "#{k}=#{v}" }.join("&")
+        endpoint += "?#{query_string}"
+      end
+      
+      # Build request body
+      request_body = { text: text }
+      
+      # Add optional body parameters
+      request_body[:model_id] = options[:model_id] if options[:model_id]
+      request_body[:language_code] = options[:language_code] if options[:language_code]
+      request_body[:voice_settings] = options[:voice_settings] if options[:voice_settings]
+      request_body[:pronunciation_dictionary_locators] = options[:pronunciation_dictionary_locators] if options[:pronunciation_dictionary_locators]
+      request_body[:seed] = options[:seed] if options[:seed]
+      request_body[:previous_text] = options[:previous_text] if options[:previous_text]
+      request_body[:next_text] = options[:next_text] if options[:next_text]
+      request_body[:previous_request_ids] = options[:previous_request_ids] if options[:previous_request_ids]
+      request_body[:next_request_ids] = options[:next_request_ids] if options[:next_request_ids]
+      request_body[:apply_text_normalization] = options[:apply_text_normalization] if options[:apply_text_normalization]
+      request_body[:apply_language_text_normalization] = options[:apply_language_text_normalization] unless options[:apply_language_text_normalization].nil?
+      request_body[:use_pvc_as_ivc] = options[:use_pvc_as_ivc] unless options[:use_pvc_as_ivc].nil?
+
+      # Use streaming method with JSON parsing for timestamp data
+      @client.post_streaming_with_timestamps(endpoint, request_body, &block)
+    end
+
+    # Alias for backward compatibility
+    alias_method :text_to_speech_stream_with_timestamps, :stream
+
+    private
+
+    attr_reader :client
+  end
+end

data/lib/elevenlabs_client/endpoints/text_to_speech_with_timestamps.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module ElevenlabsClient
+  class TextToSpeechWithTimestamps
+    def initialize(client)
+      @client = client
+    end
+
+    # POST /v1/text-to-speech/{voice_id}/with-timestamps
+    # Generate speech from text with precise character-level timing information
+    # Documentation: https://elevenlabs.io/docs/api-reference/text-to-speech/with-timestamps
+    #
+    # @param voice_id [String] Voice ID to be used
+    # @param text [String] The text that will get converted into speech
+    # @param options [Hash] Optional TTS parameters
+    # @option options [String] :model_id Model identifier (defaults to "eleven_multilingual_v2")
+    # @option options [String] :language_code ISO 639-1 language code for text normalization
+    # @option options [Hash] :voice_settings Voice settings overriding stored settings
+    # @option options [Array<Hash>] :pronunciation_dictionary_locators Pronunciation dictionary locators (max 3)
+    # @option options [Integer] :seed Deterministic sampling seed (0-4294967295)
+    # @option options [String] :previous_text Text that came before current request
+    # @option options [String] :next_text Text that comes after current request
+    # @option options [Array<String>] :previous_request_ids Request IDs of previous samples (max 3)
+    # @option options [Array<String>] :next_request_ids Request IDs of next samples (max 3)
+    # @option options [String] :apply_text_normalization Text normalization mode ("auto", "on", "off")
+    # @option options [Boolean] :apply_language_text_normalization Language text normalization
+    # @option options [Boolean] :use_pvc_as_ivc Use IVC version instead of PVC (deprecated)
+    # @option options [Boolean] :enable_logging Enable logging (defaults to true)
+    # @option options [Integer] :optimize_streaming_latency Latency optimizations (0-4, deprecated)
+    # @option options [String] :output_format Output format (defaults to "mp3_44100_128")
+    # @return [Hash] Response containing audio_base64, alignment, and normalized_alignment
+    def generate(voice_id, text, **options)
+      # Build query parameters
+      query_params = {}
+      query_params[:enable_logging] = options[:enable_logging] unless options[:enable_logging].nil?
+      query_params[:optimize_streaming_latency] = options[:optimize_streaming_latency] if options[:optimize_streaming_latency]
+      query_params[:output_format] = options[:output_format] if options[:output_format]
+      
+      # Build endpoint with query parameters
+      endpoint = "/v1/text-to-speech/#{voice_id}/with-timestamps"
+      if query_params.any?
+        query_string = query_params.map { |k, v| "#{k}=#{v}" }.join("&")
+        endpoint += "?#{query_string}"
+      end
+      
+      # Build request body
+      request_body = { text: text }
+      
+      # Add optional body parameters
+      request_body[:model_id] = options[:model_id] if options[:model_id]
+      request_body[:language_code] = options[:language_code] if options[:language_code]
+      request_body[:voice_settings] = options[:voice_settings] if options[:voice_settings]
+      request_body[:pronunciation_dictionary_locators] = options[:pronunciation_dictionary_locators] if options[:pronunciation_dictionary_locators]
+      request_body[:seed] = options[:seed] if options[:seed]
+      request_body[:previous_text] = options[:previous_text] if options[:previous_text]
+      request_body[:next_text] = options[:next_text] if options[:next_text]
+      request_body[:previous_request_ids] = options[:previous_request_ids] if options[:previous_request_ids]
+      request_body[:next_request_ids] = options[:next_request_ids] if options[:next_request_ids]
+      request_body[:apply_text_normalization] = options[:apply_text_normalization] if options[:apply_text_normalization]
+      request_body[:apply_language_text_normalization] = options[:apply_language_text_normalization] unless options[:apply_language_text_normalization].nil?
+      request_body[:use_pvc_as_ivc] = options[:use_pvc_as_ivc] unless options[:use_pvc_as_ivc].nil?
+
+      @client.post(endpoint, request_body)
+    end
+
+    # Alias for backward compatibility
+    alias_method :text_to_speech_with_timestamps, :generate
+
+    private
+
+    attr_reader :client
+  end
+end