eleven_rb 0.3.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f8b7a2ab5d7ebe900552e83ae3e8499545f788da927ffc60d54185464d3bbc3
-  data.tar.gz: ee1b62923b6fc88304f4c78a60f68164617fd0f46d68cca09ad1496f14dda10d
+  metadata.gz: ed711abcce18771ad13f10bcb29754605be61f7d02f7114f0e0b28b0dad4d556
+  data.tar.gz: 146285726bc80b0c3eab0b307a7ec4b788a8f3465903992bb12fc2b34bc1694b
 SHA512:
-  metadata.gz: 3079784a64fe6d3bff8e2c631d46763dcc6e352da16e9a7599d0ef0df7be45694c3b00279d3362f6459f7168c72f26b0e460eb80bd07239b675394979fd9cc59
-  data.tar.gz: 224530d093fdbd9b489adf6199cfd4cd19e22b2e9074bd42f59345fd0a5efcd06930c9ef9e9bfe9ab9034621c54eaf6c9443ba1b5aee91296c7365347fbcbe67
+  metadata.gz: 6bf8e216c83287bb099e4a6bbed4ef718329f361fb7dfb4c70bf122f2512c74916eb1540fe6a1dfd4ae01e0edc53edc05408a017946f504c09611a54a6c2370b
+  data.tar.gz: 1839c52e3adf4efed58c410f08fa5c5e4818fde0964922e0752019b6606d726ed66a4f48a767b4e2110aa3b0cf98e7f4666eaef64552ec9f0f976378b1ef5094

data/CHANGELOG.md

@@ -7,6 +7,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.0.0] - 2026-03-10
+
+### Added
+
+- Text-to-Dialogue multi-speaker audio generation via `client.text_to_dialogue.generate` (`POST /v1/text-to-dialogue`)
+- `Client#text_to_dialogue` resource with `dialogue` alias
+- Multi-speaker input validation (max 10 unique voices, 5000 character limit)
+- `eleven_v3` model added to `CostInfo::COST_PER_1K_CHARS` ($0.30/1K chars)
+- `Models#latest` method returning the most capable model (`eleven_v3`)
+- Audio tags support via v3 model (`[laughs]`, `[whispers]`, `[excited]`, etc.)
+- `CostInfo` now accepts `character_count:` keyword as alternative to `text:`
+- TTS generation with word-level timestamps via `client.tts.generate_with_timestamps`
+
+### Changed
+
+- `CostInfo#initialize` signature: `text:` is now optional when `character_count:` is provided (backwards-compatible)
+
+## [0.4.0] - 2026-03-10
+
+### Added
+
+- Speech-to-Speech voice conversion via `client.sts.convert` (`POST /v1/speech-to-speech/{voice_id}`)
+- `Client#speech_to_speech` resource with `sts` alias
+- Accepts file paths (String) or IO objects (IO, StringIO, Tempfile) for audio input
+- Multipart upload with binary response support
+- Default model: `eleven_english_sts_v2`
+
+### Changed
+
+- `Resources::Base#post_multipart` and `HTTP::Client#post_multipart` now accept `response_type:` parameter (defaults to `:json`, backwards-compatible)
+
 ## [0.3.0] - 2026-02-08
 
 ### Added

data/README.md

@@ -4,11 +4,13 @@
 [![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, Sound Effects, and Music API.
+A Ruby client for the [ElevenLabs](https://try.elevenlabs.io/qyk2j8gumrjz) Text-to-Speech, Speech-to-Speech, Text-to-Dialogue, Sound Effects, and Music API.
 
 ## Features
 
 - Text-to-Speech generation and streaming
+- Speech-to-Speech voice conversion
+- Text-to-Dialogue multi-speaker generation with audio tags
 - Sound effects generation from text descriptions
 - Music generation from prompts or composition plans
 - Voice management (list, get, create, update, delete)
@@ -72,7 +74,7 @@ audio.save_to_file("output.mp3")
 audio = client.tts.generate(
   "Hello world",
   voice_id: "voice_id",
-  model_id: "eleven_multilingual_v2",
+  model_id: "eleven_v3",             # Most expressive, 70+ languages, audio tags
   voice_settings: {
     stability: 0.5,
     similarity_boost: 0.75
@@ -88,6 +90,64 @@ File.open("output.mp3", "wb") do |file|
 end
 ```
 
+### Speech-to-Speech
+
+```ruby
+# Convert audio to a different voice
+audio = client.sts.convert("input.mp3", voice_id: "voice_id")
+audio.save_to_file("output.mp3")
+
+# With options
+audio = client.sts.convert(
+  "input.mp3",
+  voice_id: "voice_id",
+  model_id: "eleven_english_sts_v2",
+  voice_settings: { stability: 0.5, similarity_boost: 0.75 },
+  remove_background_noise: true,
+  output_format: "mp3_44100_192"
+)
+
+# From an IO object
+io = File.open("input.mp3", "rb")
+audio = client.sts.convert(io, voice_id: "voice_id")
+```
+
+### Text-to-Dialogue
+
+```ruby
+# Generate multi-speaker dialogue
+audio = client.text_to_dialogue.generate([
+  { text: "[excited] Welcome to the show!", voice_id: "voice_abc" },
+  { text: "[laughs] Thanks for having me.", voice_id: "voice_xyz" },
+  { text: "So tell us about your project...", voice_id: "voice_abc" }
+])
+audio.save_to_file("dialogue.mp3")
+
+# With options
+audio = client.dialogue.generate(
+  inputs,
+  model_id: "eleven_v3",
+  language_code: "en",
+  settings: { stability: 0.5 },
+  seed: 42,
+  output_format: "mp3_44100_192"
+)
+```
+
+### Audio Tags
+
+The `eleven_v3` model supports inline audio tags for expressive speech:
+
+```ruby
+audio = client.tts.generate(
+  "[excited] Oh wow, this is AMAZING! [laughs] I can't believe it...",
+  voice_id: "voice_id",
+  model_id: "eleven_v3"
+)
+```
+
+Supported tags include `[laughs]`, `[whispers]`, `[sighs]`, `[excited]`, `[sarcastic]`, `[curious]`, `[pause]`, and more. Use CAPS for emphasis, `...` for pauses, and `—` for interruptions. See the [ElevenLabs v3 documentation](https://elevenlabs.io/docs/guides/audio-tags) for the full list.
+
 ### Sound Effects
 
 ```ruby
@@ -251,6 +311,9 @@ client = ElevenRb::Client.new(
 models = client.models.list
 models.each { |m| puts "#{m.name} (#{m.model_id})" }
 
+# Get the latest/most capable model
+client.models.latest  # => "eleven_v3"
+
 # Get multilingual models
 client.models.multilingual
 

data/lib/eleven_rb/client.rb

@@ -79,6 +79,14 @@ module ElevenRb
       @user ||= Resources::User.new(http_client)
     end
 
+    # Speech-to-speech resource
+    #
+    # @return [Resources::SpeechToSpeech]
+    def speech_to_speech
+      @speech_to_speech ||= Resources::SpeechToSpeech.new(http_client)
+    end
+    alias sts speech_to_speech
+
     # Sound effects resource
     #
     # @return [Resources::SoundEffects]
@@ -93,6 +101,14 @@ module ElevenRb
       @music ||= Resources::Music.new(http_client)
     end
 
+    # Text-to-dialogue resource
+    #
+    # @return [Resources::TextToDialogue]
+    def text_to_dialogue
+      @text_to_dialogue ||= Resources::TextToDialogue.new(http_client)
+    end
+    alias dialogue text_to_dialogue
+
     # Voice slot manager
     #
     # @return [VoiceSlotManager]

data/lib/eleven_rb/http/client.rb

@@ -49,9 +49,10 @@ module ElevenRb
       #
       # @param path [String] the API path
       # @param params [Hash] form parameters including files
-      # @return [Hash] parsed JSON response
-      def post_multipart(path, params)
-        request(:post, path, body: params, multipart: true)
+      # @param response_type [Symbol] :json or :binary
+      # @return [Hash, String] parsed JSON or binary response
+      def post_multipart(path, params, response_type: :json)
+        request(:post, path, body: params, multipart: true, response_type: response_type)
       end
 
       # Make a streaming POST request

data/lib/eleven_rb/objects/cost_info.rb

@@ -12,6 +12,7 @@ module ElevenRb
         'eleven_monolingual_v1' => 0.30,
         'eleven_multilingual_v1' => 0.30,
         'eleven_multilingual_v2' => 0.30,
+        'eleven_v3' => 0.30,
         'eleven_turbo_v2' => 0.18,
         'eleven_turbo_v2_5' => 0.18,
         'eleven_english_sts_v2' => 0.30,
@@ -23,11 +24,12 @@ module ElevenRb
 
       # Initialize cost info
       #
-      # @param text [String] the text being converted
+      # @param text [String, nil] the text being converted
+      # @param character_count [Integer, nil] direct character count (alternative to text)
       # @param voice_id [String] the voice ID
       # @param model_id [String] the model ID
-      def initialize(text:, voice_id:, model_id:)
-        @character_count = text.length
+      def initialize(voice_id:, model_id:, text: nil, character_count: nil)
+        @character_count = character_count || text&.length || 0
         @voice_id = voice_id
         @model_id = model_id
       end

data/lib/eleven_rb/resources/base.rb

@@ -64,9 +64,10 @@ module ElevenRb
       #
       # @param path [String]
       # @param params [Hash]
-      # @return [Hash]
-      def post_multipart(path, params)
-        http_client.post_multipart(path, params)
+      # @param response_type [Symbol] :json or :binary
+      # @return [Hash, String]
+      def post_multipart(path, params, response_type: :json)
+        http_client.post_multipart(path, params, response_type: response_type)
       end
 
       # Validate presence of a value

data/lib/eleven_rb/resources/models.rb

@@ -54,6 +54,13 @@ module ElevenRb
         get('eleven_multilingual_v2') || tts_capable.first
       end
 
+      # Get the latest/most capable model
+      #
+      # @return [Objects::Model, nil]
+      def latest
+        get('eleven_v3') || default
+      end
+
       # Get model IDs as array
       #
       # @return [Array<String>]

data/lib/eleven_rb/resources/speech_to_speech.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Resources
+    # Speech-to-speech voice conversion resource
+    #
+    # Converts audio from one voice to another while preserving timing,
+    # cadence, and emotion. Uses ElevenLabs STS API with multipart upload.
+    #
+    # @example Convert a file
+    #   audio = client.sts.convert("input.mp3", voice_id: "abc123")
+    #   audio.save_to_file("output.mp3")
+    #
+    # @example Convert an IO object
+    #   io = File.open("input.mp3", "rb")
+    #   audio = client.sts.convert(io, voice_id: "abc123")
+    class SpeechToSpeech < Base
+      DEFAULT_MODEL = 'eleven_english_sts_v2'
+      MAX_INPUT_BYTES = 50 * 1024 * 1024 # 50 MB
+
+      # Convert speech from one voice to another
+      #
+      # @param audio_input [String, IO, Tempfile] file path or IO object of source audio
+      # @param voice_id [String] target voice ID to convert into
+      # @param model_id [String] STS model (default: eleven_english_sts_v2)
+      # @param voice_settings [Hash, nil] override voice settings (stability, similarity_boost)
+      # @param remove_background_noise [Boolean] isolate speech before conversion
+      # @param output_format [String] audio output format
+      # @param seed [Integer, nil] for reproducible results
+      # @return [Objects::Audio]
+      def convert(audio_input, voice_id:, model_id: DEFAULT_MODEL,
+                  voice_settings: nil, remove_background_noise: false,
+                  output_format: 'mp3_44100_128', seed: nil)
+        validate_presence!(voice_id, 'voice_id')
+
+        file = prepare_upload(audio_input)
+
+        params = {
+          audio: file,
+          model_id: model_id
+        }
+        params[:voice_settings] = voice_settings.to_json if voice_settings
+        params[:remove_background_noise] = remove_background_noise.to_s
+        params[:seed] = seed.to_s if seed
+
+        path = "/speech-to-speech/#{voice_id}?output_format=#{output_format}"
+        response = post_multipart(path, params, response_type: :binary)
+
+        audio = Objects::Audio.new(
+          data: response,
+          format: output_format,
+          voice_id: voice_id,
+          text: '[speech-to-speech]',
+          model_id: model_id
+        )
+
+        notify_audio_generated(audio, voice_id: voice_id, model_id: model_id)
+        audio
+      ensure
+        file&.close if file.respond_to?(:close) && audio_input.is_a?(String)
+      end
+
+      private
+
+      def notify_audio_generated(audio, voice_id:, model_id:)
+        cost_info = Objects::CostInfo.new(text: '[sts]', voice_id: voice_id, model_id: model_id)
+        http_client.config.trigger(
+          :on_audio_generated,
+          audio: audio,
+          voice_id: voice_id,
+          text: '[speech-to-speech]',
+          cost_info: cost_info.to_h
+        )
+      end
+
+      # Prepare the audio input for multipart upload
+      #
+      # @param input [String, IO, StringIO, Tempfile] file path or IO object
+      # @return [IO] file handle ready for upload
+      def prepare_upload(input)
+        case input
+        when String
+          raise Errors::ValidationError, "File not found: #{input}" unless File.exist?(input)
+
+          File.open(input, 'rb')
+        when IO, StringIO, Tempfile
+          input
+        else
+          raise ArgumentError, "Expected file path or IO object, got #{input.class}"
+        end
+      end
+    end
+  end
+end

data/lib/eleven_rb/resources/text_to_dialogue.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module ElevenRb
+  module Resources
+    # Text-to-dialogue resource for multi-speaker audio generation
+    #
+    # @example Generate dialogue
+    #   audio = client.text_to_dialogue.generate([
+    #     { text: "[excited] Welcome!", voice_id: "voice_abc" },
+    #     { text: "[laughs] Thanks!", voice_id: "voice_xyz" }
+    #   ])
+    #   audio.save_to_file("dialogue.mp3")
+    class TextToDialogue < Base
+      DEFAULT_MODEL = 'eleven_v3'
+      MAX_VOICES_PER_REQUEST = 10
+      MAX_TEXT_LENGTH = 5000
+
+      # Generate dialogue audio from multiple speaker inputs
+      #
+      # @param inputs [Array<Hash>] Array of { text:, voice_id: } hashes
+      # @param model_id [String] Model to use (only eleven_v3 supported)
+      # @param language_code [String, nil] ISO 639-1 language code
+      # @param settings [Hash, nil] Generation settings (stability: 0.0-1.0)
+      # @param seed [Integer, nil] Seed for reproducibility
+      # @param output_format [String] Audio output format
+      # @param apply_text_normalization [String] "auto", "on", or "off"
+      # @return [Objects::Audio]
+      def generate(
+        inputs,
+        model_id: DEFAULT_MODEL,
+        language_code: nil,
+        settings: nil,
+        seed: nil,
+        output_format: 'mp3_44100_128',
+        apply_text_normalization: 'auto'
+      )
+        validate_inputs!(inputs)
+
+        body = build_request_body(inputs, model_id, language_code, settings, seed,
+                                  apply_text_normalization)
+
+        response = post_binary(
+          "/text-to-dialogue?output_format=#{output_format}",
+          body
+        )
+
+        build_audio_response(response, inputs, output_format, model_id)
+      end
+
+      private
+
+      def build_request_body(inputs, model_id, language_code, settings, seed,
+                             apply_text_normalization)
+        body = {
+          inputs: inputs.map { |i| { text: i[:text], voice_id: i[:voice_id] } },
+          model_id: model_id,
+          apply_text_normalization: apply_text_normalization
+        }
+
+        body[:language_code] = language_code if language_code
+        body[:settings] = settings if settings
+        body[:seed] = seed if seed
+        body
+      end
+
+      def build_audio_response(response, inputs, output_format, model_id)
+        total_text = inputs.map { |i| i[:text] }.join("\n")
+        total_chars = inputs.sum { |i| i[:text].length }
+        primary_voice = inputs.first[:voice_id]
+
+        audio = Objects::Audio.new(
+          data: response, format: output_format,
+          voice_id: primary_voice, text: total_text, model_id: model_id
+        )
+
+        cost_info = Objects::CostInfo.new(
+          character_count: total_chars, voice_id: primary_voice, model_id: model_id
+        )
+
+        http_client.config.trigger(
+          :on_audio_generated,
+          audio: audio, voice_id: primary_voice,
+          text: total_text, cost_info: cost_info.to_h
+        )
+
+        audio
+      end
+
+      def validate_inputs!(inputs)
+        raise Errors::ValidationError, 'inputs must be a non-empty array' unless inputs.is_a?(Array) && !inputs.empty?
+
+        inputs.each_with_index do |input, i|
+          validate_presence!(input[:text], "inputs[#{i}].text")
+          validate_presence!(input[:voice_id], "inputs[#{i}].voice_id")
+        end
+
+        unique_voices = inputs.map { |i| i[:voice_id] }.uniq
+        if unique_voices.length > MAX_VOICES_PER_REQUEST
+          raise Errors::ValidationError,
+                "Maximum #{MAX_VOICES_PER_REQUEST} unique voices per request " \
+                "(got #{unique_voices.length})"
+        end
+
+        total_chars = inputs.sum { |i| i[:text].length }
+        return unless total_chars > MAX_TEXT_LENGTH
+
+        raise Errors::ValidationError,
+              "Total text length #{total_chars} exceeds maximum " \
+              "#{MAX_TEXT_LENGTH} characters"
+      end
+    end
+  end
+end

data/lib/eleven_rb/version.rb

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

data/lib/eleven_rb.rb

@@ -108,6 +108,8 @@ require_relative 'eleven_rb/resources/models'
 require_relative 'eleven_rb/resources/user'
 require_relative 'eleven_rb/resources/sound_effects'
 require_relative 'eleven_rb/resources/music'
+require_relative 'eleven_rb/resources/speech_to_speech'
+require_relative 'eleven_rb/resources/text_to_dialogue'
 
 # High-level components
 require_relative 'eleven_rb/voice_slot_manager'

metadata

@@ -1,14 +1,13 @@
 --- !ruby/object:Gem::Specification
 name: eleven_rb
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Web Ventures Ltd
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-02-08 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: base64
@@ -123,9 +122,9 @@ dependencies:
       - !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.
+  A comprehensive Ruby client for ElevenLabs covering Text-to-Speech,
+  Speech-to-Speech, Text-to-Dialogue, Sound Effects, and Music generation
+  with voice management, streaming, and built-in cost tracking.
 email:
 - gems@dev.webven.nz
 executables: []
@@ -158,6 +157,8 @@ files:
 - lib/eleven_rb/resources/models.rb
 - lib/eleven_rb/resources/music.rb
 - lib/eleven_rb/resources/sound_effects.rb
+- lib/eleven_rb/resources/speech_to_speech.rb
+- lib/eleven_rb/resources/text_to_dialogue.rb
 - lib/eleven_rb/resources/text_to_speech.rb
 - lib/eleven_rb/resources/user.rb
 - lib/eleven_rb/resources/voice_library.rb
@@ -173,7 +174,6 @@ metadata:
   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
@@ -188,8 +188,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.5.3
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
-summary: Ruby client for the ElevenLabs Text-to-Speech API
+summary: Ruby client for the ElevenLabs Audio AI API
 test_files: []