class RubyLLM::Transcription

A Transcription is text produced from spoken audio. RubyLLM.transcribe returns one. It holds the transcript along with any metadata the provider reports, such as language, duration, and timed segments.

transcription = RubyLLM.transcribe("meeting.wav")
transcription.text   # => "Welcome to today's meeting..."
transcription.model  # => "gpt-transcribe"

Attributes

duration [R]

The audio duration in seconds, or nil when the provider does not report it.

language [R]

The language of the audio, or nil when the provider does not report it.

model [R]

The id of the model that produced the transcription.

segments [R]

The timed segments of the transcript as an array of hashes, or nil when the provider does not return segments. Diarization models add a speaker label to each segment.

text [R]

The transcribed text.

words [R]

Word timing and speaker labels as an array of hashes, or nil when the provider does not return them. Request timing with timestamps:.

Public Class Methods

transcribe (audio_file, model: nil, language: nil, provider: nil, assume_model_exists: false, context: nil, prompt: nil, temperature: nil, format: nil, timestamps: nil, speaker_names: nil, speaker_references: nil, provider_options: {}, metadata: nil, &block)

Source

# File lib/ruby_llm/transcription.rb, line 113
def self.transcribe(audio_file,
                    model: nil,
                    language: nil,
                    provider: nil,
                    assume_model_exists: false,
                    context: nil,
                    prompt: nil,
                    temperature: nil,
                    format: nil,
                    timestamps: nil,
                    speaker_names: nil,
                    speaker_references: nil,
                    provider_options: {},
                    metadata: nil,
                    &block)
  config = context&.config || RubyLLM.config
  model ||= config.default_transcription_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,
    language: language,
    provider_options: provider_options,
    metadata: metadata,
    tokens: empty_tokens,
    cost: Cost.new(tokens: empty_tokens, model:, category: :audio_tokens)
  }

  RubyLLM.instrument('transcription.ruby_llm', payload, config: config) do |event|
    result = provider_instance.transcribe(audio_file, model:, language:, format:, timestamps:, speaker_names:,
                                                      speaker_references:, provider_options:, prompt:,
                                                      temperature:, &block)
    event[:result] = result
    event[:response_model] = result.model
    event[:tokens] = result.tokens
    event[:cost] = result.cost
    result
  end
end

Transcribes audio_file and returns a Transcription. The file may be a path, URL, or IO object. Uses config.default_transcription_model unless model: is given. Pass provider: and assume_model_exists: true to use a model that is not in the registry.

RubyLLM.transcribe("meeting.wav")
RubyLLM.transcribe("entrevista.mp3", language: "es")
RubyLLM.transcribe(
  "team-meeting.wav",
  model: "gpt-4o-transcribe-diarize",
  speaker_names: ["Alice", "Bob"],
  speaker_references: ["alice-voice.wav", "bob-voice.wav"]
)

language: hints at the spoken language using the provider’s accepted ISO 639-1 or BCP-47 language code. prompt: gives the model vocabulary or formatting guidance, and temperature: adjusts sampling. format: selects the transcript format in the provider’s own vocabulary: OpenAI takes values such as "text", "verbose_json", or "diarized_json", while Gemini takes a MIME type such as "text/plain". speaker_names: and speaker_references: label the speakers on models that support diarization; references may be paths, URLs, or IO objects. Option support depends on the selected model and provider. timestamps: requests :word timestamps. Some providers also accept :segment or :character; unsupported granularities raise ArgumentError. provider_options: takes options in the provider’s request vocabulary and merges them into the rendered request as-is.

Given a block, the transcript streams: each TranscriptionChunk is yielded as it arrives and the completed Transcription is still returned. Partial chunks replace earlier tentative text; only delta fields append to the committed transcript. WebSocket-based providers require the optional websocket-driver gem.

transcription = RubyLLM.transcribe("meeting.wav", model: "gpt-4o-transcribe") do |chunk|
  print chunk.delta
end

Raises RubyLLM::ModelNotFoundError if model: is not in the registry, and RubyLLM::Error when a block is given to a provider that does not stream transcriptions.

Public Instance Methods

cost ()

Source

# File lib/ruby_llm/transcription.rb, line 58
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 transcription cost across every provider attempt.

tokens ()

Source

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

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

Returns usage aggregated across every provider attempt.