Douyin Link Transcription and Speaking Script Organization

Automatically parse Douyin share links, generate verbatim transcripts locally, and organize them into usable speaking scripts.

This project is maintained as a continuation of yzfly/douyin-mcp-server; it retains the original Apache-2.0 license.

✨ Features

• 🎬 Watermark-free Videos - Get high-quality watermark-free video download links

• 🛟 Automatic Fallback - Uses shared Playwright to capture signed audio when HTTP parsing fails

• 🎙️ Local Speech Recognition - faster-whisper-medium / CPU int8, no ASR API consumption

• ✍️ Speaking Script Organization - DeepSeek removes repetition, adds punctuation and structure, preserving the original meaning

• 🌐 WebUI - Modern browser interface, no command line needed

• 🔌 MCP Integration - Supports AI applications like Claude Desktop

Related MCP server: Douyin Video Analysis MCP

Project Structure

assets/                 预览图和发布用 skill 包
douyin_mcp_server/      Python 核心包
scripts/                命令行入口
skills/douyin-video/    可复用的工作流说明
tests/                  单元测试
web/                    FastAPI WebUI

📦 Usage

🌐 WebUI (Recommended)

The simplest way to use it - just open it in your browser.

Quick Start

# 1. 克隆你自己的仓库
git clone <your-repository-url>
cd douyin-mcp-server

# 2. 安装依赖
uv sync --extra web

# 3. 启动服务
uv run python web/app.py

Open your browser and visit http://localhost:8080

Configure DeepSeek API Key

There are two ways to configure the API Key:

Method 1: Configure in the browser

1. Open the WebUI page

2. Click the "API Key Not Configured" button at the top

3. Enter the API Key in the popup and save

4. The API Key is stored locally in the browser and is only sent to the local service with extraction requests

Method 2: Environment variable

export DOUYIN_DEEPSEEK_API_KEY="<your-deepseek-api-key>"
uv run python web/app.py

Local ASR does not require a key; the DeepSeek Key is only used for the final speaking script organization step.

Feature Description

Usage Steps

1. Paste Link - Paste the share link into the input box

2. Click Button - Choose "Get Info" or "Extract Transcript"

3. View Results - The video info and extracted transcript appear on the right

4. Export - Copy the transcript or download the Markdown file

🚀 MCP Server

Use it in MCP-supported applications like Claude Desktop and Cherry Studio.

Configuration Method

Edit the MCP configuration file and add:

{
  "mcpServers": {
    "douyin-mcp": {
      "command": "uvx",
      "args": ["douyin-mcp-server"],
      "env": {
        "DOUYIN_DEEPSEEK_API_KEY": "<your-deepseek-api-key>"
      }
    }
  }
}

DOUYIN_DEEPSEEK_API_KEY should only be placed in the runtime environment, not written into the repository, output files, or run reports.

Available Tools

Conversation Example

用户：帮我提取这个视频的文案 https://v.douyin.com/xxxxx/

Claude：我来帮你提取视频文案...
[调用 extract_douyin_text 工具]
提取完成，文案内容如下：
...

🛠️ Command Line Tools

Suitable for developers and batch processing scenarios.

Installation

git clone https://github.com/yzfly/douyin-mcp-server.git
cd douyin-mcp-server
uv sync

Command Description

# 查看帮助
uv run python scripts/douyin_downloader.py --help

# 获取视频信息（无需 API）
uv run python scripts/douyin_downloader.py -l "分享链接" -a info

# 下载无水印视频
uv run python scripts/douyin_downloader.py -l "分享链接" -a download -o ./videos

# 提取文案（本地 ASR；整理阶段需要 DOUYIN_DEEPSEEK_API_KEY）
export DOUYIN_DEEPSEEK_API_KEY="<your-deepseek-api-key>"
uv run python scripts/douyin_downloader.py -l "分享链接" -a extract -o ./output

Output Format

output/
└── 7600361826030865707/
    ├── audio.m4a          # 已校验的完整音频
    ├── transcript-raw.md  # 本地 ASR 原始逐字稿
    ├── copy.md            # DeepSeek 整理后的口播
    ├── metadata.json
    └── run-report.json    # 五阶段状态和验证证据

📋 System Requirements

🔧 Technical Details

Fixed Workflow

1. HTTP parses the share link; automatically falls back to Playwright on failure.

2. HTTP branch downloads the video; browser branch downloads the signed audio via Range requests.

3. HTTP branch uses FFmpeg to extract audio; browser branch uses ffprobe to verify complete audio.

4. Local faster-whisper-medium / CPU int8 generates a timestamped verbatim transcript.

5. DeepSeek organizes it into a speaking script and writes it to run-report.json.

📝 Changelog

v1.5.0 (Current Workstation Version)

• HTTP parsing automatically falls back to shared Playwright

• Uses local faster-whisper-medium / CPU int8, ASR no longer depends on cloud APIs

• Uses DeepSeek V4 Flash to organize speaking scripts

• Fixed output of audio, raw verbatim transcript, organized script, metadata, and run report

v1.4.1

• 🔧 MCP Server Fix - API_KEY now correctly maps to the SiliconFlow key, consistent with the documentation; also compatible with the legacy DASHSCOPE_API_KEY configuration

• ♻️ Restored Tools - Restored the recognize_audio_file / recognize_audio_url tools and the context parameter of extract_douyin_text

• 🛡️ WebUI Security Hardening - The download endpoint no longer proxies arbitrary URLs, and now listens on localhost only by default

• ⚡ WebUI Performance - Transcript extraction no longer blocks other requests

• 📦 Dependency Slimming - WebUI dependencies are now optional (pip install "douyin-mcp-server[web]")

v1.4.0

• 🌐 WebUI - Added a browser-based interface

• 🔑 Browser-based API Key Configuration - No environment variable needed

• 📑 Large File Support - Automatically processes long audio in segments

v1.3.0

• ✨ Claude Code Skill support

• 📄 Markdown format output

v1.2.0

• 🔄 API upgrade

v1.0.0

• 🎉 Initial release

⚠️ Disclaimer

• This project is for learning and research purposes only

• Users must comply with applicable laws and regulations

• Use for infringing intellectual property rights is prohibited

• The author is not liable for any losses arising from the use of this project

📄 License

Apache License 2.0

🤝 Contributing

Before submitting an Issue or Pull Request, please read CONTRIBUTING.md. Report security issues privately as described in SECURITY.md.

Before publishing to your own GitHub repository, fill in the project.urls field in pyproject.toml with your repository address, and modify the project name and author information as needed.

Upstream Source

Original project author: yzfly (GitHub).