Deepgram.Listen (Deepgram v0.1.0)

View Source

Speech-to-Text services for the Deepgram API.

This module provides both prerecorded (REST API) and live (WebSocket API) speech-to-text transcription services. With Deepgram's Speech-to-Text capabilities, you can transcribe audio from various sources with high accuracy and customize the transcription process with a wide range of options.

Key Features

  • Multiple Input Sources: Transcribe audio from URLs or files
  • Real-time Streaming: Transcribe live audio streams using WebSockets
  • Asynchronous Processing: Process large files with callback support
  • Advanced Features: Speaker diarization, punctuation, smart formatting
  • Language Detection: Automatic language identification
  • Custom Models: Use domain-specific models for higher accuracy

Usage Examples

Basic URL Transcription

client = Deepgram.new(api_key: "your-api-key")
{:ok, response} = Deepgram.Listen.transcribe_url(client, %{url: "https://example.com/audio.wav"})

Enhanced Transcription with Options

client = Deepgram.new(api_key: "your-api-key")
{:ok, response} = Deepgram.Listen.transcribe_url(
  client, 
  %{url: "https://example.com/audio.wav"}, 
  %{
    model: "nova-2",         # Use the Nova-2 model
    punctuate: true,        # Add punctuation
    diarize: true,          # Identify different speakers
    smart_format: true,     # Format numbers, dates, etc.
    detect_language: true,  # Detect the audio language
    utterances: true        # Split by speaker turns
  }
)

Live Audio Streaming

# Start a WebSocket connection
{:ok, websocket} = Deepgram.Listen.live_transcription(
  client,
  %{
    model: "nova-2",
    interim_results: true,  # Get results as they become available
    punctuate: true,
    encoding: "linear16",   # Audio encoding format
    sample_rate: 16000      # Audio sample rate in Hz
  }
)

# Send audio chunks
Deepgram.Listen.WebSocket.send_audio(websocket, audio_chunk)

# Handle incoming messages
receive do
  {:deepgram_result, result} -> 
    # Process transcription result
  {:deepgram_error, error} -> 
    # Handle error
end

See the examples directory for more detailed usage examples.

Summary

Functions

Starts a live transcription WebSocket connection.

Transcribes audio from a file with callback support (asynchronous).

Transcribes audio from a URL source.

Transcribes audio from a URL with callback support (asynchronous).

Functions

live_transcription(client, options \\ %{})

@spec live_transcription(Deepgram.Client.t(), Deepgram.Types.Listen.live_options()) ::
  {:ok, pid()} | {:error, any()}

Starts a live transcription WebSocket connection.

Parameters

Examples

iex> client = Deepgram.new(api_key: "your-api-key")
iex> options = %{model: "nova-2", interim_results: true}
iex> {:ok, websocket} = Deepgram.Listen.live_transcription(client, options)
{:ok, #PID<...>}

transcribe_file(client, file_data, options \\ %{})

Transcribes audio from a file.

Parameters

  • client - A Deepgram.Client struct
  • file_data - Binary data of the audio file
  • options - Optional transcription options (see Deepgram.Types.Listen.prerecorded_options/0)

Examples

iex> client = Deepgram.new(api_key: "your-api-key")
iex> {:ok, file_data} = File.read("path/to/audio.wav")
iex> options = %{model: "nova-2", punctuate: true}
iex> {:ok, response} = Deepgram.Listen.transcribe_file(client, file_data, options)
{:ok, %{metadata: %{...}, results: %{...}}}

transcribe_file_callback(client, file_data, callback_url, options \\ %{})

@spec transcribe_file_callback(
  Deepgram.Client.t(),
  binary(),
  String.t(),
  Deepgram.Types.Listen.prerecorded_options()
) :: {:ok, Deepgram.Types.Listen.async_response()} | {:error, any()}

Transcribes audio from a file with callback support (asynchronous).

Parameters

  • client - A Deepgram.Client struct
  • file_data - Binary data of the audio file
  • callback_url - URL to receive the transcription result
  • options - Optional transcription options (see Deepgram.Types.Listen.prerecorded_options/0)

Examples

iex> client = Deepgram.new(api_key: "your-api-key")
iex> {:ok, file_data} = File.read("path/to/audio.wav")
iex> callback_url = "https://example.com/webhook"
iex> options = %{model: "nova-2", punctuate: true}
iex> {:ok, response} = Deepgram.Listen.transcribe_file_callback(client, file_data, callback_url, options)
{:ok, %{request_id: "..."}}

transcribe_url(client, source, options \\ %{})

Transcribes audio from a URL source.

Parameters

  • client - A Deepgram.Client struct
  • source - A map containing the URL: %{url: "https://example.com/audio.wav"}
  • options - Optional transcription options (see Deepgram.Types.Listen.prerecorded_options/0)

Examples

iex> client = Deepgram.new(api_key: "your-api-key")
iex> source = %{url: "https://example.com/audio.wav"}
iex> options = %{model: "nova-2", punctuate: true}
iex> {:ok, response} = Deepgram.Listen.transcribe_url(client, source, options)
{:ok, %{metadata: %{...}, results: %{...}}}

transcribe_url_callback(client, source, callback_url, options \\ %{})

Transcribes audio from a URL with callback support (asynchronous).

Parameters

  • client - A Deepgram.Client struct
  • source - A map containing the URL: %{url: "https://example.com/audio.wav"}
  • callback_url - URL to receive the transcription result
  • options - Optional transcription options (see Deepgram.Types.Listen.prerecorded_options/0)

Examples

iex> client = Deepgram.new(api_key: "your-api-key")
iex> source = %{url: "https://example.com/audio.wav"}
iex> callback_url = "https://example.com/webhook"
iex> options = %{model: "nova-2", punctuate: true}
iex> {:ok, response} = Deepgram.Listen.transcribe_url_callback(client, source, callback_url, options)
{:ok, %{request_id: "..."}}