🎙️ telnyx-transcribe 🎙️

Stop manually transcribing calls. Start automating everything.

The ultimate call-and-transcribe toolkit. It dials your list, plays your audio, records everything, and transcribes it all using OpenAI Whisper — automatically.

  •  

🧭 Quick Navigation

⚡ Get Started • ✨ Key Features • 🎮 Usage & Examples • ⚙️ Configuration • 🆚 Why This Slaps

---

telnyx-transcribe is the automated phone assistant your workflow has been missing. Stop manually calling people, recording conversations, and typing out transcripts. This tool does it all — dials your list, plays your audio message, records the responses, and delivers beautiful transcriptions using OpenAI's Whisper, the most accurate speech-to-text model available.

📞 Bulk Calling Dial hundreds in parallel

🔊 Auto Playback Play your audio message

🎙️ Smart Recording Capture every response

🧠 Whisper Transcription State-of-the-art accuracy

How it slaps:

• You: telnyx-transcribe call numbers.txt
• Tool: Dials all numbers, plays audio, records, transcribes.
• You: Check results.tsv for all transcriptions.
• Result: Hours of work done in minutes. Go grab a coffee. ☕

---

💥 Why This Slaps Other Methods

Manually managing calls and transcriptions is a vibe-killer. telnyx-transcribe makes other methods look ancient.

❌ The Old Way (Pain)	✅ The telnyx-transcribe Way (Glory)
Manually dial each number. Play your message, wait for response. Fumble with recording software. Upload recordings somewhere. Manually transcribe or use slow tools. Copy results into a spreadsheet.	telnyx-transcribe call numbers.txt Wait for completion notification. Open results.tsv. All transcriptions, ready to go. Go do something actually important. 🚀

We're not just making calls. We're building a fully automated pipeline with concurrent call handling, automatic webhook processing, intelligent retry logic, and state-of-the-art transcription that handles accents, background noise, and multiple languages like a champ.

---

🚀 Get Started in 60 Seconds

The telnyx-transcribe command (or just tt) will be available in your terminal after installation.

Method	Command
pip	pip install telnyx-transcribe
pipx	pipx install telnyx-transcribe
From source	pip install -e .

Using pip (Recommended)

# Install the package
pip install telnyx-transcribe

# Verify installation
telnyx-transcribe --version

Using pipx (Isolated Environment)

# Install pipx if you don't have it
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install telnyx-transcribe
pipx install telnyx-transcribe

From Source

# Clone the repo
git clone https://github.com/yigitkonur/telnyx-transcribe.git
cd telnyx-transcribe

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e ".[dev]"

✨ Pro Tip: Use tt as a shorthand for telnyx-transcribe — both commands work!

---

🎮 Usage: Fire and Forget

The workflow is dead simple.

📞 Make Calls & Transcribe

1. Create your numbers file (one E.164 number per line):

+14155551234
+14155551235
+14155551236

2. Run the command:

telnyx-transcribe call numbers.txt

3. Check your results:

cat results.tsv

That's it. All calls made, recorded, and transcribed.

🎧 Standalone Transcription

Already have audio files? Transcribe them directly without making calls:

# Transcribe a single file
telnyx-transcribe transcribe recording.mp3

# Transcribe all files in a directory
telnyx-transcribe transcribe ./recordings/

# With language hint for better accuracy
telnyx-transcribe transcribe ./recordings/ --language en

Supported formats: MP3, MP4, WAV, M4A, WEBM, OGG, FLAC, MPEG, MPGA

🌐 Run Webhook Server Only

Need just the webhook server for incoming Telnyx events?

# Start server on default port (5000)
telnyx-transcribe server

# Custom port and host
telnyx-transcribe server --port 8080 --host 0.0.0.0

✅ Validate Configuration

Check if everything is set up correctly before running:

telnyx-transcribe validate

---

✨ Feature Breakdown: The Secret Sauce

Feature	What It Does	Why You Care
📞 Bulk Calling Concurrent dialing	Dials multiple numbers in parallel using thread pool	Process hundreds of calls in the time of one
🔊 Auto Playback Custom audio	Plays your audio file when call is answered	Deliver consistent messages every time
🎙️ Smart Recording Automatic capture	Starts recording immediately on answer	Never miss a response
🧠 Whisper AI State-of-the-art STT	Uses OpenAI's Whisper for transcription	Handles accents, noise, multiple languages
🔄 Auto Retry Exponential backoff	Automatically retries failed API calls	Resilient to network hiccups
📊 TSV Output Ready for analysis	Structured output with all call details	Import directly into Excel, Sheets, or scripts
🌐 Webhook Server Flask-powered	Handles Telnyx events in real-time	Seamless integration with Telnyx platform
⚙️ ENV Config Zero hardcoding	All secrets via environment variables	Secure, 12-factor app compliant

---

⚙️ Configuration

All configuration is done via environment variables. Create a .env file or export them directly.

Required Variables

# Telnyx API credentials
TELNYX_API_KEY=your_telnyx_api_key
TELNYX_CONNECTION_ID=your_connection_id
TELNYX_FROM_NUMBER=+1234567890

# OpenAI API key for Whisper
OPENAI_API_KEY=your_openai_api_key

# Audio file to play during calls
AUDIO_URL=https://example.com/your-message.mp3

Optional Variables

# Server settings
WEBHOOK_HOST=0.0.0.0       # Default: 0.0.0.0
WEBHOOK_PORT=5000          # Default: 5000

# Output settings
OUTPUT_FILE=results.tsv    # Default: results.tsv

# Performance tuning
MAX_WORKERS=5              # Default: 5 concurrent calls
MAX_RETRIES=10             # Default: 10 retries
RETRY_DELAY=2.0            # Default: 2 seconds base delay

# Recording settings
RECORDING_FORMAT=mp3       # Default: mp3
RECORDING_CHANNELS=single  # Default: single

Quick Setup

# Copy the example env file
cp .env.example .env

# Edit with your credentials
nano .env

# Validate configuration
telnyx-transcribe validate

---

🔑 API Key Setup Guides

📞 Telnyx API — Pay-as-you-go calling

What you get

• Programmable voice API for making/receiving calls
• Call control, recording, and webhook events

Setup Steps

1. Go to portal.telnyx.com
2. Sign up and verify your account
3. Create a Call Control Application:
   • Navigate to "Call Control" → "Applications"
   • Create new application
   • Set your webhook URL (e.g., https://your-server.com/webhook)
4. Get a phone number:
   • Navigate to "Numbers" → "Buy Numbers"
   • Purchase a number with voice capability
   • Assign it to your Call Control application
5. Get your credentials:
   • API Key: "API Keys" section
   • Connection ID: Your Call Control application's connection ID
   • From Number: The number you purchased

Add to .env:

TELNYX_API_KEY=KEY0123456789...
TELNYX_CONNECTION_ID=1234567890
TELNYX_FROM_NUMBER=+14155551234

🧠 OpenAI API — Whisper transcription

What you get

• Access to Whisper speech-to-text model
• State-of-the-art transcription accuracy
• Multi-language support

Setup Steps

1. Go to platform.openai.com
2. Sign up or log in
3. Navigate to API Keys
4. Click "Create new secret key"
5. Copy the key (starts with sk-)

Add to .env:

OPENAI_API_KEY=sk-...

Pricing

• Whisper API: $0.006 per minute of audio
• A 5-minute recording costs ~$0.03

---

🏗️ Project Structure

telnyx-transcribe/
├── src/telnyx_transcribe/
│   ├── cli.py               # Typer CLI commands
│   ├── app.py               # Flask application factory
│   ├── config.py            # Settings management
│   ├── models.py            # Data models (Call, TranscriptionResult)
│   ├── exceptions.py        # Custom exceptions
│   ├── services/
│   │   ├── call_service.py          # Telnyx call management
│   │   ├── transcription_service.py # OpenAI Whisper integration
│   │   └── output_service.py        # TSV/CSV output handling
│   ├── webhooks/
│   │   └── handlers.py      # Telnyx webhook processing
│   └── utils/
│       ├── logging.py       # Logging configuration
│       └── console.py       # Rich console output
├── tests/                   # Test suite
├── pyproject.toml          # Project configuration
├── requirements.txt        # Dependencies
├── .env.example            # Example environment file
└── README.md               # This file

---

🛠️ For Developers & Tinkerers

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=telnyx_transcribe

# Type checking
mypy src/

# Linting
ruff check src/

Using as a Library

from telnyx_transcribe import Settings
from telnyx_transcribe.services import CallService, TranscriptionService

# Configure settings
settings = Settings(
    telnyx_api_key="your_key",
    openai_api_key="your_key",
    # ... other settings
)

# Use services directly
call_service = CallService(settings)
call = call_service.initiate_call("+14155551234")

transcription_service = TranscriptionService(settings)
result = transcription_service.transcribe_file("recording.mp3")
print(result.text)

---

🔥 Common Issues & Quick Fixes

Expand for troubleshooting tips

Problem	Solution
command not found: telnyx-transcribe	Restart your terminal or run pip install --upgrade telnyx-transcribe
TELNYX_API_KEY is required	Create a .env file with your credentials. Run telnyx-transcribe validate to check.
Webhook events not received	Ensure your webhook URL is publicly accessible. Use ngrok for local testing: ngrok http 5000
Transcription fails	Check your OPENAI_API_KEY is valid and has credits. Verify audio format is supported.
Calls not connecting	Verify TELNYX_FROM_NUMBER is assigned to your Call Control application. Check number format (E.164).
Recording URL not available	Telnyx needs time to process recordings. The webhook handles this automatically with retries.

Debugging tips:

# Run with verbose logging
telnyx-transcribe --verbose call numbers.txt

# Check your configuration
telnyx-transcribe validate

# Test webhook server locally
telnyx-transcribe server --port 5000
# Then use ngrok: ngrok http 5000

---

📜 Backstory

This project started from a simple need — automate phone-based surveys and transcribe the responses. What began as a quick script evolved into a full-featured, production-ready tool.

https://twitter.com/yigitkonur/status/1654827917845860353

---

📄 License

MIT © Yiğit Konur

---

Built with 🔥 because manually transcribing phone calls is a soul-crushing waste of time.

Report Bug • Request Feature • Contribute