Video Captions Downloader

Video Captions Downloader requests source-provided subtitle files for one video URL and converts usable tracks to SRT. Each successful file conversion becomes an 11-field Dataset row with a time-range-to-text map, video metadata, language label, and signed SRT record URL.

• Submit one non-empty video URL; source compatibility is tested at run time.
• Choose one or more of 54 named language patterns, select all, or omit languages for English.
• Receive one row per subtitle file that completes conversion—not one guaranteed row per selected language.
• Expect source failures, duplicate language variants, or even a billed Subtitles event with zero Dataset rows.

Run Video Captions Downloader, use the Apify API, or connect through MCP. The Actor retrieves existing manual or source-generated tracks; it does not transcribe audio, translate text, certify accuracy, or grant reuse rights.

Why Choose This API

This Actor packages a narrow subtitle-file workflow into a reviewable Apify run. It passes one URL and language patterns to the installed source extractor, asks for both manually supplied and source-generated subtitle tracks, skips video download, converts available files to SRT when needed, parses SRT blocks into a JSON object, and stores successfully converted SRT files in the run key-value store.

The output contract is compact. Every written row has the same 11 top-level keys: processor, processed_at, thumbnail, platform, title, description, published_at, author, language, subtitle, and srt_url. Video-level metadata is repeated for each converted subtitle file. This repetition makes each row usable on its own but means consumers should not sum video metadata across rows.

The API avoids promises that the source cannot support. The underlying extractor includes many site extractors and a generic path, but its own supported-sites documentation warns that listed sites are not guaranteed to work because websites change. Caption tracks also vary by video, account state, region, source rate limits, and language naming. The only reliable compatibility test is a real run against the exact URL.

There is no automatic speech-recognition fallback in this runtime. The option often called “automatic subtitles” means captions generated and exposed by the source platform. If a video exposes neither manual nor source-generated captions, this Actor does not synthesize a transcript from audio.

Quick Start Guide

Provide video_url. languages is optional at runtime and defaults to English. Start with one named language before asking for all, because a broad request can retrieve several variants and can include source-specific tracks that do not convert cleanly.

{
  "video_url": "https://www.youtube.com/shorts/noWlKvEPOWk",
  "languages": ["english"]
}

After completion, inspect three surfaces together: the terminal run status, charged-event counts, and Dataset item count. A process can finish while returning no rows. In a verified historical run, the example URL produced two English variants—en-orig and en—with 29 timecode entries each. In a later run against the same URL, the Subtitles event was charged but conversion produced no Dataset rows. Source availability is therefore part of the product contract, not an edge case hidden from users.

If a row exists, open srt_url promptly and confirm the subtitle map. If no row exists, do not assume the video has no captions; retry later, inspect the live source, and check whether the selected language label matches an exposed track.

Input Parameters

Field	Type	Required	Behavior
video_url	string	Yes	One non-empty source URL. No fixed platform allowlist is enforced by input validation.
languages	array of enum strings	No	Defaults to english; empty arrays and unknown values are rejected.

The selector contains all plus 54 named choices: Afrikaans, Arabic, Armenian, Belarusian, Bengali, Bulgarian, Cantonese, Catalan, two Chinese variants, Croatian, Czech, Danish, Dutch, English, Esperanto, Estonian, Filipino, Finnish, French, German, Greek, Gujarati, Hebrew, Hindi, Hungarian, Icelandic, Indonesian, Italian, Japanese, Korean, Latvian, Lithuanian, Malay, Marathi, Norwegian, Persian, Polish, Portuguese, Romanian, Russian, Serbian, Slovak, Slovenian, Spanish, Swahili, Swedish, Tamil, Telugu, Thai, Turkish, Ukrainian, Urdu, and Vietnamese.

Each choice maps to a language-code regular expression, such as en.* for English. Multiple names resolving to the same pattern are deduplicated by runtime validation. all is passed to the extractor as a broad request. It means all tracks the source/extractor elects to expose, not all human languages and not a guarantee that every downloaded file will become a row.

The Actor has no public cookie, account, proxy, format, translation, ASR, or output-file input. Private, login-gated, removed, geoblocked, rate-limited, or changed source URLs can fail even when the site has an extractor.

Output Data Schema

Field	Meaning	Important boundary
processor	Actor URL	Processing provenance.
processed_at	ISO timestamp	Metadata-formatting time, not subtitle publication time.
thumbnail	Source thumbnail URL	Can expire or be absent.
platform	Extractor label	Not a guaranteed canonical platform taxonomy.
title	Source-reported title	Nullable and changeable.
description	Source video description	Not the subtitle or an accuracy judgment.
published_at	Parsed source timestamp	Null when unavailable or invalid.
author	Source uploader value	Not verified identity or ownership.
language	Filename-suffix display name	Variants such as en and en-orig can create separate rows.
subtitle	SRT time-range → text object	Duplicate identical time-range keys overwrite earlier text.
srt_url	Signed KVS record URL	Empty if storage fails; access depends on the stored record and URL lifecycle.

{
  "processor": "https://apify.com/agentx/video-captions-downloader",
  "processed_at": "2026-07-23T11:57:47+00:00",
  "thumbnail": "https://example.com/source-thumbnail.jpg",
  "platform": "Youtube",
  "title": "Example source video",
  "description": "Source-provided description",
  "published_at": "2026-07-01T12:00:00+00:00",
  "author": "Example channel",
  "language": "ENGLISH",
  "subtitle": {
    "00:00:00,000 --> 00:00:02,000": "Example caption text"
  },
  "srt_url": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/en.srt?signature=SIGNED_VALUE"
}

The example shows the complete 11-key envelope with illustrative source values. It does not promise that a particular video yields one English row, that captions are human-authored, or that the text is accurate. SRT parsing joins multiline content with spaces and uses each time-range line as an object key rather than returning an ordered segment array.

Integration Examples

Use agentx/video-captions-downloader through REST, an Apify client, schedules, webhooks, or an MCP-capable workflow. Keep the input small and preserve the run ID so Dataset, KVS, logs, and charge events can be reconciled.

{
  "method": "POST",
  "url": "https://api.apify.com/v2/acts/agentx~video-captions-downloader/runs?waitForFinish=240",
  "headers": {
    "Authorization": "Bearer YOUR_APIFY_TOKEN",
    "Content-Type": "application/json"
  },
  "body": {
    "video_url": "https://www.youtube.com/shorts/noWlKvEPOWk",
    "languages": ["english"]
  }
}

When the run finishes, fetch items from defaultDatasetId and list records from defaultKeyValueStoreId. Do not treat a successful terminal state as proof that subtitle text exists. Require itemCount > 0, check that each subtitle object is non-empty, and verify the SRT record before forwarding it.

MCP clients should fetch current Actor details first. If an MCP plan cannot execute a public Actor, use the authenticated REST API for the exact build and use MCP for independent run, Dataset, and KVS readback. Keep API tokens in a secret manager.

Pricing & Cost Calculator

The local pay-per-event schedule defines Actor Usage at $0.00001 per metered unit, Actor Start at $0.01 with a minimum of one start event, and a one-time Subtitles event at $0.48.

Subtitles is not a per-row or per-language charge. Runtime requests it once after at least one subtitle-related file is present, before each file is converted and pushed. One charged event can therefore lead to multiple language/variant rows, one row, or zero rows. If no subtitle-related file is detected at all, the run exits before that event, although start and usage can still apply.

Planning examples: one run that reaches the Subtitles event starts at $0.49 before metered usage; ten separate qualifying runs start at $4.90; one run that writes two English variants still has one Subtitles event. Active Apify pricing at execution controls billing, especially when a host-managed Store snapshot lags behind a new build.

Set maxTotalChargeUsd as a financial guard and inspect charged events afterward. A cap does not improve source availability, limit how many subtitle files all requests, or guarantee Dataset output.

Use Cases & Applications

Localization teams can obtain available source captions as SRT inputs for a separate translation and review workflow. The Actor does not translate, so target-language generation, terminology control, timing adjustments, and native-speaker QA stay downstream.

Researchers can build timecoded text observations from videos that expose captions. Retain the video URL outside the Dataset if required, because the 11-field row does not include the original input URL. Preserve run provenance, assess caption-generation method, and avoid presenting source-generated captions as ground truth.

Editors and content operations teams can inspect a current caption file, search a time-range map, or compare source variants. An en-orig row and an en row may contain the same text or different source transformations; compare them rather than assuming one is superior.

Accessibility workflows can use the output as a starting artifact, never an automatic compliance verdict. Accuracy, speaker identification, sound cues, reading speed, timing, punctuation, and completeness require qualified review.

FAQ

Does this transcribe speech when captions are missing? No. writeautomaticsub requests captions generated by the source platform. The runtime never downloads audio for local ASR.

How many platforms are guaranteed? None by a fixed number. Compatibility follows the installed extractor and current sites. The yt-dlp supported-sites list explicitly warns that listed sites can break.

Why did English create two rows? The en.* pattern can match en and en-orig. Each downloaded file that converts successfully is processed independently.

Can a charged run return zero rows? Yes. The Subtitles event occurs before conversion and Dataset writing. A verified run charged it and wrote zero rows.

Does all exclude live chat or nonstandard subtitle tracks? No explicit exclusion is configured. Source-specific tracks may be requested and may fail SRT conversion.

Is subtitle ordered? JSON object insertion order may be preserved by clients, but consumers should use the time-range keys. Duplicate keys cannot coexist.

Are SRT links permanent? They point to KVS records through signed URLs. Archive authorized files according to your retention needs and confirm access instead of assuming permanence.

Trust & Certifications

The trust model is evidence-based: the public input matches runtime validation, the Dataset documents all 11 keys, the Subtitle charge boundary is explicit, KVS records can be checked independently, and source variability is treated as a first-class outcome.

This Actor is not certified by a video platform, accessibility authority, translation body, or rights organization. It does not verify authorship, caption accuracy, language correctness, content safety, ownership, or license. yt-dlp documents separate options for manual and automatically generated subtitles and describes language selection as patterns or all; this Actor uses those source-facing mechanisms.

Legal & Compliance

Process only URLs and subtitle data you are authorized to access and reuse. Follow source terms, Apify terms, copyright, privacy, contract, and accessibility requirements. A public URL or downloadable caption file does not by itself grant republication, model-training, translation, or commercial-use permission.

Do not bypass access controls, submit private material without authority, or redistribute personal/sensitive content without a valid basis. Keep inputs and tokens protected, define retention, and perform human review before publication or high-impact use. FFmpeg conversion changes file representation; it does not create rights or guarantee semantic accuracy. This is operational guidance, not legal advice.

Related Tools

• Video Transcript — use a transcription-oriented workflow when subtitle files are not the right source.
• YouTube Transcript — target YouTube transcript workflows.
• TikTok Transcript — target TikTok transcript workflows.
• All Video Scraper — retrieve video metadata or media-oriented outputs across supported sources.
• Instagram Reel Scraper — collect public Instagram post and Reel observations.
• Video to Social Post — transform authorized video context into a draft social workflow.

Do not substitute one product name for another capability. Subtitle-file extraction, audio transcription, media download, and content generation have different inputs, outputs, costs, and rights questions.

Support & Community

For a reproducible issue, provide the run ID, UTC time, redacted video URL if necessary, selected language names, terminal status, Subtitles event count, Dataset item count, and KVS key list. State whether the problem is source extraction, language matching, FFmpeg conversion, SRT parsing, storage, or billing. Never share an API token.

Use the AgentX support channel for Actor questions. Review the official yt-dlp subtitle options, FFmpeg documentation, and Apify Actor documentation for their respective layers. Last updated: July 23, 2026.