🎙️ Universal Video/Audio Transcriber

Transcribe any video or audio from YouTube, TikTok, Instagram, Twitter, and 1000+ sites

Powered by OpenAI · Groq · AssemblyAI · Deepgram — your choice of AI engine

LICENSE

---

✨ Why This Actor?

Feature	What You Get
🌐 1000+ platforms	YouTube, TikTok, Instagram, Twitter, Vimeo, SoundCloud, and virtually any site with video/audio
🤖 4 AI providers	OpenAI Whisper, Groq (free tier!), AssemblyAI, Deepgram — pick the best fit
💰 Free tier option	Groq offers generous free API credits — start transcribing for $0
📝 Multiple formats	JSON (full metadata), SRT (subtitles), VTT (web captions), TXT (plain text)
🌍 99+ languages	Auto-detect or specify language — from English to Japanese to Arabic
🔊 Speaker diarization	Identify who said what with AssemblyAI or Deepgram
🔄 Batch processing	Paste 1 URL or 100 — the actor handles them all with per-URL error isolation
📏 No length limits	Automatic compression + smart chunking handles hours of audio
🔗 Direct media URLs	Bypass extraction entirely for direct MP3/MP4/WAV links
🛡️ Resilient by design	Automatic retries, graceful error handling, state persistence across migrations

---

🚀 Quick Start

Option 1: On Apify (Recommended)

1. Open the Actor on Apify Console
2. Paste your URLs — YouTube, TikTok, Instagram, etc.
3. Choose a provider — OpenAI, Groq, AssemblyAI, or Deepgram
4. Enter your API key — Get one from your chosen provider
5. Click Start — Results appear in the Dataset within minutes

Option 2: Local Development

# Clone the repository
git clone https://github.com/your-username/universal-transcriber.git
cd universal-transcriber

# Install dependencies
npm install

# Set up your API key
cp .env.example .env
# Edit .env and add your API key

# Run
npm start

---

📊 Provider Comparison

Choose the provider that fits your needs:

Provider	Price/min	Best For	File Limit	Timestamps	Translation	Diarization
OpenAI	$0.006	All-around accuracy	25 MB*	✅	✅	❌
Groq	FREE tier	Speed + budget	25 MB*	✅	✅	❌
AssemblyAI	$0.0035	Long videos + accuracy	∞	✅	❌	✅
Deepgram	$0.0043	Low latency	∞	✅	❌	✅

*Files over 25 MB are automatically compressed and chunked — no manual work needed.

Available Models

Model	Provider	Highlights
whisper-1	OpenAI	Classic, reliable, all output formats
gpt-4o-transcribe	OpenAI	Newer architecture, better at context
gpt-4o-mini-transcribe	OpenAI	Cheapest OpenAI option
whisper-large-v3	Groq	High accuracy, free tier available
whisper-large-v3-turbo	Groq	Fastest option, free tier
universal-3-pro	AssemblyAI	Best overall accuracy, no file limit
universal-2	AssemblyAI	99 languages, no file limit
nova-3	Deepgram	Latest Deepgram, best accuracy
nova-2	Deepgram	Proven and stable

---

🔧 How It Works

┌─────────────────────────────────────────────────────────────────┐
│                        Input: URLs + Provider                    │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│  1. EXTRACTION (yt-dlp)                                         │
│     • Downloads audio from 1000+ platforms                      │
│     • Extracts metadata (title, duration, platform)             │
│     • Retries with exponential backoff on failure               │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│  2. COMPRESSION (ffmpeg)                                         │
│     • Converts to 16kHz mono 64kbps MP3                         │
│     • ~50 minutes of audio fits in 25 MB                        │
│     • Reduces API costs by minimizing file size                 │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│  3. CHUNKING (if needed)                                        │
│     • Silence-aware splitting at 25 MB boundaries               │
│     • Preserves word boundaries (no mid-word cuts)              │
│     • Tracks time offsets for seamless merging                  │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│  4. TRANSCRIPTION (AI Provider)                                  │
│     • Sends to OpenAI / Groq / AssemblyAI / Deepgram            │
│     • Handles provider-specific API formats                     │
│     • Merges chunks with correct time offsets                   │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│  5. OUTPUT FORMATTING                                            │
│     • JSON — Full metadata + word/segment timestamps            │
│     • SRT  — Standard subtitle format                           │
│     • VTT  — Web Video Text Tracks                              │
│     • TXT  — Clean plain text                                   │
└──────────────────────────────┬──────────────────────────────────┘
                               │
                               ▼
┌──────────────────────────────────────────────────────────────────┐
│  6. STORAGE (Apify Platform)                                     │
│     • Results → Dataset (searchable, exportable)                │
│     • Status → Key-Value Store (real-time progress)             │
│     • Per-URL error isolation (one failure ≠ batch failure)     │
└──────────────────────────────────────────────────────────────────┘

---

🌐 YouTube Extraction

This actor automatically uses Apify residential proxy for YouTube extraction to bypass bot detection. No manual proxy configuration is needed — it's enabled by default in the actor input.

---

📥 Input

Basic Usage

{
  "urls": [
    { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" },
    { "url": "https://www.tiktok.com/@user/video/1234567890" }
  ],
  "provider": "openai",
  "model": "whisper-1",
  "openaiApiKey": "sk-...",
  "outputFormats": ["json", "srt"]
}

Full Options

{
  "urls": [{ "url": "https://www.youtube.com/watch?v=..." }],
  "directMediaUrls": ["https://example.com/audio.mp3"],
  "provider": "groq",
  "model": "whisper-large-v3-turbo",
  "groqApiKey": "gsk_...",
  "outputFormats": ["json", "srt", "vtt", "txt"],
  "language": "en",
  "translateToEnglish": false,
  "prompt": "This is a technical discussion about Kubernetes and Docker.",
  "speakerDiarization": false,
  "audioFormat": "mp3",
  "maxDurationMinutes": 0,
  "debugMode": false,
  "proxyConfiguration": {
    "useApifyProxy": false
  }
}

Input Fields Reference

Field	Type	Required	Default	Description
urls	Array	✅ Yes	—	List of video/audio URLs to transcribe
directMediaUrls	Array	No	—	Direct links to media files (bypasses extraction)
provider	String	No	openai	openai, groq, assemblyai, or deepgram
model	String	No	whisper-1	Transcription model (see provider comparison)
openaiApiKey	String	*	—	Required when provider is openai
groqApiKey	String	*	—	Required when provider is groq
assemblyaiApiKey	String	*	—	Required when provider is assemblyai
deepgramApiKey	String	*	—	Required when provider is deepgram
outputFormats	Array	No	["json"]	Output formats: json, srt, vtt, txt
language	String	No	auto	ISO-639-1 code (e.g., en, id, ja)
translateToEnglish	Boolean	No	false	Translate non-English to English
prompt	String	No	—	Context prompt for better accuracy
speakerDiarization	Boolean	No	false	Identify speakers (AssemblyAI/Deepgram only)
audioFormat	String	No	mp3	Extraction format: mp3, m4a, wav, webm, flac
maxDurationMinutes	Integer	No	0	Skip videos longer than X min (0 = no limit)
debugMode	Boolean	No	false	Verbose logging for troubleshooting

---

📤 Output

Each URL produces a record in the Dataset:

{
  "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "title": "Rick Astley - Never Gonna Give You Up (Official Music Video)",
  "provider": "openai",
  "model": "whisper-1",
  "language": "en",
  "duration": 213,
  "status": "success",
  "transcript": {
    "text": "We're no strangers to love...",
    "segments": [
      {
        "start": 0.0,
        "end": 4.5,
        "text": "We're no strangers to love"
      }
    ]
  },
  "formats": {
    "json": { "..." : "..." },
    "srt": "1\n00:00:00,000 --> 00:00:04,500\nWe're no strangers to love\n\n...",
    "txt": "We're no strangers to love..."
  },
  "metadata": {
    "platform": "youtube",
    "extractionTime": 3.2,
    "compressionRatio": 0.85,
    "totalChunks": 1
  },
  "error": null
}

Output Formats

JSON — Full structured data with timestamps, confidence scores, and segments:

{
  "text": "Full transcription text...",
  "segments": [
    { "start": 0.0, "end": 4.5, "text": "First segment..." },
    { "start": 4.5, "end": 8.2, "text": "Second segment..." }
  ]
}

SRT — Standard subtitle format for video players:

1
00:00:00,000 --> 00:00:04,500
We're no strangers to love

2
00:00:04,500 --> 00:00:08,200
You know the rules and so do I

VTT — Web-compatible subtitle format:

WEBVTT

00:00:00.000 --> 00:00:04.500
We're no strangers to love

00:00:04.500 --> 00:00:08.200
You know the rules and so do I

TXT — Clean plain text:

We're no strangers to love
You know the rules and so do I

---

🏗️ Architecture

src/
├── main.js           # Entry point — orchestrates the full pipeline
├── config.js         # Provider definitions, validation, constants
├── extractor.js      # yt-dlp wrapper with retry + error classification
├── processor.js      # ffmpeg compression + silence-aware chunking
├── formatter.js      # Output format converters (JSON/SRT/VTT/TXT)
├── storage.js        # Apify Dataset + KVS persistence
├── state.js          # Resumable state tracking across migrations
├── utils.js          # Retry logic, temp dirs, platform detection
└── providers/
    ├── base.js       # Abstract provider interface
    ├── openai.js     # OpenAI Whisper + GPT-4o transcription
    ├── groq.js       # Groq Whisper (OpenAI-compatible API)
    ├── assemblyai.js # AssemblyAI (URL-based, no file upload)
    ├── deepgram.js   # Deepgram (URL-based, streaming-capable)
    └── index.js      # Provider factory

Key Design Decisions

• Compression-first: Audio is compressed to 16kHz mono 64kbps before sending to APIs — this means ~50 min of audio fits in 25 MB, dramatically reducing costs
• Silence-aware chunking: When files exceed provider limits, we split at silence boundaries instead of cutting mid-sentence
• Per-URL isolation: One failed URL never aborts the entire batch — errors are captured and stored alongside successful results
• Provider abstraction: Adding a new provider requires only implementing the BaseProvider interface — no changes to the pipeline
• State persistence: Progress is saved to Apify KVS, so if the actor migrates servers mid-batch, it resumes where it left off

---

🔑 Getting API Keys

OpenAI

1. Go to platform.openai.com
2. Navigate to API Keys
3. Create a new key starting with sk-...
4. Pricing: $0.006/min (whisper-1), $0.02/min (gpt-4o-transcribe)

Groq (Recommended for Free Tier!)

1. Go to console.groq.com
2. Sign up for a free account
3. Create an API key
4. Pricing: Free tier available with generous rate limits

AssemblyAI

1. Go to assemblyai.com
2. Sign up and get your API key
3. Pricing: $0.0035/min — best value for long videos

Deepgram

1. Go to deepgram.com
2. Sign up for $200 free credit
3. Create an API key
4. Pricing: $0.0043/min

---

🛠️ Development

Prerequisites

• Node.js ≥ 20
• ffmpeg (for audio compression)
• yt-dlp (for audio extraction from URLs)

Local Setup

# Install dependencies
npm install

# Create environment file
cp .env.example .env
# Add your API key to .env

# Run
npm start

# Run tests
npm test

Adding a New Provider

1. Create src/providers/your-provider.js extending BaseProvider
2. Implement transcribe(audioBuffer, options) and get supportsTimestamps()
3. Add your provider to PROVIDERS and MODEL_TO_PROVIDER in config.js
4. Update the factory in providers/index.js

// src/providers/your-provider.js
import { BaseProvider } from './base.js';

export class YourProvider extends BaseProvider {
  constructor(apiKey) {
    super(apiKey);
    // Initialize your SDK client
  }

  async transcribe(audioBuffer, options = {}) {
    // Call your provider's API
    return { text: '...', segments: [...] };
  }

  get supportsTimestamps() {
    return true;
  }
}

---

🐳 Docker

The actor runs in a Docker container with all dependencies pre-installed:

FROM apify/actor-node:22-alpine

# Install ffmpeg + yt-dlp
RUN apk add --no-cache ffmpeg curl \
    && curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp \
       -o /usr/local/bin/yt-dlp \
    && chmod +x /usr/local/bin/yt-dlp

# Install Node.js dependencies
COPY package*.json ./
RUN npm install --omit=dev

# Copy source code
COPY . ./

Build and run locally:

docker build -t universal-transcriber .
docker run --env-file .env universal-transcriber

---

📋 Supported Platforms

yt-dlp supports 1000+ sites. Here are the most popular:

Platform	Status	Notes
YouTube	✅	Videos, Shorts, Playlists
TikTok	✅	Public videos
Instagram	✅	Reels, Posts, Stories
Twitter/X	✅	Public tweets with video
Facebook	✅	Public videos
Vimeo	✅	All videos
SoundCloud	✅	Tracks, playlists
Twitch	✅	VODs, clips
Reddit	✅	Video posts
Dailymotion	✅	All videos
LinkedIn	✅	Public videos
Direct URLs	✅	MP3, MP4, WAV, M4A, WEBM, OGG, FLAC
...and 990+ more	✅	See yt-dlp supported sites

---

❓ FAQ

Q: How much does it cost? A: Depends on the provider. Groq offers a free tier. OpenAI charges $0.006/min. For a 1-hour video, expect ~$0.36 with OpenAI or $0 with Groq's free tier.

Q: How long does transcription take? A: Extraction + compression typically takes 1-3 minutes. API transcription is usually 10-30% of the audio duration. A 10-minute video is typically done in under 5 minutes total.

Q: Can I transcribe private/unlisted videos? A: Yes, if you provide a proxy configuration or the platform allows access via the URL alone. For geo-restricted content, use the proxy settings.

Q: What about very long videos (2+ hours)? A: The actor automatically compresses and chunks long audio. AssemblyAI and Deepgram have no file size limits, making them ideal for very long content.

Q: Can I translate non-English audio to English? A: Yes! Enable translateToEnglish with OpenAI whisper-1 or Groq whisper-large-v3.

Q: How do I identify different speakers? A: Enable speakerDiarization with AssemblyAI or Deepgram. This adds speaker labels (SPEAKER 1, SPEAKER 2, etc.) to the output.

Q: Can I run this locally without Apify? A: Yes! Install ffmpeg and yt-dlp, set your API key in .env, and run npm start.

---

🤝 Contributing

Contributions are welcome! Here's how:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

🙏 Acknowledgments

• yt-dlp — The incredible media downloader powering extraction
• ffmpeg — The Swiss army knife for audio processing
• Apify — The platform that makes deployment effortless
• OpenAI, Groq, AssemblyAI, Deepgram — The AI engines making transcription possible

---

⭐ Star this repo if you find it useful!

Made with ❤️ for the transcription community