# Media Transcriber: Audio & Video to Text, SRT, VTT (Whisper) (`blackcatforge/media-transcriber`) Actor

Transcribe or translate your own audio and video files (MP3, WAV, M4A, MP4, MOV, WebM...) into text, timestamped segments, SRT and VTT subtitles. Built-in Whisper models on Apify, or bring your own Groq/OpenAI key for the cheapest per-minute price. Pay only per transcribed minute.

- **URL**: https://apify.com/blackcatforge/media-transcriber.md
- **Developed by:** [Blackcat Forge](https://apify.com/blackcatforge) (community)
- **Categories:** AI, Videos, For creators
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $5.00 / 1,000 audio minute (fast model)s

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Media Transcriber: Audio & Video to Text, SRT and VTT (Whisper)

*By **Blackcat Forge***

Turn your own audio and video files into **clean text, timestamped segments, SRT and WebVTT subtitles** in bulk. Paste direct file links (MP3, WAV, M4A, AAC, OGG, FLAC, MP4, MOV, WebM, MKV…) and get one result row per file, plus downloadable `.txt`, `.srt` and `.vtt` files.

Good for podcast show notes, subtitle files for your own videos, searchable meeting and lecture archives, interview transcripts, and feeding speech into LLM pipelines.

### Why this one

- **Pay per audio minute, nothing else.** No monthly fee, no per-file minimum beyond one minute. Files that fail are free.
- **Three engines:**
  - **Fast** (Whisper *base*, or *tiny* for maximum speed): roughly 10–30× faster than real time on the default 4 GB setup.
  - **Accurate** (Whisper *small*): better with accents, noisy audio and non-English speech.
  - **Bring your own key** (Groq `whisper-large-v3-turbo` or OpenAI `whisper-1`): best accuracy and speed. You pay the provider directly, and this Actor charges a tiny orchestration fee.
- **99 languages** with auto-detection, or translate any language to English.
- **Subtitles ready to upload:** SRT and VTT with correct timestamps, plus optional word-level timing.
- **Long files are fine:** audio is processed in 10-minute windows, so memory stays flat for multi-hour recordings.
- **Private by design:** files are deleted from the run's disk right after processing. Your API key is stored encrypted by Apify and is never logged or written to results.

### Input

```json
{
  "mediaUrls": ["https://example-bucket.s3.amazonaws.com/episode-42.mp3"],
  "model": "base",
  "language": "",
  "task": "transcribe",
  "outputFormats": ["text", "segments", "srt", "vtt"],
  "wordTimestamps": false
}
```

**Links must be direct links to a file** that you own or have the rights to transcribe. That includes your own storage bucket or CDN, a podcast RSS enclosure, or a Dropbox/Google Drive direct-download link. Links to YouTube, TikTok, Instagram, Facebook, X, Vimeo, Spotify, SoundCloud and similar platforms are refused, because their terms don't allow downloading.

### Output (one row per file)

```json
{
  "url": "https://…/episode-42.mp3",
  "status": "ok",
  "durationSeconds": 506.9,
  "billedMinutes": 9,
  "language": "en",
  "engine": "faster-whisper/base",
  "wordCount": 1312,
  "text": "This is a LibriVox recording…",
  "segments": [{ "start": 0.0, "end": 4.2, "text": "This is a LibriVox recording." }],
  "srt": "1\n00:00:00,000 --> 00:00:04,200\nThis is a LibriVox recording.\n…",
  "files": { "txt": "https://api.apify.com/v2/key-value-stores/…/records/001-episode-42-….txt", "srt": "…", "vtt": "…" }
}
```

Failed files come back with `status: "error"` and a plain-English `error`, and they're **not charged**.

### Pricing (pay per event)

| Event | Price |
|---|---|
| Audio minute, fast model (tiny / base) | **$0.005** per started minute |
| Audio minute, accurate model (small) | **$0.015** per started minute |
| Audio minute, your own Groq/OpenAI key | **$0.002** per started minute (+ what your provider charges you) |
| Large file download, per 100 MB beyond 3 MB per audio minute | $0.03 |
| Actor start (covers loading the speech model) | $0.0005 per GB of run memory ($0.002 per run at the default 4 GB) |

Examples: a 45-minute podcast on the fast model costs **$0.23** (plus the $0.002 start fee). Ten hours of lectures cost **$3.00**. Batch many files into one run to pay the start fee only once.

The large-file fee only applies to heavy files, such as a high-bitrate 1080p video where you only need the speech. Audio files of any normal quality, even 320 kbps, never hit it. Tip: send audio-only files when you can.

Set **Max cost per run** and the Actor stops cleanly at your limit. If the limit is reached partway through a file, the file is transcribed only up to the minutes you can afford, and that's all you're charged for.

### Accuracy notes

- *base* is good for clear speech: podcasts, narration, meetings with decent mics. *small* is noticeably better for accents, crosstalk, noise and most non-English languages. For the best quality, bring a Groq key: large-v3-turbo costs about $0.04 per hour at Groq, so $0.002 + ~$0.0007 per minute in total.
- Silence and music-only parts are skipped (voice-activity detection), so they don't produce hallucinated text.
- Whisper doesn't label speakers (no diarization).

### Limits

- Up to 600 minutes per file (default 240) and 4 GB per file (default 1 GB).
- The fast and accurate models run on CPU. Very long files take a while, roughly 4–6 minutes per hour of audio on the fast model and 15–25 minutes on the accurate one. Word-level timestamps add about 70%.

### Responsible use

Only transcribe recordings that you own or are allowed to process, and follow the recording-consent laws that apply to you. This Actor does no scraping: it only downloads the exact file URLs you provide. It refuses private-network addresses and platforms whose terms forbid downloading.

### Local development

```bash
pip install -r requirements.txt     # also needs ffmpeg on PATH
python -m pytest tests
apify run                            # reads storage/key_value_stores/default/INPUT.json
```

*Blackcat Forge builds small, dependable tools for developers and creators.*

# Actor input Schema

## `mediaUrls` (type: `array`):

Direct links to media files you own or have rights to (your storage bucket, CDN, podcast RSS enclosure, Dropbox/Drive direct-download links). Links to YouTube, TikTok, Instagram, Spotify, Vimeo and similar platforms are refused because their terms forbid downloading.

## `model` (type: `string`):

Base = fast and cheap, good for clear speech (fast-model price). Tiny = fastest, lower accuracy (same price). Small = more accurate for accents, noise and non-English (accurate-model price). Ignored when you bring your own key.

## `language` (type: `string`):

ISO code such as en, es, de, ja. Leave empty to auto-detect.

## `task` (type: `string`):

Transcribe in the original language, or translate speech to English.

## `outputFormats` (type: `array`):

What to include in each result.

## `wordTimestamps` (type: `boolean`):

Adds per-word timing to segments (slightly slower).

## `byokProvider` (type: `string`):

Use your own Groq (whisper-large-v3-turbo) or OpenAI (whisper-1) account for transcription. You pay the provider directly; this Actor then charges only the low audio-minute-byok price.

## `apiKey` (type: `string`):

Stored encrypted by Apify; never logged or saved to results.

## `maxMinutesPerFile` (type: `integer`):

Longer files are transcribed up to this length (and billed only for that).

## `maxFileSizeMb` (type: `integer`):

Downloads larger than this are refused. Files above 3 MB per audio minute (typically high-bitrate video) incur the small large-file fee per extra 100 MB; send audio-only files to avoid it.

## Actor input object example

```json
{
  "mediaUrls": [
    "https://archive.org/download/art_of_war_librivox/art_of_war_01-02_sun_tzu_64kb.mp3"
  ],
  "model": "base",
  "task": "transcribe",
  "outputFormats": [
    "text",
    "segments",
    "srt",
    "vtt"
  ],
  "wordTimestamps": false,
  "byokProvider": "none",
  "maxMinutesPerFile": 240,
  "maxFileSizeMb": 1024
}
```

# Actor output Schema

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

No description

# 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 = {
    "mediaUrls": [
        "https://archive.org/download/art_of_war_librivox/art_of_war_01-02_sun_tzu_64kb.mp3"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("blackcatforge/media-transcriber").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 = { "mediaUrls": ["https://archive.org/download/art_of_war_librivox/art_of_war_01-02_sun_tzu_64kb.mp3"] }

# Run the Actor and wait for it to finish
run = client.actor("blackcatforge/media-transcriber").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "mediaUrls": [
    "https://archive.org/download/art_of_war_librivox/art_of_war_01-02_sun_tzu_64kb.mp3"
  ]
}' |
apify call blackcatforge/media-transcriber --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,blackcatforge/media-transcriber"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

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