BiliNote-MCP

Converte links de vídeo em notas Markdown geradas por IA

Documentação

VideoNote-Mcp

Link de vídeo → Notas em múltiplos formatos
Um link → uma nota · ponta a ponta ou desacoplado, qualquer combinação

Início rápido • Documentação • Casos reais • Mapa do pipeline • Gerenciamento de tarefas • Boas práticas • Como contribuir

O VideoNote-Mcp empacota todo o pipeline de "link de vídeo → notas em múltiplos formatos" como um MCP Server: forneça um link e ele conclui automaticamente download → transcrição de fala → compreensão de cenas → danmaku/comentários, gerando transcrições ou notas.

Repositório: HuangYincan/VideoNote-MCP.

Pode ser usado ponta a ponta (um link → uma nota) ou de forma desacoplada: ferramentas de geração, materiais, tarefas, processamento de mídia, etc., podem ser usadas conforme necessário. Não é necessário iniciar nenhum serviço de backend.

Início rápido

Configure o serviço MCP e comece a usar.

# 1) 注册独立 MCP（PyPI 已发布版本）
claude mcp add --scope user videonote -- uvx videonote@latest

# 2) 在终端配置转写 / 平台登录；默认笔记流程无需 LLM Key
uvx videonote@latest setup

# 3) 重启或重连 MCP，然后发送视频链接

Clientes MCP compatíveis com JSON também podem usar:

{
  "mcpServers": {
    "videonote": {
      "type": "stdio",
      "command": "uvx",
      "args": ["videonote@latest"]
    }
  }
}

[!NOTE] O uvx videonote@latest padrão contém apenas dependências básicas (transcrição fast-whisper + legendas oficiais da plataforma), sem mecanismos opcionais. No macOS, ao usar o mlx-whisper com Apple GPU, o registro do MCP e o setup do terminal devem incluí-lo (o --with deve ser escrito antes do nome da ferramenta):
claude mcp add --scope user videonote -- uvx --with mlx-whisper videonote@latest
uvx --with mlx-whisper videonote@latest setup
Já em clientes JSON, insira "--with", "mlx-whisper" no início de args:
{
  "mcpServers": {
    "videonote": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--with", "mlx-whisper", "videonote@latest"]
    }
  }
}
O funasr (ideal para chinês) segue o mesmo princípio, basta trocar por --with funasr --with torch.

[!TIP] Quatro formas de instalação, detalhes de configuração, atualização e segurança em docs/04-使用手册.md.

Formatos de exportação

Legendas: suporta SRT, VTT e JSON, ideal para salvar linhas do tempo ou importar para outras ferramentas.
Notas em Markdown: podem ser organizadas a partir de transcrições, cenas e comentários para leitura e edição contínua.
LaTeX / Typst: o pacote inclui modelos como Math Note, English Article e zju-lab, que podem ser listados, lidos ou copiados para novos diretórios no cliente MCP.
A cópia de modelos não sobrescreve diretórios existentes. Compiladores, fontes e dependências de LaTeX / Typst precisam estar preparados na máquina local; o MCP fornece materiais e modelos, mas não compila PDFs automaticamente.

Instruções completas de exportação em 使用手册.

Documentação

Instalação / configuração / uso / variáveis de ambiente / atualização / segurança e outras instruções completas foram arquivadas em docs/ (o README mantém apenas uma visão geral):

Índice de documentação
Design de arquitetura · Diagrama de arquitetura editável
Manual de uso — instalação (4 formas) · configuração (assistente setup + CLI) · variáveis de ambiente · atualização · segurança
Registro de alterações

Casos reais

Dois casos reais ponta a ponta: um gera diretamente um PDF LaTeX mathnote via assistente de conversa, e outro usa geração totalmente automática com LLM para produzir Markdown portátil.

Caso 1 · agent_direct + LaTeX mathnote (vídeo DeepSeek-V4)

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

Um vídeo + quatro tipos de materiais externos (artigos / relatórios técnicos / anúncios oficiais / coleções open source) → geração direta pelo assistente de conversa de notas refinadas, com saída em PDF LaTeX mathnote (modelo de caligrafia chinesa):

Página1	Página2	Página3

Sem chave de LLM: organiza notas a partir de transcrições, quadros de vídeo e comentários
Integração cruzada de múltiplas fontes: vídeo × artigos × relatórios técnicos × listas open source
Refinamento preserva o original: note.md / note_original.md em duplicidade
PDF LaTeX mathnote: correção adaptativa de fontes ausentes / quebras de linha / deduplicação de referências

Registro completo do processo em examples/agent-direct-deepseek-v4-mathnote/README.md.

Caso 2 · Geração totalmente automática com LLM + Markdown portátil (múltiplos vídeos em paralelo)

Prompt mínimo (3 links do Bilibili + diretório de saída, sem nenhum parâmetro explicado) → totalmente automático executa verificação de ambiente → reconhecimento de links → descoberta de provedor/modelo → confirmação de parâmetros → múltiplos vídeos em paralelo → refinamento pós-geração baseado em legendas, produzindo 3 notas portáteis refinadas (note.md + capturas de tela Assets/ + seção "opiniões do público", mantendo note_original.md para comparação).

IELTS: quebrando mitos + análise das quatro seções (ouvir/ler/escrever/falar) + 179 palavras de alta frequência + 15 estruturas lógicas
Medicina legal: médico legista com 43 anos de experiência "analisa" o contraste entre filmes e realidade, refinado e expandido para 12 seções
Transformer: explicação detalhada do mecanismo de autoatenção, 18 capturas de tela distribuídas ao longo da linha do tempo da aula

Registro completo do processo em examples/note-generation-example/README.md.

Mapa do pipeline

Linhas sólidas representam o fluxo principal: um prepare_note_material gera materiais, e o assistente de conversa atual organiza as notas; generate_note é o plano de contingência (usado quando o assistente de conversa não consegue ver imagens, acionando o LLM configurado). Linhas tracejadas representam capacidades opcionais (compreensão de vídeo / danmaku e comentários). Detalhes de cada etapa em docs/02-架构设计.md.

Gerenciamento de tarefas

Cada tarefa tem uma pasta note_results/{task_id}/: raw/ (mídia baixada) + gen/ (transcrição/notas/quadros/exportação) + arquivos de controle; índice global de tarefas na tabela SQLite video_tasks (com títulos semânticos). list_tasks enumera todas as tarefas (identificadas por títulos semânticos), cleanup(task_id, dry_run=True) consulta antes de limpar, cleanup limpa por tarefa / globalmente (mantém configuração e modelos por padrão), health_check verifica se FFmpeg / banco de dados / whisper estão prontos.

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

Ferramenta	Descrição	Tipo
`list_tasks`	Lista todas as tarefas (índice global, com títulos semânticos)	Ferramenta MCP
`cleanup`	Limpa por tarefa (informe `task_id`) / limpeza global (restauração de fábrica, sem informar)	Ferramenta MCP
`health_check`	Status de prontidão de FFmpeg / banco de dados / whisper	Ferramenta MCP

Boas práticas

Estudo e preparação para provas: ponta a ponta + compreensão de vídeo + otimização posterior baseada em legendas, para dominar o conteúdo do curso.
Atas de reunião: process_media(action="merge") mescla gravações segmentadas → process_media(action="diarize") separação de falantes → estilo meeting_minutes.
Leitura aprofundada de palestras: após a geração ponta a ponta, refine com base nas legendas completas e complete detalhes por capítulo.
Análise de vídeos: ative a integração de danmaku + comentários, com a nota contendo a seção "opiniões do público".
Caminho padrão: um link usa prepare_note_material, e o assistente de conversa atual organiza as notas; use generate_note apenas quando não for possível ver imagens ou quando o usuário solicitar um LLM configurado. Para apenas processamento de mídia, use process_media.
Casos reais: registros completos dos processos em examples.

Como contribuir

Sugestões, Issues e Pull Requests são bem-vindos. Ambiente de desenvolvimento, comandos de teste, estratégia de branches e navegação no código em CONTRIBUTING.md.

Agradecimentos

Glama: pela inclusão do servidor MCP
LINUX DO: uma nova comunidade ideal
Todas as dependências open source e a inspiração dos projetos upstream do pipeline