@illyism/transcribe

Transcribe audio/video files to SRT subtitles in one command. Optimized for large files (2-4GB videos).

Quick Start

# 1. Try it instantly (no install needed)
npx @illyism/transcribe video.mp4

# 2. Set your OpenAI API key (one-time setup)
export OPENAI_API_KEY=sk-...

# 3. Transcribe anything
npx @illyism/transcribe video.mp4
npx @illyism/transcribe https://www.youtube.com/watch?v=VIDEO_ID

That's it! Get your free API key here and start transcribing.

Why Use This Instead of Whisper CLI?

While OpenAI's Whisper has multiple ways to use it, this tool provides a simpler, more convenient experience:

| Feature | @illyism/transcribe | Official Whisper CLI | Local Whisper (whisper.cpp) | |---------|---------------------|---------------------|----------------------------| | Setup | Zero setup with npx/bunx | Install Python package | Download models (~1-5GB) | | Video Support | ✅ Automatic with FFmpeg | ❌ Audio only | ❌ Audio only | | YouTube Support | ✅ Built-in | ❌ Manual download | ❌ Manual download | | SRT Output | ✅ Built-in | ❌ Manual formatting | ✅ Available | | Processing | ☁️ Cloud (fast) | ☁️ Cloud (fast) | 💻 Local (slower) | | Cost | $0.006/min | $0.006/min | Free (after setup) | | Internet Required | ✅ Yes | ✅ Yes | ❌ No | | Best For | Quick tasks, videos, YouTube | API integration | Privacy, offline use |

Key Advantages

• 🎬 Handles videos directly - No need to manually extract audio
• 🎥 YouTube support - Transcribe YouTube videos with just the URL
• 📝 SRT format ready - Generates subtitles automatically
• 🚀 Zero installation - Just run npx @illyism/transcribe video.mp4
• 🔧 Simple config - One-time API key setup
• 🌐 Cross-platform - Works on macOS, Linux, Windows

Perfect for: Content creators, podcasters, and developers who need quick, accurate transcriptions with minimal setup.

Real-World Use Case

Got a 30-60 minute video that's 2-4GB? Other tools like Descript upload the entire video file, which takes forever and costs more.

This tool:

1. 🎬 Extracts only the audio locally (takes seconds with FFmpeg)
2. ☁️ Uploads only ~20-40MB of audio to Whisper
3. 📝 Generates SRT subtitles

Result: 10-100x faster than uploading multi-GB video files. Same quality, fraction of the time and bandwidth.

Features

• 🎬 Video & Audio Support: Works with MP4, MP3, WAV, M4A, WebM, OGG, MOV, AVI, and MKV
• 🎥 YouTube Support: Download and transcribe YouTube videos directly
• 🎯 High Accuracy: Powered by OpenAI's Whisper API
• ⚡ Smart Optimization: Automatic 1.2x speed processing for large files (99.5% size reduction)
• 📝 SRT Format: Generates standard SRT subtitle files with precise timestamps
• 🔧 Simple Setup: Easy configuration via environment variable or config file
• 🌍 Multi-language: Automatically detects language
• 🚀 Lightning Fast: Optimized for 2-4GB video files

Installation & Setup

Option 1: Use Instantly (No Install)

npx @illyism/transcribe video.mp4

Option 2: Install Globally

npm install -g @illyism/transcribe
# or: bun install -g @illyism/transcribe

Prerequisites

# macOS
brew install ffmpeg

# Ubuntu/Debian
sudo apt-get install ffmpeg

# Windows
choco install ffmpeg

# macOS
brew install yt-dlp

# Ubuntu/Debian
sudo apt install yt-dlp

# Windows
winget install yt-dlp

# Or with pip
pip install yt-dlp

1. Go to platform.openai.com/api-keys
2. Create a new API key
3. Copy it and set it up below ⬇️

API Key Setup (30 seconds)

One-time setup - Choose your preferred method:

Method 1: Config File (Recommended)

mkdir -p ~/.transcribe && echo '{"apiKey": "sk-YOUR_KEY"}' > ~/.transcribe/config.json

Method 2: Environment Variable

export OPENAI_API_KEY=sk-YOUR_KEY

Don't have a key? Get one free here (takes 1 minute)

Usage Examples

# Local video file
transcribe video.mp4

# YouTube video
transcribe https://www.youtube.com/watch?v=VIDEO_ID

# Audio file
transcribe podcast.mp3

# Disable optimization (use original audio)
transcribe video.mp4 --raw

Outputs: Creates video.srt in the same directory.

What Happens Automatically

By default, the tool optimizes large files:

2.7GB video → Extract audio → Speed up 1.2x → Compress if needed → Upload 12MB → Transcribe → Adjust timestamps

Result:

• ⚡ 99.5% smaller uploads (2.7GB → 12.8MB)
• 🚀 10-100x faster than uploading full video
• 🎯 ~98% accuracy maintained
• 💰 Same cost ($0.006/min)

Want original audio? Add --raw flag.

Use as a Library

npm install @illyism/transcribe

import { transcribe } from '@illyism/transcribe'

const result = await transcribe({
  inputPath: 'video.mp4',
  apiKey: process.env.OPENAI_API_KEY,
  optimize: true // default, set false to disable
})

console.log(result.srtPath)  // Path to generated SRT file
console.log(result.text)     // Full transcription text

interface TranscribeOptions {
  inputPath: string        // Path to video/audio file
  apiKey?: string         // OpenAI API key (or use env var)
  outputPath?: string     // Custom output path (optional)
  optimize?: boolean      // Enable optimization (default: true)
}

interface TranscribeResult {
  srtPath: string         // Path to generated SRT file
  text: string           // Full transcription text
  language: string       // Detected language
  duration: number       // Duration in seconds
}

Details

• Video: MP4, WebM, MOV, AVI, MKV
• Audio: MP3, WAV, M4A, OGG, Opus
• YouTube: All videos, Shorts, youtu.be links

OpenAI Whisper API: $0.006 per minute

Examples:

• 5 min: $0.03
• 30 min: $0.18
• 2 hours: $0.72

1. Extract audio from video (if needed)
2. Optimize: 1.2x speed + compression if >24MB
3. Upload to Whisper API
4. Generate SRT with timestamps
5. Adjust timestamps to match original
6. Clean up temp files

1
00:00:00,000 --> 00:00:03,420
Hey and thank you for getting the SEO roast.

2
00:00:03,420 --> 00:00:06,840
I'll take a look at your website and see what things we can improve.

Troubleshooting

Set up your API key using one of the methods in API Key Setup.

Install FFmpeg:

brew install ffmpeg  # macOS
sudo apt install ffmpeg  # Ubuntu
choco install ffmpeg  # Windows

Install yt-dlp:

brew install yt-dlp  # macOS
sudo apt install yt-dlp  # Ubuntu
pip install yt-dlp  # Any platform

Use absolute paths:

transcribe /full/path/to/video.mp4

OpenAI API may be temporarily down. Wait 30 seconds and try again.

Links

• 📦 NPM Package
• 🐙 GitHub Repo
• 📚 Full Changelog
• 🧪 A/B Test Results
• 🐛 Report Issues

Contributing

Pull requests welcome! See GitHub repo.

License

MIT © Ilias Ismanalijev