🎧 Transcript Downloader - Youtube Audio Scraper Extractor & Downloader

Convert YouTube videos into downloadable audio files using the Transcript Downloader API. Ideal for podcasting, offline listening, and content repurposing. Works in bulk, with optional storage to Apify key-value store.

---

✨ Features

• 📁 Bulk processing of multiple YouTube video IDs
• 🕒 Polling logic with automatic retries
• 🧠 Progress tracking and run logs
• 🗂️ Optional Apify file storage to key-value store
• 🔐 Secure API token-based authentication

---

🔧 Input Parameters

Parameter	Type	Required	Default	Description
videoIds	array	✅ Yes	–	List of YouTube video IDs to process
apiToken	string	✅ Yes	–	Bearer token for Transcript Downloader API
downloadToApify	boolean	No	true	Whether to download audio files to Apify key-value store
maxWaitTime	number	No	10	Max time to wait for video processing (in minutes, range: 1–15)
pollingInterval	number	No	60	Interval between polling status (in seconds, range: 30–300)

📥 Example Input

{
  "videoIds": ["Fqdz6A-5d04"],
  "apiToken": "your-api-token",
  "downloadToApify": true,
  "maxWaitTime": 10,
  "pollingInterval": 60
}

---

📤 Output Format

Each video generates an output record with metadata and processing info:

{
  "videoId": "Fqdz6A-5d04",
  "id": "01JW72M0AGW3M6R3QDCS30RD2P",
  "type": "audio",
  "duration": "01:47:55",
  "cost": "1.079",
  "status": "success", // pending, success, or failed
  "created_at": "2025-01-23T00:30:50.000Z",
  "audioUrl": "https://cdn.transcriptdownloader.com/audio/abc123.mp3",
  "storedAt": "apify://key-value-store/audio-Fqdz6A-5d04" // If downloaded
}

---

🚀 How to Use

1. Get your API token from Transcript Downloader
2. Add one or more YouTube video IDs
3. Set downloadToApify to true if you want files saved
4. Run the actor and access results in the dataset or key-value store

---

❌ Error Handling

This actor includes robust handling for common issues:

Status Code	Description
403	Invalid API key – check or regenerate key
404	Video not found or has been deleted
429	Too many requests – reduce polling frequency
503	Transcript Downloader API under maintenance
Custom	"You already have a pending download for this video"

If a video is already being processed, its ID will be returned in the error message.

---

⚠️ Rate Limiting & Performance

API Rate Limits

Scope	Limit	Window
Per User (API Token)	90 requests	1 minute
Per IP (unauthenticated)	90 requests	1 minute

When rate limits are exceeded, the API returns 429 Too Many Requests. The actor handles this automatically with built-in retry logic.

Audio Download Cooldown

Endpoint	Limit	Cooldown Period	Scope
Single Audio Download	1 request	5 minutes	Per video

If you request audio for the same video within the 5-minute cooldown, the API returns 429 with a "Download again in X minute(s)" message. The actor handles duplicate requests gracefully.

Processing Times

Scenario	Typical Duration	Maximum Wait
Short videos (< 10 min)	10-30 seconds	15 minutes
Medium videos (10-60 min)	30 seconds - 2 minutes	15 minutes
Long videos (60+ min)	2-5 minutes	15 minutes

Retry Behavior

The actor automatically retries on transient errors (429, 500, 503) with exponential backoff (base delay 1s, max delay 60s, up to 5 attempts). It does not retry on client errors (401, 403, 404) since those require user action.

Response Headers

The API returns rate limit headers you can monitor in logs:

Header	Description
X-RateLimit-Limit	Max requests allowed in window
X-RateLimit-Remaining	Requests remaining in current window
Retry-After	Seconds to wait before retrying (on 429)

---

💡 Best Practices

• ✅ Respect rate limits to avoid 429 errors
• ⏳ Use polling wisely — longer intervals for large queues
• ⏳ Avoid re-requesting the same video within the 5-minute cooldown
• 🔐 Keep your apiToken secret (never log it)
• 🧠 Monitor output for incomplete or failed downloads
• 🗂️ Store large audio files in Apify only when needed

---

📈 Monitoring

Track performance and usage with Apify tools:

• Run history
• Success/failure rates
• Storage and resource usage
• Output file availability

---

💳 Pricing & Billing

The Transcript Downloader API used by this actor requires a valid API token. API usage is billed separately and is based on processing time and file size.

📊 We charge per minute of audio. Visit our site to checkout pricing. View full details and subscription plans on our pricing page

---

🙋 Support

Need help? Visit Transcript Downloader Support. We respond within 24 business hours.

---

📄 License

This actor is provided under the ISC License.