Skip to content
Back to search

AI-Video-Transcriber

Transcribe and summarize videos and podcasts using AI. Open-source, multi-platform, and supports multiple languages.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wendy7756--ai-video-transcriber/badge.svg)](/listings/wendy7756--ai-video-transcriber)

HTML

<a href="/listings/wendy7756--ai-video-transcriber"><img src="/api/listings/wendy7756--ai-video-transcriber/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Python 3.8+ - FFmpeg (required for yt-dlp audio extraction, merging downloaded video, and normalizing uploaded media) - An API key from any OpenAI-compatible provider (OpenAI, OpenRouter, etc.) — configurable directly in the UI, no server-side env var needed

Installation

<details open> <summary><b>Method 1: Automatic Installation</b></summary>

git clone https://github.com/wendy7756/AI-Video-Transcriber.git
cd AI-Video-Transcriber

chmod +x install.sh
./install.sh

</details>

<details> <summary><b>Method 2: Docker</b></summary>

git clone https://github.com/wendy7756/AI-Video-Transcriber.git
cd AI-Video-Transcriber

# Using Docker Compose (easiest)
cp .env.example .env
# Edit .env if you want server-side defaults (optional)
docker-compose up -d

# Or using Docker directly
docker build -t ai-video-transcriber .
docker run -p 8000:8000 --env-file .env ai-video-transcriber

The image uses **Python 3.12** (Debian Bookworm), upgrades `pip`/`setuptools`/`wheel`, then installs from `requirements.txt` — same version constraints as a fresh local venv on a current Python.

> **Tip:** transcripts and downloaded videos live in `/app/temp` inside the container. Uncomment the `volumes` block in `docker-compose.yml` to persist them on the host.

</details>

<details> <summary><b>Method 3: Manual Installation</b></summary>

**1. Install Python dependencies**

# macOS (PEP 668) strongly recommends a virtualenv
python3 -m venv venv
source venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

**2. Install FFmpeg**

brew install ffmpeg                              # macOS
sudo apt update && sudo apt install ffmpeg       # Ubuntu/Debian
sudo yum install ffmpeg                          # CentOS/RHEL

**3. Configure environment variables** *(optional)*

# Only if you prefer server-side defaults — otherwise configure in the UI
export OPENAI_API_KEY="your_api_key_here"
export OPENAI_BASE_URL="https://openrouter.ai/api/v1"   # any OpenAI-compatible endpoint

</details>

Start the Service

python3 start.py

Then open `http://localhost:8000`.

**Production mode (recommended for long videos)** — disables hot-reload so the SSE connection stays stable across 30–60+ minute tasks:

python3 start.py --prod

<details> <summary>Run with explicit env (example)</summary>

source venv/bin/activate
export OPENAI_API_KEY=your_api_key_here                  # optional: server-side default
# export OPENAI_BASE_URL=https://openrouter.ai/api/v1    # optional: server-side default
python3 start.py --prod

</details>

<a id="usage-guide"></a>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 661 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <div align="center">
  2. # AI Video Transcriber
  3. English | [中文](README_ZH.md)
  4. An AI-powered tool to transcribe, summarize, and archive videos and podcasts — paste a URL from YouTube, TikTok, Bilibili, Apple Podcasts, SoundCloud, and 30+ platforms, **or upload a local file** (audio, video, or plain text).
  5. ![Interface](en_video.png)
  6. </div>
  7. ## ✨ Features
  8. - 🎥 **Multi-Platform Support**: Works with YouTube, TikTok, Bilibili, Apple Podcasts, SoundCloud, and 30+ more
  9. - ⚡ **Subtitle-First Architecture**: For platforms with native subtitles (e.g. YouTube), transcripts are extracted instantly — no audio download needed. Whisper is only a fallback, making the whole pipeline dramatically faster
  10. - 🎬 **Original Video Download**: Keep the source video alongside the transcript. It downloads **in parallel** with transcription, previews inline in the results card, and saves with one click. On the Whisper path the audio is extracted from that same file, so the video is only fetched once. Toggle **Keep original video** off when you want text only
  11. - 📁 **Local File Upload**: Drag-and-drop or pick a file — `.txt` (treated as transcript text), `.mp3`, `.mp4`, `.m4a`, `.wav`, `.webm`, `.mkv`, `.ogg`, `.flac`. Media is normalized with FFmpeg for Whisper, then runs the same optimize → translate → summarize pipeline as URLs
  12. - 🗣️ **Intelligent Transcription**: High-accuracy speech-to-text using Faster-Whisper when subtitles aren't available
  13. - 🤖 **AI Text Optimization**: Automatic typo correction, sentence completion, and intelligent paragraphing
  14. - 🌍 **Multi-Language Summaries**: Generate intelligent summaries in 11 languages
  15. - ⚙️ **Conditional Translation**: Auto-translates the transcript when the summary language differs from the source language
  16. - 🔧 **Bring Your Own Model**: Configure any OpenAI-compatible API endpoint (OpenAI, OpenRouter, local LLM, etc.) directly in the UI — enter your API Base URL and API Key, then click **Fetch** to auto-discover available models
  17. - 📡 **Live Progress**: Server-sent events stream real-time status, with a badge showing whether the job took the subtitle or Whisper path
  18. - 📱 **Mobile-Friendly**: Responsive layout, dark UI
  19. ## 📑 Contents
  20. - [Quick Start](#quick-start)
  21. - [Usage Guide](#usage-guide)
  22. - [Use It From Claude / Codex / Scripts](#agents)
  23. - [API Reference](#api-reference)
  24. - [Technical Architecture](#architecture)
  25. - [Configuration Options](#configuration)
  26. - [FAQ](#faq)
  27. - [Supported Languages](#languages)
  28. - [Performance Tips](#performance)
  29. - [Contributing](#contributing)
  30. <a id="quick-start"></a>
  31. ## 🚀 Quick Start
  32. ### Prerequisites
  33. - Python 3.8+
  34. - FFmpeg (required for yt-dlp audio extraction, merging downloaded video, and normalizing uploaded media)
  35. - An API key from any OpenAI-compatible provider (OpenAI, OpenRouter, etc.) — configurable directly in the UI, no server-side env var needed
  36. ### Installation
  37. <details open>
  38. <summary><b>Method 1: Automatic Installation</b></summary>
  39. ```bash
  40. git clone https://github.com/wendy7756/AI-Video-Transcriber.git
  41. cd AI-Video-Transcriber
  42. chmod +x install.sh
  43. ./install.sh
  44. ```
  45. </details>
  46. <details>
  47. <summary><b>Method 2: Docker</b></summary>
  48. ```bash
  49. git clone https://github.com/wendy7756/AI-Video-Transcriber.git
  50. cd AI-Video-Transcriber
  51. # Using Docker Compose (easiest)
  52. cp .env.example .env
  53. # Edit .env if you want server-side defaults (optional)
  54. docker-compose up -d
  55. # Or using Docker directly
  56. docker build -t ai-video-transcriber .
  57. docker run -p 8000:8000 --env-file .env ai-video-transcriber
  58. ```
  59. The image uses **Python 3.12** (Debian Bookworm), upgrades `pip`/`setuptools`/`wheel`, then installs from `requirements.txt` — same version constraints as a fresh local venv on a current Python.
  60. > **Tip:** transcripts and downloaded videos live in `/app/temp` inside the container. Uncomment the `volumes` block in `docker-compose.yml` to persist them on the host.
  61. </details>
  62. <details>
  63. <summary><b>Method 3: Manual Installation</b></summary>
  64. **1. Install Python dependencies**
  65. ```bash
  66. # macOS (PEP 668) strongly recommends a virtualenv
  67. python3 -m venv venv
  68. source venv/bin/activate
  69. python -m pip install --upgrade pip
  70. pip install -r requirements.txt
  71. ```
  72. **2. Install FFmpeg**
  73. ```bash
  74. brew install ffmpeg # macOS
  75. sudo apt update && sudo apt install ffmpeg # Ubuntu/Debian
  76. sudo yum install ffmpeg # CentOS/RHEL
  77. ```
  78. **3. Configure environment variables** *(optional)*
  79. ```bash
  80. # Only if you prefer server-side defaults — otherwise configure in the UI
  81. export OPENAI_API_KEY="your_api_key_here"
  82. export OPENAI_BASE_URL="https://openrouter.ai/api/v1" # any OpenAI-compatible endpoint
  83. ```
  84. </details>
  85. ### Start the Service
  86. ```bash
  87. python3 start.py
  88. ```
  89. Then open `http://localhost:8000`.
  90. **Production mode (recommended for long videos)** — disables hot-reload so the SSE connection stays stable across 30–60+ minute tasks:
  91. ```bash
  92. python3 start.py --prod
  93. ```
  94. <details>
  95. <summary>Run with explicit env (example)</summary>
  96. ```bash
  97. source venv/bin/activate
  98. export OPENAI_API_KEY=your_api_key_here # optional: server-side default
  99. # export OPENAI_BASE_URL=https://openrouter.ai/api/v1 # optional: server-side default
  100. python3 start.py --prod
  101. ```
  102. </details>
  103. <a id="usage-guide"></a>
  104. ## 📖 Usage Guide
  105. **1. Choose your input — URL or file**
  106. - **Video / podcast URL**: paste a link from YouTube, Bilibili, or any supported platform
  107. - **Local file**: drag a file onto the dashed upload area, or click to browse. The same **Transcribe** button starts the job. Uploads use the same API route as URLs (`POST /api/process-video` with a multipart `file`), which helps when a reverse proxy only allows that path
  108. **2. Pick your options**
  109. - **Summary Language** — the output language for the summary
  110. - **Keep original video** — on by default. Downloads the source video (≤720p) so you can preview and save it with the results. Turn it off for text-only jobs to save bandwidth and disk
  111. **3. (Optional) Configure your AI model** — click **AI Settings** to expand
  112. - Enter your **API Base URL** (e.g. `https://openrouter.ai/api/v1`) and **API Key**
  113. - Click **Fetch** to auto-load available models, then select one — or leave blank for the server default
  114. - Credentials are stored in your browser's `localStorage`, never sent anywhere but your chosen provider
  115. **4. Start processing** — click **Transcribe**. For **URL** jobs a badge shows the active mode:
  116. | Badge | Meaning |
  117. |-------|---------|
  118. | **⚡ Subtitle** (green) | Native subtitles found — transcript extracted in seconds |
  119. | **🎙 Whisper** (cyan) | No subtitles available — audio downloaded and transcribed |
  120. For **local uploads**, media is normalized with FFmpeg then transcribed with Whisper. Plain **`.txt`** files skip download and Whisper entirely, going straight into the text pipeline.
  121. **5. Review the results**
  122. - **Transcript** and **AI Summary** tabs are always present; a **Translation** tab appears automatically when the transcript language differs from your summary language
  123. - Each tab has its own **purple download icon** — click it to save that file without switching tabs
  124. - **Download original video** sits at the right of the tab row, next to an inline player showing the source file and its size
  125. <a id="agents"></a>
  126. ## 🤖 Use It From Claude / Codex / Scripts
  127. Besides the web UI there is a headless entry point, so agents and scripts can run the
  128. same pipeline with no server and no browser.
  129. ### CLI
  130. ```bash
  131. venv/bin/python transcribe.py "https://www.youtube.com/watch?v=VIDEO_ID" --json
  132. venv/bin/python transcribe.py talk.mp4 -l zh --no-video
  133. venv/bin/python transcribe.py notes.txt --no-llm # no API key needed
  134. ```
  135. `--json` puts a machine-readable result on stdout and keeps progress on stderr.
  136. Exit codes: `0` success, `2` bad input, `1` download/transcode failure.
  137. | Flag | Meaning |
  138. |------|---------|
  139. | `-l, --summary-language` | Summary language (`en`, `zh`, `es`, `fr`, `de`, `it`, `pt`, `ru`, `ja`, `ko`, `ar`) |
  140. | `--no-llm` | Transcript only — skips optimize/translate/summarize, needs no API key |
  141. | `--no-video` | Don't keep the original video |
  142. | `--whisper-model` | `tiny` … `large`, default `base` |
  143. | `-o, --output-dir` | Where to write the Markdown, default `./temp` |
  144. | `--json` / `-q` | Machine-readable output / silence progress |
  145. #### AI provider settings for agents
  146. For CLI/agent use, configure the OpenAI-compatible provider with environment
  147. variables:
  148. ```bash
  149. export OPENAI_API_KEY="your_api_key_here"
  150. export OPENAI_BASE_URL="https://openrouter.ai/api/v1"
  151. export OPENAI_TRANSLATION_MODEL="gpt-4o" # optional
  152. ```
  153. For one-off CLI runs you can also pass `--api-key`, `--base-url`, and `--model`,
  154. but environment variables are safer because API keys do not end up in shell history.
  155. ### Codex App plugin
  156. The repo also ships a skills-only Codex plugin:
  157. ```text
  158. .codex-plugin/plugin.json
  159. skills/video-transcribe/SKILL.md
  160. ```
  161. This repository root is the plugin root. Import or install this folder as a local
  162. plugin in Codex App, then start a new task and select **AI Video Transcriber** from
  163. Plugins. Shipping the plugin files does not install the plugin automatically; after
  164. changing the plugin, refresh or reinstall it and start a new task so Codex reloads
  165. the skill. The skill wraps the same CLI pipeline above, so the machine running
  166. Codex still needs this repo's `venv` and `ffmpeg`.
  167. Codex App does not provide a plugin-specific settings panel for this skills-only
  168. plugin. To switch from OpenRouter to another OpenAI-compatible endpoint, update the
  169. environment variables available to the Codex task, or ask Codex to run the CLI with
  170. `--base-url` / `--model` for that specific run.
  171. This plugin intentionally does not bundle the local stdio MCP server. If you want
  172. Codex to call the `transcribe_video` MCP tool directly, register the MCP server
  173. separately as shown below.
  174. ### Claude Code skill
  175. The repo ships `.claude/skills/video-transcribe/SKILL.md`, so Claude Code picks it up
  176. automatically when you work in this directory — just ask it to transcribe a link. To
  177. use it from anywhere, copy the folder to `~/.claude/skills/`.
  178. ### MCP server (Claude Code, Claude Desktop, Codex)
  179. The project includes an optional stdio MCP server. It is not registered
  180. automatically; add it once per client.
  181. ```bash
  182. pip install "mcp>=2.0"
  183. # From the repository root:
  184. claude mcp add video-transcriber \
  185. -e OPENAI_API_KEY=your_api_key_here \
  186. -e OPENAI_BASE_URL=https://openrouter.ai/api/v1 \
  187. -- "$(pwd)/venv/bin/python" "$(pwd)/mcp_server.py"
  188. codex mcp add \
  189. --env OPENAI_API_KEY=your_api_key_here \
  190. --env OPENAI_BASE_URL=https://openrouter.ai/api/v1 \
  191. video-transcriber -- "$(pwd)/venv/bin/python" "$(pwd)/mcp_server.py"
  192. ```
  193. If you prefer editing Codex config directly, add this to `~/.codex/config.toml`:
  194. ```toml
  195. [mcp_servers.video-transcriber]
  196. command = "/abs/path/venv/bin/python"
  197. args = ["/abs/path/mcp_server.py"]
  198. [mcp_servers.video-transcriber.env]
  199. OPENAI_API_KEY = "your_api_key_here"
  200. OPENAI_BASE_URL = "https://openrouter.ai/api/v1"
  201. ```
  202. For Claude Desktop, add the same command and args to your Claude Desktop MCP
  203. configuration:
  204. ```json
  205. {
  206. "mcpServers": {
  207. "video-transcriber": {
  208. "command": "/abs/path/venv/bin/python",
  209. "args": ["/abs/path/mcp_server.py"],
  210. "env": {
  211. "OPENAI_API_KEY": "your_api_key_here",
  212. "OPENAI_BASE_URL": "https://openrouter.ai/api/v1"
  213. }
  214. }
  215. }
  216. }
  217. ```
  218. To change providers later, update the MCP client's saved environment variables
  219. or remove and re-add the MCP server with the new `OPENAI_BASE_URL` / model settings,
  220. then restart or reload the client if it keeps MCP servers running.
  221. Exposes one tool, `transcribe_video`, returning the transcript, summary, optional
  222. translation, file paths, and a `no_speech` flag. Verify the wiring with
  223. `venv/bin/python mcp_server.py --selftest`, then check client registration with
  224. `claude mcp list` or `codex mcp list`.
  225. > **`no_speech` matters:** when the source has no speech, the pipeline skips the LLM
  226. > entirely and returns empty text. Agents should report that rather than guessing at
  227. > the content — feeding an empty transcript to an LLM produces confident fabrications.
  228. <a id="api-reference"></a>
  229. ## 🔌 API Reference
  230. All endpoints are served from the same origin as the UI.
  231. | Method | Endpoint | Purpose |
  232. |--------|----------|---------|
  233. | `POST` | `/api/process-video` | Start a job — accepts either a URL or a multipart `file` |
  234. | `POST` | `/api/process-upload` | Upload-only alias, identical behavior |
  235. | `GET` | `/api/task-status/{task_id}` | Poll a job's current state |
  236. | `GET` | `/api/task-stream/{task_id}` | SSE stream of live progress updates |
  237. | `GET` | `/api/download/{filename}` | Download a result as an attachment (`.md` or media). Optional `?name=` sets a friendly filename |
  238. | `GET` | `/api/media/{filename}` | Stream media inline for the player — supports HTTP Range, so seeking works |
  239. | `DELETE` | `/api/task/{task_id}` | Cancel a running job and drop its record |
  240. | `POST` | `/api/models` | Proxy: list models from any OpenAI-compatible provider |
  241. | `GET` | `/api/tasks/active` | Active job counters (debugging) |
  242. <details>
  243. <summary><b>Form fields for <code>POST /api/process-video</code></b></summary>
  244. | Field | Type | Default | Description |
  245. |-------|------|---------|-------------|
  246. | `url` | string | `""` | Video/podcast URL. Omit when uploading a file |
  247. | `file` | file | – | Multipart upload. Takes precedence over `url` |
  248. | `summary_language` | string | `zh` | Target summary language code |
  249. | `download_video` | string | `1` | `0`/`false`/`no`/`off` disables the original video download |
  250. | `api_key` | string | `""` | Per-request API key; falls back to `OPENAI_API_KEY` |
  251. | `model_base_url` | string | `""` | Per-request OpenAI-compatible base URL |
  252. | `model_id` | string | `""` | Model to use; blank means server default |
  253. ```bash
  254. # Transcribe a URL, skipping the video download
  255. curl -X POST http://localhost:8000/api/process-video \
  256. -F "url=https://www.youtube.com/watch?v=VIDEO_ID" \
  257. -F "summary_language=en" \
  258. -F "download_video=0"
  259. ```
  260. </details>
  261. <a id="architecture"></a>
  262. ## 🛠️ Technical Architecture
  263. **Backend** — FastAPI · yt-dlp (download & subtitle extraction) · FFmpeg (audio extraction, video merge, upload normalization to mono 16 kHz) · Faster-Whisper (transcription) · OpenAI-compatible API (optimization, translation, summary)
  264. **Frontend** — vanilla HTML5/CSS3/ES6+ · Marked.js (Markdown rendering) · Font Awesome (icons) · SSE for live progress
  265. ### Processing Pipeline
  266. ```
  267. URL ──┬─→ probe subtitles ──found──→ parse VTT/SRT ─────────────┐
  268. │ │
  269. │ (in parallel, if "Keep original video" is on) ├─→ optimize
  270. └─→ download video (≤720p) ──→ extract audio ──→ Whisper ──┘ → translate*
  271. → summarize
  272. File ─→ normalize with FFmpeg ──→ Whisper ───────────────────────┘ → results
  273. (.txt skips straight to the text pipeline) (* when languages differ)
  274. ```
  275. ### Project Structure
  276. ```
  277. AI-Video-Transcriber/
  278. ├── backend/
  279. │ ├── main.py # FastAPI app, routes, task orchestration
  280. │ ├── pipeline.py # Pure helpers shared by web/CLI/MCP (incl. no-speech guard)
  281. │ ├── video_processor.py # yt-dlp: subtitles, audio, original video
  282. │ ├── transcriber.py # Faster-Whisper transcription
  283. │ ├── summarizer.py # Transcript optimization + summary
  284. │ ├── translator.py # Conditional translation
  285. │ └── llm_sanitize.py # Post-process LLM output (strip boilerplate)
  286. ├── static/
  287. │ ├── index.html # UI markup + styles
  288. │ └── app.js # Frontend logic, SSE, i18n
  289. ├── temp/ # Generated transcripts, summaries, media
  290. ├── Dockerfile
  291. ├── docker-compose.yml
  292. ├── .env.example
  293. ├── requirements.txt
  294. ├── install.sh
  295. ├── start.py # Startup script (--prod disables hot reload)
  296. ├── transcribe.py # Headless CLI (agents, scripts, cron)
  297. ├── mcp_server.py # MCP server exposing the transcribe_video tool
  298. ├── .codex-plugin/
  299. │ └── plugin.json # Codex App plugin manifest
  300. ├── skills/
  301. │ └── video-transcribe/ # Codex plugin skill wrapping the CLI
  302. └── .claude/skills/
  303. └── video-transcribe/ # Claude Code skill wrapping the CLI
  304. ```
  305. <a id="configuration"></a>
  306. ## ⚙️ Configuration Options
  307. ### Environment Variables
  308. All are optional — the app runs with defaults and accepts AI credentials from the UI.
  309. | Variable | Description | Default |
  310. |----------|-------------|---------|
  311. | `OPENAI_API_KEY` | API key (server-side default) | – |
  312. | `OPENAI_BASE_URL` | OpenAI-compatible endpoint | provider default |
  313. | `OPENAI_TRANSLATION_MODEL` | Model used for translation | `gpt-4o` |
  314. | `WHISPER_MODEL_SIZE` | Whisper model size | `base` |
  315. | `UPLOAD_MAX_MB` | Max upload size per file (MB) | `200` |
  316. | `VIDEO_MAX_HEIGHT` | Max height for the original video download | `720` |
  317. | `HOST` | Server address | `0.0.0.0` |
  318. | `PORT` | Server port | `8000` |
  319. | `PRODUCTION_MODE` | Set to `true` to disable hot reload (same as `--prod`) | – |
  320. ### Whisper Model Size Options
  321. | Model | Parameters | Speed | Memory |
  322. |-------|------------|-------|--------|
  323. | tiny | 39 M | Fast | ~150 MB |
  324. | base | 74 M | Medium | ~250 MB |
  325. | small | 244 M | Medium | ~750 MB |
  326. | medium | 769 M | Slow | ~1.5 GB |
  327. | large | 1550 M | Very slow | ~3 GB |
  328. All sizes are multilingual; `tiny`–`medium` also ship English-only variants.
  329. <a id="faq"></a>
  330. ## 🔧 FAQ
  331. <details>
  332. <summary><b>Does keeping the original video slow things down?</b></summary>
  333. Usually not much. The download runs concurrently with transcription and summarization and is only awaited at the very end, so it mostly hides behind work that was happening anyway. On the Whisper path it actually *saves* a download, because the audio is extracted from the video file instead of fetching the media twice.
  334. Downloads are capped at 720p by default — lower `VIDEO_MAX_HEIGHT` to save bandwidth, or turn the toggle off entirely for text-only jobs. If the video download fails, transcription still completes normally and the results simply omit the player.
  335. </details>
  336. <details>
  337. <summary><b>Does <code>temp/</code> grow over time?</b></summary>
  338. Yes. Transcripts, summaries, and downloaded videos are deliberately kept after a job finishes so you can still download them, and there is no automatic cleanup. Now that original videos are saved too, prune the directory periodically:
  339. ```bash
  340. # Delete generated files older than 7 days
  341. find temp -type f -mtime +7 ! -name 'tasks.json' -delete
  342. ```
  343. </details>
  344. <details>
  345. <summary><b>Why is transcription slow?</b></summary>
  346. Speed depends on video length, Whisper model size, and hardware. Use a smaller model (`tiny` or `base`) to speed it up. Note that videos with native subtitles skip Whisper entirely and finish in seconds.
  347. </details>
  348. <details>
  349. <summary><b>Which video platforms are supported?</b></summary>
  350. Everything yt-dlp supports — including YouTube, TikTok, Facebook, Instagram, X/Twitter, Bilibili, Youku, iQiyi, Tencent Video, Apple Podcasts, and SoundCloud.
  351. </details>
  352. <details>
  353. <summary><b>What local file types and size limits apply?</b></summary>
  354. Allowed extensions: `.txt`, `.mp3`, `.mp4`, `.m4a`, `.wav`, `.webm`, `.mkv`, `.ogg`, `.flac`. Default limit is **200 MB** per file — override with `UPLOAD_MAX_MB`.
  355. </details>
  356. <details>
  357. <summary><b>The AI features are unavailable — what now?</b></summary>
  358. They need an API key from any OpenAI-compatible provider. Enter it in the **AI Settings** panel in the UI (no restart needed), or set `OPENAI_API_KEY` for a server-side default. Without a key, transcription still works — Whisper runs locally — but optimization, translation, and summaries fall back to basic formatting.
  359. </details>
  360. <details>
  361. <summary><b>I get HTTP 500 errors. Why?</b></summary>
  362. Usually environment configuration rather than a code bug. Check that you:
  363. - Activated the virtualenv: `source venv/bin/activate`
  364. - Installed deps inside it: `pip install -r requirements.txt`
  365. - Configured an API key in **AI Settings**, or set `OPENAI_API_KEY`
  366. - Installed FFmpeg: `brew install ffmpeg` / `sudo apt install ffmpeg`
  367. - Freed port 8000, or changed `PORT`
  368. </details>
  369. <details>
  370. <summary><b>How do I deploy with Docker?</b></summary>
  371. **Prerequisites:** install Docker Desktop from https://www.docker.com/products/docker-desktop/ and make sure the service is running.
  372. ```bash
  373. git clone https://github.com/wendy7756/AI-Video-Transcriber.git
  374. cd AI-Video-Transcriber
  375. cp .env.example .env # edit for server-side defaults (optional)
  376. docker-compose up -d # recommended
  377. # Or manually
  378. docker build -t ai-video-transcriber .
  379. docker run -p 8000:8000 --env-file .env ai-video-transcriber
  380. ```
  381. **Common issues**
  382. - **Port conflict** — remap with `-p 8001:8000`
  383. - **Permission denied** — confirm Docker Desktop is running
  384. - **Build fails** — check disk space (~2 GB free) and network
  385. - **Container won't start** — inspect `docker logs <container_id>`
  386. **Useful commands**
  387. ```bash
  388. docker ps # running containers
  389. docker logs ai-video-transcriber-ai-video-transcriber-1 # logs
  390. docker-compose down # stop
  391. docker-compose build --no-cache # rebuild
  392. ```
  393. </details>
  394. <details>
  395. <summary><b>What are the memory requirements?</b></summary>
  396. **Docker:** ~128 MB idle, 500 MB–2 GB while processing, ~1.6 GB image. 4 GB+ RAM recommended.
  397. **Traditional:** ~50–100 MB for the FastAPI server, plus the Whisper model (see the table above), plus roughly 500 MB peak for processing.
  398. ```bash
  399. # Reduce memory usage
  400. WHISPER_MODEL_SIZE=tiny
  401. # Limit container memory
  402. docker run -m 1g -p 8000:8000 --env-file .env ai-video-transcriber
  403. # Monitor
  404. docker stats ai-video-transcriber-ai-video-transcriber-1
  405. ```
  406. </details>
  407. <details>
  408. <summary><b>Network connection errors or timeouts?</b></summary>
  409. Symptoms include "Unable to extract" or timeouts on download, API connection/DNS failures, and slow Docker pulls.
  410. 1. **Switch VPN/proxy** to a different server
  411. 2. **Check network stability**
  412. 3. **Wait 30–60 seconds** after changing network settings before retrying
  413. 4. **Verify custom endpoints** are reachable from your network
  414. 5. **Restart Docker Desktop** if container networking fails
  415. ```bash
  416. curl -I https://www.youtube.com/ # platform access
  417. curl -I https://openrouter.ai # AI provider
  418. docker pull hello-world # Docker Hub
  419. ```
  420. </details>
  421. <a id="languages"></a>
  422. ## 🎯 Supported Languages
  423. **Transcription** — 100+ languages via Whisper, with automatic language detection.
  424. **Summaries & Translation** — English, Chinese (Simplified), Japanese, Korean, Spanish, French, German, Italian, Portuguese, Russian, Arabic.
  425. **Interface** — English and Chinese, switchable from the top-right.
  426. <a id="performance"></a>
  427. ## 📈 Performance Tips
  428. **Hardware**
  429. - Minimum: 4 GB RAM, dual-core CPU
  430. - Recommended: 8 GB RAM, quad-core CPU
  431. - Ideal: 16 GB RAM, multi-core CPU, SSD
  432. **Processing time estimates**
  433. | Video Length | Subtitle Mode | Whisper Mode | Notes |
  434. |--------------|---------------|--------------|-------|
  435. | 1 minute | ~5 s | 30 s–1 min | Subtitle mode needs no audio download |
  436. | 5 minutes | ~10 s | 2–5 min | YouTube auto-captions trigger subtitle mode |
  437. | 15 minutes | ~15 s | 5–15 min | Most YouTube videos support subtitle mode |
  438. | 30+ minutes | ~20 s | 15–60 min | Podcasts/audio-only always use Whisper |
  439. Times assume **Keep original video** is off. With it on, subtitle-mode jobs are bounded by the video download rather than the transcript — the download overlaps the AI steps, so the added wall-clock is usually well under the download time itself.
  440. <a id="contributing"></a>
  441. ## 🤝 Contributing
  442. Issues and Pull Requests are welcome!
  443. 1. Fork the project
  444. 2. Create a feature branch (`git checkout -b feature/AmazingFeature`)
  445. 3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
  446. 4. Push to the branch (`git push origin feature/AmazingFeature`)
  447. 5. Open a Pull Request
  448. ## Acknowledgments
  449. - [yt-dlp](https://github.com/yt-dlp/yt-dlp) — powerful video downloading tool
  450. - [Faster-Whisper](https://github.com/guillaumekln/faster-whisper) — efficient Whisper implementation
  451. - [FastAPI](https://fastapi.tiangolo.com/) — modern Python web framework
  452. - [OpenAI](https://openai.com/) — intelligent text processing API
  453. ## 📞 Contact
  454. For questions or suggestions, please open an Issue or contact Wendy.
  455. ---
  456. ## 🚀 Try the Full Product — sipsip.ai
  457. This tool is the open-source part of **[sipsip.ai](https://sipsip.ai)**.
  458. The full product goes further:
  459. - 📧 **Daily email briefs** — follow your favorite creators and get an AI-curated digest in your inbox every morning
  460. - ⚡ Transcribe & summarize any video or podcast on demand
  461. - 🌐 Multi-language support across all features
  462. **Free to start** — no credit card required.
  463. ➡️ [sipsip.ai](https://sipsip.ai)
  464. ---
  465. ## More from the same developer
  466. - Recording a video? Try the [best free teleprompter](https://teleprompter.works) — use the browser version or download the [app version]((https://apps.apple.com/app/teleprompter-scrolling-scripts/id6767148844))for a better experience.
  467. - Growing a product on Pinterest? [GetPinFast](https://getpin.fast) is a Pinterest growth tool for more traffic and conversions.
  468. - Writing through your thoughts? [3 Pages Daily](https://3pagesdaily.com) helps you remember the past, make sense of the present, and shape what comes next.
  469. - Looking for side hustle or small business tools? [Clara Vale](https://claravale.studio) offers free templates, calculators, and planners for budgeting, finance, bookkeeping, and taxes.
  470. ---
  471. ⭐ If you find this project helpful, please consider giving it a star!

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.