CJK-Accurate Audio & Video Transcriber (Whisper) — Traditional Chinese, SRT/VTT

Turn any audio or video URL into a clean transcript with correct Chinese script. Whisper is excellent at Mandarin, but its output randomly mixes Simplified and Traditional characters and uses mainland phrasing (软件, 网络). This Actor fixes that at the source (Traditional-Chinese prompting) and at the output (OpenCC s2twp → 軟體, 網路), so Taiwan / Hong Kong readers get text they would actually publish. It also drops the boilerplate Whisper hallucinates over intros, jingles and silence (請不吝點贊…, Amara.org credits, prompt echoes), which most Whisper wrappers pass straight through. Works for any language Whisper supports — the CJK handling only kicks in when Chinese is detected.

What you get

One dataset item per URL:

{
  "url": "https://example.com/episode.mp3",
  "index": 0,
  "status": "ok",
  "language": "Chinese",
  "durationSec": 1834.2,
  "billableMinutes": 31,
  "chunks": 4,
  "scriptConversion": "s2twp",
  "droppedSegments": 1,
  "text": "第一句…\n第二句…",
  "segments": [{ "start": 0.0, "end": 4.2, "text": "第一句…" }],
  "srtUrl": "https://api.apify.com/v2/key-value-stores/…/records/0000.srt",
  "vttUrl": "https://api.apify.com/v2/key-value-stores/…/records/0000.vtt"
}

status is one of ok, failed (with a fixed error code: download_failed, too_large, too_long, probe_failed, transcode_failed, auth_failed, bad_request, upstream_unavailable, internal_error), skipped_charge_limit (your run budget could not cover the file — nothing was transcribed, nothing charged) or partial_charge. language, chunks, scriptConversion, droppedSegments and the output fields only exist on ok / partial_charge items; skipped_charge_limit items carry url, index, status, durationSec, billableMinutes and nothing else; failed items carry url, index, status, error and nothing else — read those keys conditionally. Two optional flags mark an empty result on an ok / partial_charge item: emptyTranscript: true whenever no segment survived (audio without speech, or everything filtered) and additionally allSegmentsDropped: true when the hallucination filter is what removed them.

Input

Field	Default	Notes
audioUrls	—	Direct http(s) links: mp3, m4a, wav, mp4, mkv, podcast enclosures
language	auto	ISO 639-1. Use zh for Chinese audio: enables the Traditional prompt
chineseScript	auto	auto/traditional → Taiwan Traditional (s2twp); simplified; none
outputFormats	text, segments, srt	vtt also available; subtitle files land in the key-value store
model	whisper-large-v3-turbo	or whisper-large-v3
initialPrompt	empty	≤500 chars of names / jargon; auto Taiwan prompt when zh + Traditional
filterHallucinations	true	Drop segments Whisper invents over silence/music (see Notes); count in droppedSegments
chunkMinutes	10	Long files are split; 10 min keeps chunks under Groq's 25 MB cap
maxFileSizeMb	500	Rejected before any cost is incurred
maxDurationMinutes	240	Rejected before any cost is incurred
groqApiKey	empty	Bring your own key → billed at the cheaper audio-minute-byok event

Pricing (pay per event)

Event	When
audio-minute	per started minute of audio, hosted key
audio-minute-byok	per started minute of audio, your own Groq key

Minutes are rounded up per file. Files that would exceed your run's max charge are skipped (skipped_charge_limit) instead of being half-transcribed.

Notes

• Only transcribe media you own or are allowed to process. The Actor downloads the URL you give it and sends audio to Groq's Whisper API; no media is retained after the run.
• Speech recognition is done by whisper-large-v3-turbo on Groq; accuracy on noisy audio, heavy code-switching or Taiwanese Hokkien is limited by the model. Proper nouns and programme names are best fixed by listing them in initialPrompt.
• Hallucination filter (filterHallucinations): a segment is dropped when it contains known subtitle boilerplate (明鏡與點點欄目, 點贊/點讚訂閱轉發打賞, Amara.org, 優優獨播劇場; matched script-insensitively), is nothing but punctuation or music glyphs (♪), echoes the built-in Traditional-Chinese prompt (at least 60 % of it once punctuation and spaces are removed — your own initialPrompt is never echo-checked, because you list words the speaker will actually say), spans ≥ 15 s with under 1 letter/character per second (punctuation and spaces not counted), or trips Whisper's own no-speech (> 0.6 with logprob < −1.0) or repetition (compression ratio > 2.4) thresholds. droppedSegments reports the count (null when the filter is off); an empty result is flagged with emptyTranscript: true, plus allSegmentsDropped: true when the filter removed everything. Set the filter to false for very sparse speech (guided meditation, long pauses).
• No speaker diarization yet (planned).

Development

python3.12 -m venv .venv && ./.venv/bin/pip install -r requirements.txt pytest pytest-asyncio
./.venv/bin/python -m pytest -q                      # 130 tests, real ffmpeg, no network
mkdir -p storage/key_value_stores/default
cp example_input.json storage/key_value_stores/default/INPUT.json   # edit the URL
bash scripts/set-groq-key.sh                          # once: key from clipboard → ~/.config/cjk-transcriber.env (0600)
set -a; source ~/.config/cjk-transcriber.env; set +a  # never put the key on a command line
./.venv/bin/python -m src                             # local run; output in storage/datasets/default

ffmpeg/ffprobe must be on PATH locally (the Docker image installs them). Set ACTOR_TEST_PAY_PER_EVENT=1 to exercise the charging code path locally.

Deploy to Apify

1. npm i -g apify-cli && apify login
2. apify push from this directory (builds the Dockerfile on Apify).
3. Console → Actor → Settings → Environment variables: add GROQ_API_KEY as a secret.
4. Console → Monetization: pay-per-event with events audio-minute and audio-minute-byok (suggested launch prices $0.008 and $0.003 per minute; Groq turbo costs ~$0.0007/min).
5. Publish to Store with this README, a title, categories (AI, Audio, Transcription) and one example run.