VideoNote-Mcp는 「동영상 링크 → 다중 형식 노트」 전체 파이프라인을 MCP Server + Claude Code Skill로 패키징합니다: agent에게 링크 하나를 주면, 자동으로 다운로드 → 음성 전사 → 화면 이해 → 댓글/코멘트 → AI 요약을 완료하고, 스크린샷이 포함되어 전체를 옮길 수 있는 휴대용 노트를 돌려줍니다.

저장소: HuangYincan/VideoNote-MCP.

이 프로젝트는 엔드투엔드로 사용할 수 있을 뿐만 아니라(링크 하나 → 노트 한 편), 분리해서도 사용할 수 있습니다: 파이프라인의 각 단계(다운로드 / 전사 / 프레임 추출 / 댓글 / 요약 / 내보내기 / 향상 / 정리)는 모두 독립적인 MCP 도구이므로, 특정 단계만 사용하거나 동영상 내용만 파악하고 싶을 때도 충족할 수 있습니다. 백엔드 서비스를 시작할 필요가 없습니다.

⚡ 빠른 시작

# 1) 一条命令装好 Skill + MCP（插件 marketplace，uvx 自动更新）
claude plugin marketplace add HuangYincan/VideoNote-MCP
claude plugin install videonote@videonote

# 2) 安装时 Claude Code 会逐项提示默认值（风格/转写引擎/视频理解/评论等）；
#    装完在会话里跑配置向导收尾：
/videonote-setup

# 3) （可选）LLM-Key/B 站扫码/CLI向导
# ! videonote setup

# 4) 重启会话，对 agent 说「帮我给这个视频做笔记」+ 链接

[!TIP] 네 가지 설치 방법, 구성 세부 사항, 업데이트 및 보안은 [docs/04-사용자 매뉴얼.md](docs/04-사용자 매뉴얼.md)를 참조하세요.

Related MCP server: tldw-mcp

📚 문서

설치 / 구성 / 사용 / 환경 변수 / 업데이트 / 보안 등 전체 설명은 docs/에 정리되어 있습니다(README에는 개요만 유지):

• [📇 문서 색인](docs/00-문서 색인.md)

• [🏗️ 아키텍처 설계](docs/02-아키텍처 설계.md)

• [📖 사용자 매뉴얼](docs/04-사용자 매뉴얼.md) —— 설치(4가지 방법) · 구성(setup 마법사 + CLI) · 환경 변수 · 업데이트 · 보안

• 📜 업데이트 로그

🎬 실제 사례

두 가지 엔드투엔드 실제 사례: 하나는 AGENT 직접 생성을 통해 LaTeX mathnote PDF를 출력하고, 다른 하나는 완전 자동 LLM 생성을 통해 휴대용 Markdown을 생산합니다.

사례 1 · agent_direct + LaTeX mathnote(DeepSeek-V4 동영상)

출처: 【闪客】深入解读 DeepSeek V1~V4！男女老少都听得懂～

동영상 하나 + 네 가지 유형의 외부 자료(논문 / 기술 보고서 / 공식 계정 발표 / 오픈소스 모음) → AGENT 직접 생성으로 정제된 노트를 만들고, LaTeX mathnote PDF(중국어 서체 템플릿)를 출력합니다:

하이라이트: agent_direct 전체 프로세스(LLM key 없이, Agent가 전사 + 프레임 이미지 + 댓글을 읽고 직접 노트 작성) · 다중 소스 교차 통합(동영상 × 논문 × 기술 보고서 × 오픈소스 목록) · 정제 시 원본 보존(note.md / note_original.md 이중 보관) · LaTeX mathnote PDF(글꼴 누락 / 줄바꿈 넘침 / 인용 중복 자동 수정). 전체 과정 기록은 examples/agent-direct-deepseek-v4-mathnote/README.md를 참조하세요.

사례 2 · 완전 자동 LLM 생성 + 휴대용 Markdown(다중 동영상 병렬)

극도로 간단한 Prompt(B站 링크 3개 + 출력 디렉터리, 매개변수 하나도 설명하지 않음) → 완전 자동으로 환경 검사 → 링크 인식 → 공급업체/모델 발견 → 매개변수 확인 → 다중 동영상 병렬 → 생성 후 자막 기반 정제를 거쳐 3개의 정제된 휴대용 노트(note.md + Assets/ 스크린샷 + 「시청자 의견」 섹션, note_original.md는 비교용으로 보존)를 생산합니다.

• 雅思: 오해 극복 + 듣기/읽기/쓰기/회화 네 과목 분해 + 179개 고빈도 시험 단어 + 15개 논리 프레임워크

• 法医: 43년 경력 법의관이 영화와 현실을 대조하며 분석, 정제 후 12개 절로 확장

• Transformer: 자기 주의 메커니즘 상세 해설, 강의 타임라인에 따라 18장의 스크린샷 배치

전체 과정 기록은 examples/note-generation-example/README.md를 참조하세요.

🗺️ 파이프라인 지도

flowchart LR
    A["视频链接"] --> B["下载音视频<br/>+ 平台字幕"]
    B --> C["语音转写<br/>或直接用平台字幕"]
    B -. 可选 .-> D["逐帧画面理解<br/>关键帧 → 网格图"]
    B -. 可选 .-> E["弹幕 + 评论区"]
    C --> F["素材包<br/>转写 · 帧 · 评论"]
    D -.-> F
    E -.-> F
    F --> G["AI 总结 → Markdown 底稿<br/>正文 + 截图 + 「观众观点」"]
    G --> O1["便携笔记<br/>note.md + Assets/"]
    G --> O2["字幕导出<br/>SRT · VTT · JSON"]
    G -. Agent 生成 .-> O3["创意格式<br/>思维导图 · 闪卡 · LaTeX · typst"]
    G -. 可选 .-> O4["基于完整字幕精修<br/>保留原版对比"]

0 🔄 엔드투엔드 전체 프로세스

엔드투엔드 모드는 링크 하나만 주면 됩니다: generate_note가 비동기로 전체 파이프라인을 실행하고 task_id를 반환합니다. 가벼운 get_task_status 스냅샷 폴링으로 SUCCESS/FAILED/CANCELLED까지 확인합니다(단일 프로세스에서 최대 3개의 진행 중 작업, 같은 메시지에서 병렬 제출 금지). cancel_note는 협력적 취소입니다. 「AGENT 직접 생성」은 prepare_note_material을 사용합니다 — 자료 패키지만 준비하고 구성된 LLM을 호출하지 않으며, agent가 직접 전사, 이미지, 댓글을 읽고 노트를 작성합니다.

1 📥 다운로드 및 플랫폼 파싱

inspect_video는 플랫폼을 인식합니다(bilibili / youtube / douyin / tiktok / kuaishou / local; 내장 6개 플랫폼 외에는 platform:"generic"을 반환하고 자동으로 yt-dlp 범용 추출을 통해 1800+ 사이트를 지원) + 링크 유효성 검사(유효하지 않으면 바로 이유 제공) + B站 분할 영상 / YouTube 재생 목록을 각 에피소드별로 독립 제출 가능한 url로 분리합니다(다운로드하지 않음). 플랫폼 Cookie는 ! videonote login bilibili / ! videonote setup을 통해 처리하며, MCP를 통해 전달하지 마세요. 플랫폼 자막(B站 AI 자막 포함)은 generate_note 내부에서 우선 사용되며, 독립 도구는 없습니다.

2 🎙 음성 전사(ASR)

음성 전사(ASR)는 generate_note 내부에서 완료됩니다: 플랫폼 자막(B站 AI 자막 포함)을 우선 사용하고, 자막이 없으면 전사합니다. 엔진 선택 가능: fast-whisper(로컬) / groq / bcut / kuaishou(클라우드) / mlx-whisper(macOS Apple Silicon GPU) / funasr(중국어 최적, VAD + 자동 문장 부호). 엔진과 모델 관리는 CLI를 통해 진행: ! videonote transcriber set/download; 상태 확인은 get_config().

3 🖼️ 동영상 화면 이해(프레임 추출)

generate_note는 동영상 이해 매개변수를 직접 지원합니다: video_understanding=True + video_interval(기본 6초) + grid_size(기본 [3,3]), 그리드 이미지를 멀티모달 LLM에 보내 화면을 「봅니다」.

4 💬 댓글과 코멘트

generate_note에 include_comments=True + comments_limit(기본 20)을 추가하면 댓글 도배와 댓글란 고빈도 의견을 노트에 정리하고, 「시청자 의견」 섹션을 추가합니다(B站 SESSDATA 필요; 수집 실패 시 작업을 차단하지 않음).

5 ✍️ AI 요약과 노트

9가지 스타일 지원: minimal / detailed / academic / tutorial / xiaohongshu / life_journal / task_oriented / business / meeting_minutes; format=["screenshot"]은 휴대용 노트를 생산합니다(note.md + Assets/, 상대 참조로 전체 이동 가능). 공급업체/모델/전사기 구성은 모두 CLI로 진행(! videonote providers set / ! videonote transcriber set), 읽기 전용 확인은 get_config(). agent_direct는 AGENT가 직접 생성합니다.

6 📤 다중 형식 내보내기

기계적 형식은 export_transcript(srt / vtt / json)를 사용합니다 — 결정적 렌더링(타임라인 변환), LLM을 소모하지 않으며, file:// 경로를 반환합니다. 창의적 형식(마인드맵 / 플래시카드 / LaTeX / typst / 사용자 정의 템플릿)은 Agent가 MD 초안 + SKILL 템플릿 기반으로 생성합니다(LaTeX 내장 Math Note / English Article 템플릿: 수학/이공계 노트 스타일, 영어 문서/발표 개요 스타일; typst 내장 zju-lab 템플릿: 이공계 노트/실험 보고서/논문 스타일, ZJU 교표 포함).

7 🎛️ 오디오 향상

merge_audio는 여러 녹음 / 회의 분할 / 여러 로컬 동영상을 16kHz mono wav로 병합한 후 전사합니다. 오디오 전처리(16kHz 정규화 + 1800초 초과 시 자동 분할, 선택적 노이즈 제거)는 기본 꺼짐, 하드 의존성 없음. diarize_media는 화자 분리를 수행합니다(pyannote 선택적 중의존성, HF_TOKEN + 모델 승인 필요).

8 🗂️ 작업 관리와 정리

각 작업마다 폴더 하나 note_results/{task_id}/: raw/(다운로드 미디어) + gen/(전사/노트/프레임/내보내기) + 제어 파일; 전역 작업 색인은 SQLite video_tasks 테이블(의미론적 제목 포함). list_tasks는 모든 작업을 열거하고(의미론적 제목으로 인식), cleanup_note(dry_run=True)는 먼저 확인 후 정리, cleanup_note / cleanup_all은 작업별 / 전역 정리(기본적으로 구성과 모델 보존), health_check는 FFmpeg / 데이터베이스 / whisper 준비 상태를 확인합니다.

flowchart TB
    DATA["data/ 数据根"] --> R["note_results/ 任务目录"]
    DATA --> DB[("video_note.db<br/>SQLite 全局任务索引")]
    R --> T1["任务 A<br/>note_results/{task_id}/"]
    R --> T2["任务 B<br/>…"]
    R --> T3["任务 C<br/>…"]
    T1 --> RAW["raw/ 原始材料<br/>音视频 · 封面"]
    T1 --> GEN["gen/ 生成材料"]
    T1 --> CTRL["status.json · result.json · manifest.json"]
    GEN --> T1A["transcript.json 转写全文"]
    GEN --> T1B["note.md 成稿笔记"]
    GEN --> T1C["Assets/ 笔记内截图"]
    GEN --> T1D["frames/ 关键帧原图"]
    GEN --> T1E["srt / vtt / json 字幕导出"]
    DB -. 索引 .-> T1

🏆 모범 사례

• 학습 및 시험 준비: 엔드투엔드 + 동영상 이해 + 자막 기반 후속 최적화로 강의를 완전히 이해.

• 회의록: merge_audio로 분할 녹음 병합 → diarize_media 화자 분리 → meeting_minutes 스타일.

• 강의 정독: 엔드투엔드 생성 후, agent가 전체 자막을 기반으로 정제하고 장별로 세부 내용 보완.

• 동영상 감상: 댓글 + 코멘트 통합 활성화, 노트에 「시청자 의견」 섹션 포함.

• 엔드투엔드: 링크 하나는 generate_note 사용(다운로드/전사/요약/댓글 전체 프로세스 내부 완료); 자료만 준비하려면 prepare_note_material 사용.

• 실제 사례: 전체 사례 과정 기록은 examples 참조.

🤝 기여 방법

• 기능 브랜치 → PR → dev(CI 스모크 테스트 통과 필수); dev 안정화 후 PR → main(보호 브랜치, review 필요).

• 프로세스, 브랜치 명명 및 커밋 전 자가 점검은 CONTRIBUTING.md 참조.

🙏 감사의 말

커뮤니티와 모든 기여자분들께 감사드리며, MCP server를 등록해 주신 Glama, 그리고 모든 오픈소스 의존성과 상류 파이프라인 프로젝트의 영감에 감사드립니다.