Deepgram.Listen (Deepgram v0.1.0)
View SourceSpeech-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.
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
@spec live_transcription(Deepgram.Client.t(), Deepgram.Types.Listen.live_options()) :: {:ok, pid()} | {:error, any()}
Starts a live transcription WebSocket connection.
Parameters
client
- ADeepgram.Client
structoptions
- Optional live transcription options (similar toDeepgram.Types.Listen.prerecorded_options/0
)
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<...>}
@spec transcribe_file( Deepgram.Client.t(), binary(), Deepgram.Types.Listen.prerecorded_options() ) :: {:ok, Deepgram.Types.Listen.transcription_response()} | {:error, any()}
Transcribes audio from a file.
Parameters
client
- ADeepgram.Client
structfile_data
- Binary data of the audio fileoptions
- Optional transcription options (seeDeepgram.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: %{...}}}
@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
- ADeepgram.Client
structfile_data
- Binary data of the audio filecallback_url
- URL to receive the transcription resultoptions
- Optional transcription options (seeDeepgram.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: "..."}}
@spec transcribe_url( Deepgram.Client.t(), Deepgram.Types.Listen.source(), Deepgram.Types.Listen.prerecorded_options() ) :: {:ok, Deepgram.Types.Listen.transcription_response()} | {:error, any()}
Transcribes audio from a URL source.
Parameters
client
- ADeepgram.Client
structsource
- A map containing the URL:%{url: "https://example.com/audio.wav"}
options
- Optional transcription options (seeDeepgram.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: %{...}}}
@spec transcribe_url_callback( Deepgram.Client.t(), Deepgram.Types.Listen.source(), String.t(), Deepgram.Types.Listen.prerecorded_options() ) :: {:ok, Deepgram.Types.Listen.async_response()} | {:error, any()}
Transcribes audio from a URL with callback support (asynchronous).
Parameters
client
- ADeepgram.Client
structsource
- A map containing the URL:%{url: "https://example.com/audio.wav"}
callback_url
- URL to receive the transcription resultoptions
- Optional transcription options (seeDeepgram.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: "..."}}