class RubyLLM::Speech

A Speech is audio generated from text. RubyLLM.speak returns one. It holds the raw audio bytes along with the model, voice, and format used.

speech = RubyLLM.speak "Hello, welcome to RubyLLM!"
speech.save "welcome.mp3"

Constants

MIME_TYPES: Maps audio format names to their MIME types.

Attributes

data [R]

The raw audio bytes returned by the provider.

format [R]

The audio format name, such as "mp3" or "pcm".

mime_type [R]

The MIME type of the audio, such as "audio/mpeg".

model [R]

The id of the model that generated the audio.

voice [R]

The voice used for synthesis. When no voice: was given, this is the provider default.

Public Class Methods

speak (input, model: nil, provider: nil, assume_model_exists: false, voice: nil, format: nil, context: nil, provider_options: {}, metadata: nil, &block)

Source

# File lib/ruby_llm/speech.rb, line 76
def self.speak(input,
               model: nil,
               provider: nil,
               assume_model_exists: false,
               voice: nil,
               format: nil,
               context: nil,
               provider_options: {},
               metadata: nil,
               &block)
  config = context&.config || RubyLLM.config
  model ||= config.default_speech_model
  model, provider_instance = Models.resolve(model, provider: provider, assume_model_exists: assume_model_exists,
                                                   config: config)
  empty_tokens = Tokens.new

  payload = {
    provider: provider_instance.slug,
    provider_class: provider_instance.class.display_name,
    model: model.id,
    model_info: model,
    input: input,
    voice: voice,
    format: format,
    provider_options: provider_options,
    metadata: metadata,
    streaming: !block.nil?,
    tokens: empty_tokens,
    cost: Cost.new(tokens: empty_tokens, model:, category: :audio_tokens)
  }

  RubyLLM.instrument('speech.ruby_llm', payload, config: config) do |event|
    result = provider_instance.speak(input, model:, voice:, format:, provider_options:, &block)
    event[:result] = result
    event[:response_model] = result.model
    event[:voice] = result.voice
    event[:format] = result.format
    event[:audio_bytes] = result.to_blob.bytesize
    event[:tokens] = result.tokens
    event[:cost] = result.cost
    result
  end
end

Generates speech for input and returns a Speech holding the audio. Uses config.default_speech_model unless model: is given. Pass provider: and assume_model_exists: true to use a model that is not in the registry. provider_options: takes options in the provider’s request vocabulary, such as instructions: and speed: for OpenAI, and merges them into the request as-is.

speech = RubyLLM.speak "Hello, welcome to RubyLLM!"
speech.save "welcome.mp3"

RubyLLM.speak "Welcome back.", voice: "nova"
RubyLLM.speak "Save this as a WAV file.", format: "wav"
RubyLLM.speak "Say cheerfully: Have a wonderful day!",
              model: "gemini-3.1-flash-tts-preview", provider: :gemini

Given a block, yields SpeechChunk objects as audio arrives and still returns the complete Speech. Chunks contain consecutive bytes of the recording and are not separate audio files.

File.open("welcome.mp3", "wb") do |file|
  RubyLLM.speak("Welcome back.") { |chunk| file.write(chunk.data) }
end

Raises RubyLLM::Error when the selected protocol cannot stream speech, or RubyLLM::ModelNotFoundError if model: is not in the registry.

Public Instance Methods

cost ()

Source

# File lib/ruby_llm/speech.rb, line 134
def cost
  return ruby_llm_usage_cost unless ruby_llm_usage_entries.empty?

  Cost.new(tokens:, model: model_info, category: :audio_tokens)
end

Returns the speech cost across every provider attempt.

save (path)

Source

# File lib/ruby_llm/speech.rb, line 150
def save(path)
  File.binwrite(File.expand_path(path), to_blob)
  path
end

Writes the audio to path in binary mode and returns path.

speech.save "welcome.mp3"

to_blob ()

Source

# File lib/ruby_llm/speech.rb, line 121
def to_blob
  data
end

Returns the raw audio bytes. Alias for data, mirroring Image#to_blob.

tokens ()

Source

# File lib/ruby_llm/speech.rb, line 127
def tokens
  return ruby_llm_usage_tokens unless ruby_llm_usage_entries.empty?

  Tokens.new(input: @input_tokens, output: @output_tokens)
end

Returns provider-reported usage across every attempt. Its fields are nil when the provider did not report any.