elevenlabs/skills

speech-to-text

Transcribe audio to text using ElevenLabs Scribe v3.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/elevenlabs/skills --skill speech-to-text

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

ElevenLabs Speech-to-Text

Transcribe audio to text with Scribe v3 - supports 90+ languages, speaker diarization, and word-level timestamps.

Setup, before writing any code: if ELEVENLABS_API_KEY isn't set for this project, run npx -y @elevenlabs/cli@latest onboard init from the app's folder first and follow what it prints: it signs the user in and stores a key for the project, so nobody copies one by hand. Otherwise see the Installation Guide. For JavaScript, use @elevenlabs/* packages only.

Quick Start

Python

python
from elevenlabs import ElevenLabs

client = ElevenLabs()

with open("audio.mp3", "rb") as audio_file:
    result = client.speech_to_text.convert(file=audio_file, model_id="scribe_v3")

print(result.text)

JavaScript

javascript
import { ElevenLabsClient } from "@elevenlabs/elevenlabs-js";
import { createReadStream } from "fs";

const client = new ElevenLabsClient();
const result = await client.speechToText.convert({
  file: createReadStream("audio.mp3"),
  modelId: "scribe_v3",
});
console.log(result.text);

CLI

bash
elevenlabs speech-to-text convert --file audio.mp3 --model-id scribe_v3

Models

Model IDDescriptionBest For
scribe_v3Most accurate batch model, 90+ languages; adds numbers_format and secondary_language_codesBatch transcription, subtitles, long-form and mixed-language audio
scribe_v3_liveMost accurate realtime model, with turn prediction and multilingual modeLive transcription, voice agents
scribe_v2Previous-generation batch model, 90+ languagesExisting batch integrations
scribe_v2_medicalSpecialized recognition for medical and clinical audio, 90+ languagesClinical documentation, medical dictation, patient calls
scribe_v2_realtimePrevious-generation realtime model, low latency (~150ms)Existing realtime integrations
scribe_v2_realtime_turboRealtime transcription variantLive transcription
scribe_v2_realtime_liteRealtime transcription variantLive transcription

Transcription with Timestamps

Word-level timestamps include type classification and speaker identification:

python
result = client.speech_to_text.convert(
    file=audio_file, model_id="scribe_v3", timestamps_granularity="word"
)

for word in result.words:
    print(f"{word.text}: {word.start}s - {word.end}s (type: {word.type})")

Speaker Diarization

Identify WHO said WHAT - the model labels each word with a speaker ID, useful for meetings, interviews, or any multi-speaker audio:

python
result = client.speech_to_text.convert(
    file=audio_file,
    model_id="scribe_v3",
    diarize=True
)

for word in result.words:
    print(f"[{word.speaker_id}] {word.text}")

For call recordings, the batch API can label diarized speakers as agent and customer by setting detect_speaker_roles=true alongside diarize=true. This option is not compatible with use_multi_channel=true.

If your workspace has registered speaker profiles, set use_speaker_library=true with diarize=true to match detected speakers against the speaker library.

bash
elevenlabs speech-to-text convert \
  --file call.mp3 \
  --model-id scribe_v3 \
  --diarize true \
  --detect-speaker-roles true \
  --use-speaker-library true

Multichannel Audio

Use use_multi_channel=true when each speaker is isolated on a separate audio channel. By default, the API returns one transcript per channel under transcripts; set multichannel_output_style="combined" to receive one transcript merged by timestamp, with channel_index on each word.

python
result = client.speech_to_text.convert(
    file=audio_file,
    model_id="scribe_v3",
    use_multi_channel=True,
    multichannel_output_style="combined",
)

Keyterm Prompting

Help the model recognize specific words it might otherwise mishear - product names, technical jargon, or unusual spellings (up to 100 terms):

python
result = client.speech_to_text.convert(
    file=audio_file,
    model_id="scribe_v3",
    keyterms=["ElevenLabs", "Scribe", "API"]
)

Language Detection

Automatic detection with optional language hint:

python
result = client.speech_to_text.convert(
    file=audio_file,
    model_id="scribe_v3",
    language_code="eng"  # ISO 639-1 or ISO 639-3 code
)

print(f"Detected: {result.language_code} ({result.language_probability:.0%})")

scribe_v3 also accepts secondary_language_codes for mixed-language audio (other languages expected alongside language_code) and numbers_format (digits or words) to control how numbers are written. The SDKs don't have typed arguments for these yet, so pass them through request_options:

python
result = client.speech_to_text.convert(
    file=audio_file,
    model_id="scribe_v3",
    language_code="en",
    request_options={
        "additional_body_parameters": {
            "secondary_language_codes": ["es", "fr"],
            "numbers_format": "digits",
        },
    },
)

Supported Formats

Audio: MP3, WAV, M4A, FLAC, OGG, WebM, AAC, AIFF, Opus Video: MP4, AVI, MKV, MOV, WMV, FLV, WebM, MPEG, 3GPP

Limits: Up to 5.0GB file size, 10 hours duration

Response Format

json
{
  "text": "The full transcription text",
  "language_code": "eng",
  "language_probability": 0.98,
  "words": [
    {"text": "The", "start": 0.0, "end": 0.15, "type": "word", "speaker_id": "speaker_0"},
    {"text": " ", "start": 0.15, "end": 0.16, "type": "spacing", "speaker_id": "speaker_0"}
  ]
}

Word types:

  • word - An actual spoken word
  • spacing - Whitespace between words (useful for precise timing)
  • audio_event - Non-speech sounds the model detected (laughter, applause, music, etc.)

Error Handling

python
try:
    result = client.speech_to_text.convert(file=audio_file, model_id="scribe_v3")
except Exception as e:
    print(f"Transcription failed: {e}")

Common errors:

  • 401: Invalid API key
  • 422: Invalid parameters
  • 429: Rate limit exceeded

Tracking Costs

Monitor usage via request-id response header:

python
response = client.speech_to_text.with_raw_response.convert(file=audio_file, model_id="scribe_v3")
result = response.data
print(f"Request ID: {response.headers.get('request-id')}")

Real-Time Streaming

For live transcription with ultra-low latency, use the real-time API. The real-time API produces two types of transcripts:

  • Partial transcripts: Interim results that update frequently as audio is processed - use these for live feedback (e.g., showing text as the user speaks)
  • Committed transcripts: Final, stable results after you "commit" - use these as the source of truth for your application

A "commit" tells the model to finalize the current segment. You can commit manually (e.g., when the user pauses) or use Voice Activity Detection (VAD) to auto-commit on silence.

Python (Server-Side)

python
import asyncio
from elevenlabs import CommitStrategy, ElevenLabs, RealtimeEvents, RealtimeUrlOptions

client = ElevenLabs()

async def transcribe_realtime():
    done = asyncio.Event()
    connection = await client.speech_to_text.realtime.connect(RealtimeUrlOptions(
        model_id="scribe_v3_live",
        url="https://npr-ice.streamguys1.com/live.mp3",
        commit_strategy=CommitStrategy.VAD,  # URL streams never commit on their own
        include_timestamps=True,
        keyterms=["ElevenLabs", "Scribe"],
        no_verbatim=True,
    ))

    def on_error(error):
        print(f"Error: {error}")
        done.set()

    connection.on(RealtimeEvents.PARTIAL_TRANSCRIPT, lambda data: print(f"Partial: {data.get('text', '')}"))
    connection.on(RealtimeEvents.COMMITTED_TRANSCRIPT, lambda data: print(f"Final: {data.get('text', '')}"))
    connection.on(RealtimeEvents.ERROR, on_error)
    connection.on(RealtimeEvents.CLOSE, done.set)

    try:
        await done.wait()
    finally:
        await connection.close()

asyncio.run(transcribe_realtime())

JavaScript (Client-Side with React)

typescript
import { useScribe, CommitStrategy } from "@elevenlabs/react";

function TranscriptionComponent() {
  const [transcript, setTranscript] = useState("");

  const scribe = useScribe({
    modelId: "scribe_v3_live",
    commitStrategy: CommitStrategy.VAD, // Auto-commit on silence for mic input
    keyterms: ["ElevenLabs", "Scribe"],
    noVerbatim: true,
    includeLanguageDetection: true,
    onPartialTranscript: (data) => console.log("Partial:", data.text),
    onCommittedTranscript: (data) => setTranscript((prev) => prev + data.text),
  });

  const start = async () => {
    // Get token from your backend (never expose API key to client)
    const { token } = await fetch("/scribe-token").then((r) => r.json());

    await scribe.connect({
      token,
      microphone: { echoCancellation: true, noiseSuppression: true },
    });
  };

  return <button onClick={start}>Start Recording</button>;
}

Commit Strategies

StrategyDescription
ManualYou call commit() when ready - use for file processing or when you control the audio segments
VADVoice Activity Detection auto-commits when silence is detected - use for live microphone input
Turn predictionscribe_v3_live only. Commits when the model predicts the speaker has finished their turn, with VAD as a fallback - set commit_strategy=turn_prediction on the WebSocket URL (not yet in the SDK CommitStrategy enums)

Set includeLanguageDetection: true to receive the detected language code in delayed final transcript events.

typescript
// React: set commitStrategy on the hook (recommended for mic input)
import { useScribe, CommitStrategy } from "@elevenlabs/react";

const scribe = useScribe({
  modelId: "scribe_v3_live",
  commitStrategy: CommitStrategy.VAD,
  keyterms: ["ElevenLabs", "Scribe"],
  noVerbatim: true,
  // Optional VAD tuning:
  vadSilenceThresholdSecs: 1.5,
  vadThreshold: 0.4,
});
javascript
// JavaScript client: pass vad config on connect
const connection = await client.speechToText.realtime.connect({
  modelId: "scribe_v3_live",
  keyterms: ["ElevenLabs", "Scribe"],
  noVerbatim: true,
  vad: {
    silenceThresholdSecs: 1.5,
    threshold: 0.4,
  },
});

Event Types

EventDescription
partial_transcriptLive interim results
final_transcriptStable segment result sent before the segment is committed
final_transcript_with_timestampsDelayed final result with timestamps and/or detected language
committed_transcriptFinal results after commit
committed_transcript_with_timestampsFinal with word timing
committed_transcript_entitiesEntities detected in a committed segment
edited_transcriptOriginal and edited text for a committed segment when transcript editing is enabled
invalid_requestConnection parameters were rejected and the session closes
errorError occurred

See real-time references for complete documentation.

References

from this repository

More skills

All skills
elevenlabs
Official

text-to-speech

Convert text to speech using ElevenLabs voice AI. Use when generating audio from text, creating voiceovers, building voice apps, or synthesizing speech in 90+ languages.

24h installs
329
GitHub stars
579
Updated
Nov 18
elevenlabs
Official

agents

Build voice AI agents with ElevenLabs. Use when creating voice assistants, customer service bots, interactive voice characters, or any real-time voice conversation experience, and when configuring an agent's tools, workflows, or procedures, including creating, editing, and publishing free-form and structured procedure drafts on an agent branch over the SDKs or REST API.

1h installs
20
GitHub stars
579
Updated
Nov 18
elevenlabs
Official

dubbing

Dub audio and video into other languages using the ElevenLabs Dubbing API (dubbingv2), preserving the original speakers' voices. Use when translating videos, podcasts, or recordings into other languages, localizing media content, reviewing or correcting dubbing transcripts and translations, or regenerating a dub after edits.

1h installs
20
GitHub stars
579
Updated
Nov 18
elevenlabs
Official

onboarding

Add ElevenLabs to a project from scratch. Use when the user wants to start using ElevenLabs, add text to speech, speech to text, voice agents, real-time voice for their own agent runtime (Speech Engine), sound effects, music, voice changing, voice isolation, or dubbing to their app, or get set up with an ElevenLabs account or API key for the first time. Handles sign-in, API key creation, SDK install and a test request end to end; the user leaves the conversation once, to approve a browser page.

1h installs
20
GitHub stars
579
Updated
Nov 18