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  # => "whisper-1"

Attributes

duration [R]

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

input_tokens [R]

The number of input tokens reported by the provider, or nil.

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.

output_tokens [R]

The number of output tokens reported by the provider, or nil.

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-level timestamps as an array of hashes, or nil unless requested through format: and provider_options: on models that support them.

Public Class Methods

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

Source

# File lib/ruby_llm/transcription.rb, line 80
def self.transcribe(audio_file, # rubocop:disable Metrics/ParameterLists
                    model: nil,
                    language: nil,
                    provider: nil,
                    assume_model_exists: false,
                    context: nil,
                    prompt: nil,
                    temperature: nil,
                    format: nil,
                    speaker_names: nil,
                    speaker_references: nil,
                    provider_options: {},
                    metadata: nil)
  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)
  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
  }

  RubyLLM.instrument('transcription.ruby_llm', payload, config: config) do |event|
    result = provider_instance.transcribe(audio_file, model:, language:, format:, speaker_names:,
                                                      speaker_references:, provider_options:, prompt:,
                                                      temperature:)
    event[:result] = result
    event[:response_model] = result.model
    event[:input_tokens] = result.input_tokens
    event[:output_tokens] = result.output_tokens
    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 as an ISO 639-1 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. Providers silently ignore the options they do not support. provider_options: takes options in the provider’s request vocabulary and merges them into the rendered request as-is.

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