Prosey

Prosey é uma ferramenta de linha de comando 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 na CLI com um único comando (mais rápido).
• Ler as legendas do vídeo, formatadas e organizadas em capítulos como no vídeo original (geralmente leva mais tempo).

Ambos os usos necessitam 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 literalmente.

Funcionalidades

Início rápido

Teste 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 config
prosey help

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

O comando summarize obtém uma transcrição, adiciona a instrução da seção de configuração [summarize] e envia o resultado para o comando de IA configurado.

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

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

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

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

Exemplos

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

# Resumir (igual ao anterior)
prosey summarize 771PQEDeRmw

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

# Exibir 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 por IA)
prosey read 771PQEDeRmw

# Exibir texto simples (sem transcrição por 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) já que JSON é dados estruturados.

Desenvolvimento

Este projeto usa Bun para desenvolvimento.

bun run typecheck   # Verificação TypeScript
bun run start       # Executar a CLI a partir do código-fonte
bun run test        # Executar testes unitários
bun run build       # Compilar 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 do Diretório Base XDG (~/.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ção e resumo. O padrão é "auto", que detecta o primeiro disponível entre: bat -lmd --style plain → glow -p → mdcat -l -p → less. Defina para 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 detecção automática.

Cache

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

Ao executar prosey summarize, o comando é executado dentro do diretório de cache para aquele vídeo. Isso impede que o agente de IA colete 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 através da biblioteca youtube-transcript-plus. Nenhuma chave de API ou automação de navegador é necessária.

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.