Douyin 링크 전사 및 구술 정리

Douyin 공유 링크에서 미디어를 자동으로 파싱하고, 로컬에서 자막을 생성한 후 사용 가능한 구술 대본으로 정리합니다.

이 프로젝트는 yzfly/douyin-mcp-server를 기반으로 계속 유지보수됩니다. 원 프로젝트의 Apache-2.0 라이선스를 유지합니다.

✨ 기능 특징

• 🎬 워터마크 없는 영상 - 고품질 워터마크 없는 영상 다운로드 링크 획득

• 🛟 자동 다운그레이드 - HTTP 파싱 실패 시 공유 Playwright로 서명된 오디오 캡처

• 🎙️ 로컬 음성 인식 - faster-whisper-medium / CPU int8, ASR API 불필요

• ✍️ 구술 정리 - DeepSeek가 중복 제거, 문장 부호 및 구조 보완, 원래 의미 유지

• 🌐 WebUI - 현대적인 브라우저 인터페이스, 명령줄 불필요

• 🔌 MCP 통합 - Claude Desktop 등 AI 애플리케이션 지원

Related MCP server: Douyin Video Analysis MCP

프로젝트 구조

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

📦 사용 방법

🌐 WebUI (추천)

가장 간단한 사용 방식으로, 브라우저를 열면 바로 사용할 수 있습니다.

빠른 시작

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

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

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

브라우저를 열고 http://localhost:8080 에 접속하세요.

DeepSeek API Key 설정

API Key를 설정하는 방법은 두 가지입니다.

방법 1: 브라우저 내 설정

1. WebUI 페이지를 엽니다.

2. 상단의 「API 미설정」 버튼을 클릭합니다.

3. 팝업에서 API Key를 입력하고 저장합니다.

4. API Key는 브라우저 로컬에 저장되며, 추출 요청 시에만 로컬 서비스로 전송됩니다.

방법 2: 환경 변수

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

로컬 ASR은 키가 필요 없습니다. DeepSeek Key는 마지막 단계의 구술 정리에만 사용됩니다.

기능 설명

사용 단계

1. 링크 붙여넣기 - 공유 링크를 입력란에 붙여넣습니다.

2. 버튼 클릭 - 「정보 가져오기」 또는 「텍스트 추출」을 선택합니다.

3. 결과 확인 - 오른쪽에 영상 정보와 추출된 텍스트가 표시됩니다.

4. 내보내기 - 텍스트를 복사하거나 Markdown 파일을 다운로드합니다.

🚀 MCP Server

Claude Desktop, Cherry Studio 등 MCP를 지원하는 애플리케이션에서 사용합니다.

설정 방법

MCP 설정 파일을 편집하여 다음을 추가합니다.

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

DOUYIN_DEEPSEEK_API_KEY는 실행 환경에만 배치하고, 저장소, 출력 파일 또는 실행 보고서에는 기록하지 마세요.

사용 가능한 도구

대화 예시

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

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

🛠️ 명령줄 도구

개발자 및 일괄 처리 시나리오에 적합합니다.

설치

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

명령 설명

# 查看帮助
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/
└── 7600361826030865707/
    ├── audio.m4a          # 已校验的完整音频
    ├── transcript-raw.md  # 本地 ASR 原始逐字稿
    ├── copy.md            # DeepSeek 整理后的口播
    ├── metadata.json
    └── run-report.json    # 五阶段状态和验证证据

📋 시스템 요구 사항

🔧 기술 설명

고정 워크플로우

1. HTTP로 공유 링크 파싱. 실패 시 자동으로 Playwright로 다운그레이드.

2. HTTP 분기는 영상 다운로드. 브라우저 분기는 Range로 서명된 오디오 다운로드.

3. HTTP 분기는 FFmpeg로 오디오 추출. 브라우저 분기는 ffprobe로 전체 오디오 검증.

4. 로컬 faster-whisper-medium / CPU int8로 타임스탬프가 포함된 자막 생성.

5. DeepSeek가 구술 대본으로 정리하고 run-report.json에 기록.

📝 업데이트 로그

v1.5.0 (현재 워크스테이션 버전)

• HTTP 파싱 실패 시 공유 Playwright로 자동 다운그레이드

• 로컬 faster-whisper-medium / CPU int8 사용, ASR이 더 이상 클라우드 API에 의존하지 않음

• DeepSeek V4 Flash로 구술 대본 정리

• 출력 오디오, 원본 자막, 정리된 대본, 메타데이터 및 실행 보고서 고정 출력

v1.4.1

• 🔧 MCP Server 수정 - API_KEY가 이제 문서와 일치하게 실리콘플로우 키에 올바르게 대응. 이전 버전 DASHSCOPE_API_KEY 설정도 호환

• ♻️ 도구 복원 - recognize_audio_file / recognize_audio_url 도구 및 extract_douyin_text의 context 매개변수 복원

• 🛡️ WebUI 보안 강화 - 다운로드 인터페이스가 더 이상 임의 URL을 프록시하지 않으며, 기본적으로 로컬에서만 수신

• ⚡ WebUI 성능 - 텍스트 추출이 더 이상 다른 요청을 차단하지 않음

• 📦 의존성 간소화 - WebUI 의존성을 선택 설치로 변경 (pip install "douyin-mcp-server[web]")

v1.4.0

• 🌐 WebUI - 브라우저 시각화 인터페이스 추가

• 🔑 브라우저에서 API Key 설정 - 환경 변수 불필요

• 📑 대용량 파일 지원 - 긴 오디오 자동 분할 처리

v1.3.0

• ✨ Claude Code Skill 지원

• 📄 Markdown 형식 출력

v1.2.0

• 🔄 API 업그레이드

v1.0.0

• 🎉 최초 출시

⚠️ 면책 조항

• 이 프로젝트는 학습 및 연구 목적으로만 사용됩니다.

• 사용자는 관련 법규를 준수해야 합니다.

• 지식 재산권을 침해하는 행위는 금지됩니다.

• 저자는 이 프로젝트 사용으로 발생하는 손실에 대해 책임을 지지 않습니다.

📄 라이선스

Apache License 2.0

🤝 기여

Issue 또는 Pull Request를 제출하기 전에 CONTRIBUTING.md를 읽어주세요. 보안 문제는 SECURITY.md의 방식대로 비공개로 보고해 주세요.

자신의 GitHub 저장소에 배포하기 전에 pyproject.toml의 project.urls를 자신의 저장소 주소로 채우고, 필요에 따라 프로젝트 이름과 작성자 정보를 수정하세요.

업스트림 출처

원 프로젝트 작성자: yzfly (GitHub).