📝 Transcript Downloader - YouTube Transcript & Metadata Scraper Extractor

This Apify actor fetches full transcripts, timestamps, video metadata, and optionally comments from public YouTube videos using the Transcript Downloader API. Ideal for content repurposing, accessibility, SEO enrichment, or video analysis at scale.

---

✨ Features

• 🔁 Batch processing: Handle multiple YouTube videos at once
• 🌍 Language support: Use ISO codes or auto for detection
• 💬 Comment extraction: Fetch most relevant and most recent comments
• 📊 Metadata included: Title, description, view count, likes, channel info, etc.
• ⚙️ Concurrency control: Adjust maxConcurrency for optimized performance
• 🔄 Automatic retries: Handles API errors and retryable failures
• 🧠 Error tracking: All failures logged in output

---

🔧 Input Parameters

The actor accepts the following input:

Parameter	Type	Required	Default	Description
videoIds	array	✅ Yes	-	List of YouTube video IDs (11 characters each)
apiToken	string	✅ Yes	-	Your Transcript Downloader API bearer token
language	string	No	auto	ISO language code for transcript (e.g., en, es, fr)
includeComments	boolean	No	false	Whether to fetch video comments
maxConcurrency	number	No	5	Max concurrent requests (range: 1-10)

📥 Sample Input

{
  "videoIds": ["dQw4w9WgXcQ", "jNQXAC9IVRw"],
  "apiToken": "your-api-token",
  "language": "en",
  "includeComments": true,
  "maxConcurrency": 5
}

---

📤 Output Format

Each video will produce a dataset item with the following structure:

{
  "videoId": "dQw4w9WgXcQ",
  "videoMetadata": {
    "title": "Example Title",
    "description": "Video description...",
    "publishedAt": "2023-08-20T15:32:00Z",
    "duration": "5:12",
    "viewCount": 120456,
    "likeCount": 3456,
    "commentCount": 123,
    "channelName": "Channel Name",
    "channelUrl": "https://www.youtube.com/channel/abc123"
  },
  "transcriptsWithTimeStamps": [
    {
      "dur": "3.5",
      "text": "Welcome to this tutorial...",
      "start": "0.0"
    }
  ],
  "fullTranscript": "Welcome to this tutorial...",
  "comments": {
    "mostRelevant": [
      {
        "author": "User123",
        "text": "This helped me so much!"
      }
    ],
    "mostRecent": [
      {
        "author": "User456",
        "text": "Just watched it!"
      }
    ]
  },
  "downloadInfo": {
    "id": "123DDJNRUND",
    "youtube_video_id": "dQw4w9WgXcQ",
    "type": "captions",
    "cost": "1.600",
    "status": "success",
    "created_at": "2025-06-16T21:34:43.000Z"
  }
}

---

🚀 How to Use

1. Get your API token from Transcript Downloader
2. Open the actor in the Apify Console
3. Add YouTube video IDs and required input
4. Run the actor and access results in the dataset

---

❌ Error Handling

The actor gracefully handles common API errors:

Status Code	Meaning
401	Insufficient credits
403	Invalid API token
404	Video or transcript not found
429	Rate limit exceeded
503	Service temporarily unavailable

Failed attempts are captured in the dataset with error info.

---

❓ Common Issues

Transcript did not appear in the metadata

• If the channel's title is in a different language than the actual content, sometimes the auto language detection does not work.
• ✅ Try setting the language parameter explicitly to the language being spoken.
• ⚠️ Also note: some videos may not have a native transcript available at all.

---

⚠️ 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.

Transcript Download Cooldown

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

If you request a transcript for the same video within the 5-minute cooldown, the API returns 429 with a "Download again in X minute(s)" message. For batch processing of unique videos, this does not apply.

YouTube API Quotas

Video metadata requests consume YouTube API quota (1 unit per video). Daily quota resets at midnight UTC. When quota is exhausted, the API returns a 429 error until reset.

Retry Behavior

The actor automatically retries on transient errors (429, 500, 503) with exponential backoff (base delay 1s, max delay 60s, up to 3 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)

Other Limitations

• 📼 YouTube video IDs must be exactly 11 characters
• ⚙️ maxConcurrency must be 1–10

---

🧪 Example Run

{
  "videoIds": ["AyOjAEn36b8"],
  "apiToken": "your-api-token",
  "language": "auto",
  "includeComments": false
}

---

💳 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 on a per transcript/metadata basis. 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 project is licensed under the ISC License.