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)

Source

# File lib/ruby_llm/speech.rb, line 61
def self.speak(input, # rubocop:disable Metrics/ParameterLists
               model: nil,
               provider: nil,
               assume_model_exists: false,
               voice: nil,
               format: nil,
               context: nil,
               provider_options: {},
               metadata: nil)
  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)

  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
  }

  RubyLLM.instrument('speech.ruby_llm', payload, config: config) do |event|
    result = provider_instance.speak(input, model:, voice:, format:, provider_options:)
    event[:result] = result
    event[:response_model] = result.model
    event[:voice] = result.voice
    event[:format] = result.format
    event[:audio_bytes] = result.to_blob.bytesize
    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-2.5-flash-preview-tts", provider: :gemini

Raises RubyLLM::ModelNotFoundError if model: is not in the registry.

Public Instance Methods

save (path)

Source

# File lib/ruby_llm/speech.rb, line 107
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 99
def to_blob
  data
end

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