video-to-text-local

name	video-to-text-local
description	Transcribe video/audio URL or local file to text + SRT using yt-dlp + local mlx-whisper (Apple Silicon). Free, offline, fastest on M-series Macs. Opt-in advanced path for users with Apple Silicon + mlx-whisper installed. Returns raw text and segments; summary is caller's responsibility.
version	0.1.0
layer	leaf
domains	["video-audio","transcription"]
scenarios	["video-to-text","subtitle-extraction","podcast-transcription","offline-transcription"]
trigger_keywords	["转文字","字幕","转录","transcribe","whisper","video to text","播客字幕","本地转录","offline transcribe"]
model_tier	Fast
auth_required	false
cost	free
experience_digest	experience.md

Transcribe video or audio entirely on-device using yt-dlp audio extraction plus local mlx-whisper inference. Works offline, zero API cost, fastest on Apple Silicon M-series with MLX Metal acceleration.

Input Fit

• YouTube URLs.
• Bilibili URLs.
• Douyin URLs.
• Xiaoyuzhou podcast URLs.
• Local audio files such as MP3, M4A, WAV, AAC, FLAC, OGG, and OPUS.
• Local video files such as MP4, MOV, MKV, AVI, WEBM, FLV, and M4V.

Invocation

Call transcribe.py's sync transcribe(url_or_path: str) function with the original URL or local file path:

result = transcribe("https://www.youtube.com/watch?v=example")

Successful calls return:

{
    "ok": True,
    "raw_txt": "...",
    "subtitle_srt": "1\n00:00:00,000 --> 00:00:03,100\n...\n",
    "meta": {
        "language": "en",
        "duration_sec": 123.4,
        "model": "mlx-community/whisper-large-v3-turbo",
        "backend": "mlx-whisper",
    },
    "audio_path": "/tmp/autosearch-video-to-text-local-.../audio.mp3",
    "source": "https://www.youtube.com/watch?v=example",
}

Failure Modes

• Missing mlx-whisper package returns reason: mlx_whisper_unavailable (install with pip install mlx-whisper, Apple Silicon only).
• Unsupported URLs, network failures, and non-zero yt-dlp exits return reason: yt_dlp_failed.
• Missing local ffmpeg for video conversion returns reason: ffmpeg_missing.
• Model download failure (no network on first run) returns reason: model_download_failed.
• Other MLX / transcription runtime errors return reason: mlx_whisper_runtime_error.

Downgrade chain: use video-to-text-groq as the free cloud fallback (requires GROQ_API_KEY), then video-to-text-openai as the paid cloud fallback.

Limits

• Requires Apple Silicon (M1 / M2 / M3 / M4). Not compatible with Intel Macs, Linux, or Windows.
• Requires mlx-whisper package installed separately: pip install mlx-whisper (not a default autosearch dependency because it's macOS/ARM-only).
• First run downloads the Whisper model to ~/.cache/huggingface/hub/ (~3 GB for large-v3-turbo).
• Default model: mlx-community/whisper-large-v3-turbo. Override via AUTOSEARCH_MLX_WHISPER_MODEL env var to any HuggingFace repo or local model path.

This tool does not produce a summary. It returns raw_txt and subtitles so the runtime AI can decide how to process, summarize, quote, or cite the transcript.

Quality Bar

• Evidence items have non-empty title and url.
• No crash on empty or malformed API response.
• Source channel field matches the channel name.