ReqLLM.Transcription (ReqLLM v1.19.0)

View Source

Speech-to-text transcription functionality for ReqLLM.

Inspired by the Vercel AI SDK's transcribe() function, this module provides audio transcription capabilities with support for:

  • Audio file transcription from binary data or file paths
  • Transcript segments with timing information
  • Language detection
  • Duration extraction
  • Provider-specific options

Usage

# Transcribe from a file path
{:ok, result} = ReqLLM.transcribe("openai:whisper-1", "/path/to/audio.mp3")

result.text
#=> "Hello, this is a transcription test."

result.segments
#=> [%{text: "Hello, this is a transcription test.", start_second: 0.0, end_second: 2.5}]

result.language
#=> "en"

result.duration_in_seconds
#=> 2.5

# Transcribe from binary audio data
audio_data = File.read!("/path/to/audio.mp3")
{:ok, result} = ReqLLM.transcribe("openai:whisper-1", {:binary, audio_data, "audio/mpeg"})

# With provider-specific options
{:ok, result} = ReqLLM.transcribe("openai:whisper-1", "/path/to/audio.mp3",
  language: "en",
  provider_options: [prompt: "ZyntriQix, Currentex, Reiterwood"]
)

Summary

Functions

schema()

Returns the base transcription options schema.

transcribe(model_spec, audio, opts \\ [])

Transcribes audio using an AI model.

transcribe!(model_spec, audio, opts \\ [])

Transcribes audio, raising on error.

transcribe_detailed(model_spec, audio, opts \\ [])

Transcribes audio and returns the unchanged transcription result with sparse metadata for the same provider call.

transcribe_detailed!(model_spec, audio, opts \\ [])

Transcribes audio with call metadata, raising on error.

Functions

schema()

@spec schema() :: NimbleOptions.t()

Returns the base transcription options schema.

transcribe(model_spec, audio, opts \\ [])

@spec transcribe(
  ReqLLM.model_input(),
  String.t()
  | {:binary, binary(), String.t()}
  | {:base64, String.t(), String.t()},
  keyword()
) :: {:ok, ReqLLM.Transcription.Result.t()} | {:error, term()}

Transcribes audio using an AI model.

Returns a ReqLLM.Transcription.Result containing the transcribed text, segments with timing, detected language, and duration.

Parameters

  • model_spec - Model specification (e.g., "openai:whisper-1", "groq:whisper-large-v3")
  • audio - Audio input in one of these formats:
    • String.t() - File path to an audio file
    • {:binary, binary(), String.t()} - Raw audio binary with media type (e.g., {:binary, data, "audio/mpeg"})
    • {:base64, String.t(), String.t()} - Base64-encoded audio with media type
  • opts - Additional options (keyword list)

Options

  • :language - Language hint in ISO-639-1 format (e.g., "en")
  • :provider_options - Provider-specific options
  • :receive_timeout - HTTP timeout in milliseconds (default: 120_000)
  • :total_timeout - Optional whole-call deadline in milliseconds, including retries

Examples

# From file path
{:ok, result} = ReqLLM.transcribe("openai:whisper-1", "speech.mp3")
result.text #=> "Hello world"

# From binary data
data = File.read!("speech.mp3")
{:ok, result} = ReqLLM.transcribe("openai:whisper-1", {:binary, data, "audio/mpeg"})

# With language hint
{:ok, result} = ReqLLM.transcribe("openai:whisper-1", "speech.mp3", language: "en")

transcribe!(model_spec, audio, opts \\ [])

@spec transcribe!(
  ReqLLM.model_input(),
  String.t()
  | {:binary, binary(), String.t()}
  | {:base64, String.t(), String.t()},
  keyword()
) :: ReqLLM.Transcription.Result.t() | no_return()

Transcribes audio, raising on error.

Same as transcribe/3 but raises on error.

transcribe_detailed(model_spec, audio, opts \\ [])

@spec transcribe_detailed(
  ReqLLM.model_input(),
  String.t()
  | {:binary, binary(), String.t()}
  | {:base64, String.t(), String.t()},
  keyword()
) :: {:ok, ReqLLM.Transcription.DetailedResult.t()} | {:error, term()}

Transcribes audio and returns the unchanged transcription result with sparse metadata for the same provider call.

The returned ReqLLM.Transcription.DetailedResult keeps the legacy result at detailed.result. Its call_metadata includes model and provider identity, then adds usage and cost, correlation and provider request IDs, warnings, and timings only when the request pipeline supplied them.

This function performs one provider request. Use transcribe/3 when call metadata is not needed.

transcribe_detailed!(model_spec, audio, opts \\ [])

@spec transcribe_detailed!(
  ReqLLM.model_input(),
  String.t()
  | {:binary, binary(), String.t()}
  | {:base64, String.t(), String.t()},
  keyword()
) :: ReqLLM.Transcription.DetailedResult.t() | no_return()

Transcribes audio with call metadata, raising on error.

Same as transcribe_detailed/3 but raises on error.