Prosey

Prosey é uma ferramenta de CLI para baixar e exibir transcrições de vídeos do YouTube, para que você obtenha as informações que procura sem perder horas.

Os principais casos de uso são:

• Resumir um vídeo do YouTube e exibi-lo no CLI com um único comando (mais rápido).
• Ler legendas de vídeo, formatadas e organizadas em capítulos como no vídeo original (geralmente exige mais tempo).

Ambos os usos precisam de um assistente de IA no seu sistema (padrão: opencode, use prosey config para configurar o seu próprio).

Se detectarmos um realçador de sintaxe no seu sistema, você terá uma saída colorida agradável.

O Prosey também pode gerar ou armazenar o formato json nativo verbatim.

Recursos

Início rápido

Experimente imediatamente com npx:

npx @tacone/prosey 771PQEDeRmw
npx @tacone/prosey https://youtu.be/771PQEDeRmw --lang es -o transcript.txt

Instalação

Instale globalmente com seu gerenciador de pacotes favorito:

npm install -g @tacone/prosey
# ou
yarn global add @tacone/prosey
# ou
pnpm add -g @tacone/prosey
# ou
bun install -g @tacone/prosey

Depois use em qualquer lugar:

prosey 771PQEDeRmw

A partir do código-fonte

Usa Bun para desenvolvimento — scripts, gerenciamento de pacotes e execução direta do código-fonte TypeScript.

git clone https://github.com/tacone/prosey.git
cd prosey
bun install
bun run start -- 771PQEDeRmw

Uso

prosey [options] <video controls-url-or-id>
prosey read [options] <video controls-url-or-id>
prosey info [options] <video controls-url-or-id>
prosey summarize [options] <video controls-url-or-id>
prosey index
prosey render
prosey config
prosey help

summarize é o comando padrão, então prosey <id> executa o resumidor de IA. Use prosey read <id> para baixar e imprimir uma transcrição ricamente formatada.

O comando summarize busca uma transcrição, adiciona o prompt da seção de configuração [summarize] no início e envia o resultado para o comando de IA configurado.

O comando read baixa a transcrição e a imprime no stdout (texto simples, markdown ou JSON). Isso é útil quando você não precisa de processamento de IA.

O comando info mostra os metadados do vídeo (título, canal, duração, visualizações).

O comando index reconstrói o índice de documentos e o abre no navegador. O índice lista todos os resumos e transcrições armazenados no diretório de dados e é reconstruído automaticamente após cada execução de summarize/transcribe. Clicar no logotipo do Prosey em qualquer página de conteúdo navega de volta para ele.

O comando render regenera todas as páginas HTML a partir do markdown em cache (sem rede ou processamento de IA) e reescreve o índice.

O comando config abre seu arquivo de configuração no $EDITOR para edição. Se $EDITOR não estiver definido, o caminho do arquivo de configuração é impresso.

O comando help mostra a mensagem de ajuda, igual ao --help.

Exemplos

# Resumir (resumo com IA + formatação + realce de sintaxe)
prosey 771PQEDeRmw

# Resumir (igual ao acima)
prosey summarize 771PQEDeRmw

# Transcrever (resumo com IA + formatação + realce de sintaxe)
prosey read 771PQEDeRmw

# Mostrar metadados do vídeo
prosey info 771PQEDeRmw

# Editar configuração no $EDITOR
prosey config

# Listar idiomas disponíveis
prosey read https://youtu.be/771PQEDeRmw --list

# Especificar idioma
prosey read https://youtu.be/771PQEDeRmw --lang es

# Exibir JSON (sem transcrição com IA)
prosey read 771PQEDeRmw

# Exibir texto simples (sem transcrição com IA)
prosey read 771PQEDeRmw

# Salvar transcrição em arquivo
prosey read 771PQEDeRmw -o transcript.txt

Opções

Formato JSON

Quando --json é usado, a saída é um array de objetos:

[
  {
    "text": "♪ We're no strangers to love ♪",
    "offset": 18.64,
    "duration": 3.24,
    "timestamp": "00:18"
  }
]

timestamp está sempre presente no modo JSON. Os detalhes do vídeo são suprimidos (silenciosamente), pois JSON é dado estruturado.

Desenvolvimento

Este projeto usa Bun para desenvolvimento.

bun run typecheck   # Verificação TypeScript
bun run start       # Executa o CLI a partir do código-fonte
bun run test        # Executa testes unitários
bun run build       # Compila o bundle Node para bin/prosey

Antes de publicar no npm, bun run build é executado automaticamente pelo hook prepack, produzindo um bundle JS compatível com Node em bin/prosey.

Configuração

O Prosey lê a configuração de um arquivo TOML. A localização segue a Especificação XDG Base Directory (~/.config/prosey/config.toml), ou você pode definir a variável de ambiente PROSEY_CONFIG_PATH para usar um caminho personalizado.

O arquivo de configuração é criado automaticamente na primeira execução com valores padrão. Use --reset-config para restaurar os padrões a qualquer momento.

pager

Comando do paginador para saída de transcrições e resumos. O padrão é "auto", que detecta o primeiro disponível entre: bat -lmd --style plain → glow -p → mdcat -l -p → less. Defina um comando personalizado (ex.: "less -R") para substituir. A variável de ambiente PROSEY_PAGER tem precedência sobre esta configuração.

[summarize]

A seção [summarize] configura o comando summarize:

PROSEY_PAGER

Variável de ambiente para definir o comando do paginador. Tem precedência sobre o valor da configuração pager. Defina como "auto" ou vazio para usar a detecção automática.

Cache

Transcrições e resumos são armazenados em cache em /tmp/prosey/. Invocações repetidas para o mesmo vídeo e opções são instantâneas e funcionam offline. Use --no-cache para ignorar leituras de cache e forçar uma nova busca.

Ao executar prosey summarize, o comando é executado dentro do diretório de cache daquele vídeo. Isso impede que o agente de IA capture arquivos específicos do projeto como AGENTS.md ou CLAUDE.md da pasta atual e limita sua capacidade de modificar arquivos fora desse diretório.

Códigos de saída

Como funciona

O prosey usa a API Innertube do YouTube por meio da biblioteca youtube-transcript-plus. Não são necessárias chaves de API ou automação de navegador.

A ferramenta funciona tanto com legendas criadas manualmente quanto com transcrições geradas automaticamente (reconhecimento de fala do YouTube). A detecção automática percorre os idiomas na ordem fornecida pela resposta do player do YouTube.