# Video Subtitles Downloader (`truefetch/video-subtitles-downloader`) Actor

Download subtitles from 1,000+ video platforms — VTT, ASS, TTML, JSON, and 5 other formats all converted to clean SRT from a single pasted link. ~$0.051 per video.

- **URL**: https://apify.com/truefetch/video-subtitles-downloader.md
- **Developed by:** [TrueFetch](https://apify.com/truefetch) (community)
- **Categories:** Videos, Social media, News
- **Stats:** 23 total users, 1 monthly users, 100.0% runs succeeded, 2 bookmarks
- **User rating**: 5.00 out of 5 stars

## Pricing

from $0.25 / subtitles

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

Video Subtitles Downloader turns subtitle tracks already exposed by a video source into structured Dataset rows and downloadable SRT records. Give it one video URL, select subtitle languages, and inspect each file that completed extraction and conversion.

- Send one non-empty video URL that the current source extractor can open.
- Select from 54 named language patterns, choose `all`, or omit the list to request English.
- Receive one 11-field row for each subtitle file that finishes conversion, including timecoded text and video metadata.
- Plan for source changes, language variants, and a possible Subtitles charge even when conversion produces zero rows.

[Open Video Subtitles Downloader](https://console.apify.com/actors/FiN3qhAHDYW2nV3Wx/input), call it through the [Apify API](https://docs.apify.com/api/v2), or use an [MCP-compatible client](https://docs.apify.com/integrations/mcp). The Actor requests manual and source-generated subtitle files; it does not download the video, transcribe its audio locally, translate captions, or guarantee that a source will expose a usable track.

### What does Video Subtitles Downloader do?

The Actor accepts a single video URL and a set of language selectors. It asks the installed extractor for existing subtitle files while skipping media download. Both manually supplied captions and captions generated by the source platform may be requested. If the extractor returns a subtitle-related file, the runtime converts it to SRT when necessary, parses its time ranges and text, stores the converted SRT in the run key-value store, and pushes a Dataset item.

Each written item represents a converted file, not a unique video or a guaranteed selected language. A broad expression such as English can match source variants such as `en` and `en-orig`; these may become separate rows. Conversely, a selected language can produce no row when the video has no matching track, the source blocks extraction, or conversion fails.

This distinction matters when the source advertises “automatic subtitles.” Here, automatic means a caption track created and exposed by that platform. The Actor has no speech-recognition engine and no fallback that derives text from downloaded audio. If you need audio transcription rather than subtitle-file retrieval, use a transcription-specific workflow.

### How do I run Video Subtitles Downloader?

Start with one URL and one language. English is the runtime default when `languages` is omitted. This small request is easier to validate than `all`, which may retrieve multiple source-specific tracks and variants.

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

After the run reaches a terminal state, compare the charged-event counters, Dataset item count, and key-value store records. A successful process state only means the Actor completed its control flow; it does not prove that subtitle rows exist. Open each `srt_url` while it remains available and compare it with the `subtitle` object before sending the data downstream.

For scheduled monitoring, retain the run ID and original input in your own job ledger. Source availability can change between otherwise identical runs, so a retry is a new observation rather than proof that the earlier result was wrong.

### What data does Video Subtitles Downloader return?

Every stored Dataset item has 11 top-level fields. `processor` identifies the Actor, and `processed_at` records when metadata was formatted. `thumbnail`, `platform`, `title`, `description`, `published_at`, and `author` come from the source extractor when available. `language` is derived from the downloaded filename suffix. `subtitle` is an object whose keys are SRT time ranges and whose values are joined caption text. `srt_url` points to the converted file record in the run key-value store.

```json
{
  "processor": "https://apify.com/truefetch/video-subtitles-downloader",
  "processed_at": "2026-07-23T12:10:00+00:00",
  "thumbnail": "https://example.com/video-thumbnail.jpg",
  "platform": "Youtube",
  "title": "Example source video",
  "description": "Description reported by the source",
  "published_at": "2026-07-01T09:00:00+00:00",
  "author": "Example creator",
  "language": "ENGLISH",
  "subtitle": {
    "00:00:00,000 --> 00:00:02,400": "Example source caption"
  },
  "srt_url": "https://api.apify.com/v2/key-value-stores/STORE_ID/records/en.srt?signature=SIGNED_VALUE"
}
```

The row does not contain the submitted `video_url`; save that association outside the Dataset if your pipeline requires it. Metadata can be null or change later. The subtitle parser joins multiline cue text with spaces and uses a time-range string as an object key. If a file repeats an identical key, later text replaces earlier text. Treat the map as a convenient representation, not a lossless replacement for every unusual SRT construct.

### What inputs can I use?

`video_url` is the only required public input. It must be a non-empty string, but the schema does not impose a fixed platform regex or allowlist. Actual compatibility is decided by the extractor and the live source.

`languages` is optional and must contain at least one allowed value when supplied. It supports `all` plus 54 named patterns covering Afrikaans, Arabic, Armenian, Belarusian, Bengali, Bulgarian, Cantonese, Catalan, simplified and traditional Chinese, 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.

Named options map to code patterns rather than exact human-language guarantees. English, for example, can match multiple English-labelled files. `all` asks for everything the extractor and source expose; it does not manufacture absent translations or guarantee successful conversion of every downloaded file.

### What platforms and markets are supported?

There is no honest fixed site count or permanent compatibility list for this Actor. Support follows the installed source extractor, and sites can change login rules, endpoints, geographic behavior, rate limits, markup, or subtitle delivery without notice. The official [yt-dlp supported-sites document](https://github.com/yt-dlp/yt-dlp/blob/master/supportedsites.md) warns that even a listed extractor is not a guarantee that a site currently works.

Market coverage likewise depends on the submitted URL, source visibility, network route, account requirements, and caption availability. A public video can work in one run and fail later. Private, removed, login-gated, age-restricted, geoblocked, or rate-limited content may be unavailable. Test the exact URL and desired language in the environment where the production run will execute.

### Why use Video Subtitles Downloader?

The Actor combines extraction, SRT normalization, structured parsing, storage, and run observability. Instead of managing a downloader process and manually locating output files, you get Dataset rows, KVS records, logs, resource usage, and charge-event evidence tied to one Apify run.

The contract is deliberately narrow. It separates source metadata from caption content, exposes language variants rather than collapsing them silently, and documents the billing boundary. That makes failures easier to audit and prevents a zero-row run from being mistaken for a verified “no captions exist” conclusion.

The Actor also fits workflows that need reviewable artifacts. Teams can archive authorized SRT files, compare variants, search timecoded text, or route rows to a later translation or editorial process. It is not a replacement for human caption QA, rights review, or accessibility validation.

### Who is Video Subtitles Downloader for?

Content operations teams can retrieve available caption files before editing or republishing authorized media. Localization teams can use the source language SRT as an input to a separate translation and timing workflow. Researchers can collect timecoded text observations while preserving run-level provenance and documenting source variability.

Developers can integrate the Dataset envelope into an ETL job without parsing files from a local working directory. Accessibility teams can use the result as an initial artifact, but should still review wording, timing, speaker attribution, sound cues, reading speed, punctuation, and completeness. Compliance teams should verify authorization, retention, and permitted reuse independently.

### Can I use Video Subtitles Downloader through an API or MCP?

Yes. Use the Actor ID `FiN3qhAHDYW2nV3Wx` or the name `truefetch/video-subtitles-downloader` with Apify REST clients, schedules, webhooks, integrations, or an MCP-capable application. Keep the token in a secret manager and store the returned run ID.

```json
{
  "method": "POST",
  "url": "https://api.apify.com/v2/acts/truefetch~video-subtitles-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"]
  }
}
```

Read `defaultDatasetId` and `defaultKeyValueStoreId` from the finished run. Validate the item count and SRT records instead of relying only on terminal status. Some MCP plans may not permit direct execution of every public Actor; in that case, run the exact cloud build through authenticated REST and use MCP for independent Actor, run, Dataset, and KVS readback.

### How much does Video Subtitles Downloader cost?

The local pay-per-event configuration lists Actor Usage at `$0.00001` per metered unit, a one-time Actor Start at `$0.01`, and a one-time Subtitles event at `$0.25`. The active Apify Store schedule at execution time is authoritative.

Subtitles is not priced per Dataset row, language, caption cue, or video minute. Runtime requests the event once after at least one subtitle-related file has been downloaded and before individual conversion and Dataset writing. A qualifying run therefore begins at `$0.26` plus metered usage, yet it can yield several rows, one row, or zero rows. Ten separate qualifying runs begin at `$2.60` plus usage.

Set `maxTotalChargeUsd` when you need a budget boundary and review event counts afterward. A charge cap cannot guarantee source access, caption accuracy, or row creation.

### How does Video Subtitles Downloader compare with alternatives?

A transcript API may generate new text from audio, while this Actor retrieves existing source subtitle files. A media downloader focuses on audio or video assets. A translation service creates target-language text. A caption editor focuses on corrections, timing, and export. These are related but different jobs.

Choose this Actor when source-exposed subtitle files and their SRT representation are the primary evidence you need. Choose transcription when no usable captions exist and you have permission to process the audio. Use translation and human review after extraction when multilingual publication is the objective.

### What are the limits and troubleshooting steps?

First verify that the URL is public and currently playable, then try one named language. Check logs, event counts, Dataset items, and KVS keys. If extraction fails, consult current source behavior and the official [yt-dlp subtitle options](https://github.com/yt-dlp/yt-dlp/blob/master/README.md#subtitle-options). If a file downloads but no row appears, conversion or parsing may have failed; [FFmpeg documentation](https://www.ffmpeg.org/ffmpeg.html) describes the conversion layer.

A verified run can charge Subtitles and still write zero rows because billing occurs before per-file conversion. Duplicate-looking language rows can arise from variants such as `en` and `en-orig`. Signed SRT URLs depend on KVS retention and access. Save authorized artifacts you need to retain. Never expose tokens in logs or support messages.

### FAQ

**Does the Actor transcribe audio?** No. It only requests subtitle tracks exposed by the source.

**Does it translate captions?** No. Language options select available tracks; they do not create translations.

**Why can one language produce multiple rows?** A language pattern can match multiple source variants, and every successfully converted file is processed separately.

**Can a completed run have no Dataset items?** Yes. Source retrieval or file conversion can produce no writable row.

**Can Subtitles be charged with zero items?** Yes. The event occurs before conversion and Dataset writing once a subtitle-related file is present.

**Are the captions verified?** No. Accuracy and generation method depend on the source, and qualified human review remains necessary.

**Does a public URL grant reuse rights?** No. Confirm copyright, contract, privacy, platform terms, and any required consent before storage, translation, analysis, training, or republication.

### Related TrueFetch Actors

- [Video To Text](https://apify.com/truefetch/video-to-text?fpr=aiagentapi) — use an audio-to-text workflow when an authorized video has no suitable caption track.
- [Instagram Video Transcript](https://apify.com/truefetch/instagram-video-transcript?fpr=aiagentapi) — use a transcript-oriented flow for supported Instagram video content.
- [YouTube Video Downloader](https://apify.com/truefetch/youtube-video-downloader?fpr=aiagentapi) — retrieve authorized YouTube media when the asset, rather than a subtitle file, is required.

Review each Actor's current input, output, billing, and source limits before substituting it in a pipeline.

### Support and last updated

For a reproducible report, share the run ID, UTC time, redacted URL if needed, selected language options, build number, terminal state, Subtitles event count, Dataset item count, and KVS key names. Explain whether the issue concerns extraction, matching, conversion, parsing, storage, API access, or billing. Do not send API tokens or private source material.

Contact the [TrueFetch community](https://t.me/TrueFetch) or [support channel](https://t.me/AiAgentApi). For platform concepts, see the [Apify Actor documentation](https://docs.apify.com/platform/actors). Last updated: July 23, 2026.

# Actor input Schema

## `video_url` (type: `string`):

Enter one non-empty video URL. Compatibility and subtitle availability depend on the current extractor and source; listed sites are not guaranteed to work.

## `languages` (type: `array`):

Optional. Select one or more of 54 named language patterns, or all. The Actor requests source-provided manual and auto-generated tracks; it does not transcribe audio. Defaults to English when omitted.

## Actor input object example

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

# Actor output Schema

## `results` (type: `string`):

Open converted subtitle rows with video metadata, a time-range-to-text map, and signed SRT record URLs. A charged run can still have zero rows if conversion or writing fails.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "video_url": "https://www.youtube.com/shorts/noWlKvEPOWk",
    "languages": [
        "english"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("truefetch/video-subtitles-downloader").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "video_url": "https://www.youtube.com/shorts/noWlKvEPOWk",
    "languages": ["english"],
}

# Run the Actor and wait for it to finish
run = client.actor("truefetch/video-subtitles-downloader").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "video_url": "https://www.youtube.com/shorts/noWlKvEPOWk",
  "languages": [
    "english"
  ]
}' |
apify call truefetch/video-subtitles-downloader --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=truefetch/video-subtitles-downloader",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/FiN3qhAHDYW2nV3Wx/builds/NzWVUpuJAlwElPV31/openapi.json