🎵 Pyscribe

A robust tool to transcribe audio (including music) files and URLs using ElevenLabs Scribe AI model.

📋 Requirements

• 64-bit operating system
• Python 3.8+ if not using standalone binary
• ElevenLabs API key (instructions below)

🚀 Installation

Prebuilt standalone binary (Windows, macOS, Linux)

Download a standalone binary from the latest release. Comes with keyring support.

Install from PyPI

If you don't want to enter your API key every time, the optional keyring dependency allows Pyscribe to securely store it in your system's credential store.

# Recommended: Installation with keyring support
pip install "pyscribest[keyring]"
# Minimal installation without keyring support
pip install pyscribest

Run the tool without installation using uv¹

# With keyring support
uvx "pyscribest[keyring]" "path/or/url.mp3"
# Without keyring support
uvx pyscribest "path/or/url.mp3"

pyscribe was taken 🥹

⚡ Usage

Important

API Key Configuration

Log in to your ElevenLabs dashboard and create an API key with access to Speech to Text endpoint.

The script looks for the API key in the following order:

1. Environment Variable: Looks for the ELEVENLABS_API_KEY environment variable.
2. System Credential Store: Automatically saved to by the other methods if keyring is installed.
3. Terminal Prompt: If terminal is detected, prompt user for the key without displaying it.
4. Standard Input: Read one line from sys.stdin.

Basic Transcription

pyscribe "https://storage.googleapis.com/eleven-public-cdn/audio/marketing/nicole.mp3"

In the spirit of Unix philosophy only successful transcription prints to sys.stdout. Everything else is written to sys.stderr.
Use your shell's output redirection operator to write transcription to disk.

pyscribe "Never Gonna Give You Up.webm" > lyrics.txt

Note

python -m pyscribe is available as an alternative if installed via pip.

The pyscribest entrypoint is intended to avoid typing uvx --from pyscribest pyscribe.

CLI Options

• --full: Insert audio event tags like [laughter].
• --lang: An ISO-639-1 or ISO-639-3 language code² for improved performance, e.g. de or deu for German.
• --no-keyring: Avoid reading or writing key to the system keyring.
• -v, --verbose: Show diagnostic messages.
• -V, --version: Print program's version and exit.

pyscribe --lang deu --full recording.wav -v

🛠️ Integration

The pyscribe package provides both synchronous and asynchronous interfaces for seamless integration into any project.

Sync

from elevenlabs import ElevenLabs
from pyscribe import transcribe

client = ElevenLabs(api_key="YOUR API KEY")
text = transcribe(client, "path/or/url.mp3")
print(text)

Async

from elevenlabs import AsyncElevenLabs
from pyscribe import atranscribe

client = AsyncElevenLabs(api_key="YOUR API KEY")
text = await atranscribe(client, "path/or/url.mp3")
print(text)

Tip

The elevenlabs SDK is included as a dependency; no separate installation is required.

🛑 API Limitations

Concurrency

ElevenLabs imposes limitations on concurrent Speech to Text requests.
For example, the free plan only allows 8 transcription requests at the same time.

File Size

ElevenLabs also imposes different file size limits:

• Local files — up to 3 GB³
• Remote HTTPS files — up to 2 GB⁴

Features

Pyscribe focuses on end users and aims to provide a simple interface for the Scribe model.
As such, this tool does not implement all Scribe features, including but not limited to:

• Webhook support
• Word-level timestamps
• Speaker diarization
• Output in other formats

Footnotes

1. Documentation for uvx ↩

2. Supported Languages ↩

3. file Parameter Description ↩

4. cloud_storage_url Parameter Description ↩