PeakCut na prática: monte sua própria ferramenta de edição de vídeo curto com IA

O que mais consome tempo ao criar vídeos curtos não é a edição, mas sim encontrar os poucos segundos que valem a pena publicar em uma transmissão ao vivo ou vídeo longo de uma ou duas horas. O PeakCut automatiza esse fluxo: executa o reconhecimento de fala localmente, a IA ajuda a selecionar os melhores momentos, corta automaticamente para o formato vertical 9:16 e adiciona legendas palavra por palavra. O mais atraente é que todo o processo pode ser executado inteiramente no seu próprio computador, e os dados de vídeo e áudio não saem da máquina.

O fluxo de trabalho é direto: transcreve o áudio, deixa a IA decidir quais segmentos conseguem prender a atenção de estranhos e usa o FFmpeg para renderizar vídeos verticais legendados. A transcrição usa os modelos sherpa-onnx e Parakeet, totalmente locais; a IA só é responsável por selecionar os segmentos e escrever os títulos, e você pode usar qualquer provedor que desejar, desde que seja compatível com a API da OpenAI.

Se você não quiser usar a interface oficial do ChatGPT, o Defapi é uma boa opção. O preço é metade do oficial, e todos os modelos são basicamente compatíveis com os protocolos principais v1/chat/completions, v1/messages, v1beta/models/, então o provedor personalizado do PeakCut pode se conectar diretamente, e a configuração é exatamente igual ao passo 3 abaixo.

Dependências principais e ambiente

Antes de começar, confira estes itens:

  • Python 3.10+: ambiente de execução do programa principal.
  • FFmpeg: usado para todo processamento de vídeo e áudio. No Windows, use winget install Gyan.FFmpeg; no macOS, brew install ffmpeg; no Linux, sudo apt install ffmpeg.
  • Rede e armazenamento: na primeira execução, será necessário baixar cerca de 480 MB do modelo de voz. Os arquivos de vídeo são grandes; recomenda-se reservar pelo menos 20 GB de espaço em disco.
  • Chave de IA (opcional): funciona sem configurar, mas o PeakCut selecionará os segmentos com base no volume, sem títulos gerados por IA.

O PeakCut recomenda colocar o projeto em um caminho fixo, como C:\peakcut (Windows) ou ~/peakcut (macOS/Linux). Não use diretórios temporários; no Windows, caminhos muito profundos podem fazer o modelo de voz falhar ao carregar.

Estrutura do projeto

peakcut/
├── studio/                  # Código principal do servidor
│   ├── server.py            # Entrada FastAPI
│   ├── ai.py                # Camada de adaptação de serviços de IA (novos provedores aqui)
│   ├── transcribe.py        # Transcrição de voz local
│   ├── jobs.py              # Pipeline de tarefas de edição
│   ├── render.py            # Renderização de legendas e composição de vídeo
│   └── fonts/               # Arquivos de fonte para legendas
├── web/                     # Páginas front-end (HTML/CSS/JS puro)
├── deploy/                  # Configuração de implantação Docker
├── tests/                   # Testes automatizados
├── requirements.txt         # Dependências Python
├── .env.example             # Modelo de variáveis de ambiente
└── Dockerfile

Passo a passo

1. Clone o repositório e instale as dependências

git clone https://github.com/haziqahmedqasmi/peakcut.git ~/peakcut
cd ~/peakcut
pip install -r requirements.txt

Recomenda-se usar um ambiente virtual para evitar poluir os pacotes Python globais.

2. Inicie o serviço local

python -m studio.server

Na primeira execução, o modelo de voz será baixado automaticamente (cerca de 480 MB), então leve um tempo. Quando vir uma saída semelhante a Uvicorn running on http://127.0.0.1:8765, o serviço está no ar.

Abra http://127.0.0.1:8765 no navegador, entre direto no console, sem necessidade de login.

3. Configure o serviço de IA

Acesse a página Settings → AI. Aqui você escolhe o provedor de IA que deseja usar. A IA do PeakCut é responsável por duas coisas: decidir quais segmentos valem a pena cortar e escrever títulos para os segmentos. Ela precisa de um modelo de chat que retorne JSON, não um serviço de transcrição de voz — a transcrição sempre roda localmente.

No menu suspenso, selecione Custom (OpenAI-compatible). Aparecerá um campo para Base URL. Preencha com o endereço do seu provedor, cole sua chave de API no campo Key, insira manualmente o ID de um modelo de chat que suporte saída JSON e clique em Find models para buscar a lista de modelos disponíveis (se o provedor suportar). Por fim, clique em Save and test.

Por exemplo, o Defapi oferece uma interface compatível com a OpenAI, com preço pela metade do oficial. A configuração é a seguinte:

  • Base URL: https://api.defapi.org/v1
  • Key: obtenha no console da plataforma Defapi
  • Modelo: insira o ID de um modelo de chat que suporte saída JSON, por exemplo, your-model-id (o ID específico depende da lista no seu painel)

O Defapi é compatível com v1/chat/completions, v1/messages, v1beta/models/ e outros protocolos principais, então o provedor personalizado do PeakCut pode se conectar diretamente.

Nota: se você configurou parâmetros de IA anteriormente via arquivo .env, as configurações salvas no console substituirão as definições do .env. Para usar o .env, as variáveis correspondentes são:

PEAKCUT_AI_PROVIDER=custom
PEAKCUT_AI_MODELS=your-model-id
PEAKCUT_AI_KEY=your-key
PEAKCUT_AI_BASE_URL=https://api.defapi.org/v1

4. Importe vídeos

Na parte superior da página inicial, há uma caixa de colagem que aceita links do YouTube, Twitch, Kick, ou você pode enviar arquivos de vídeo locais diretamente.

Em Options, você pode definir o número de clipes a gerar (1-20), a duração mínima/máxima (mínimo 5 segundos, máximo 180 segundos), o estilo da legenda (Bounce/Hype/Clean), o layout da tela (preenchimento desfocado/zoom/corte/jogo com câmera), a resolução (720p/1080p) e também pode limitar o processamento a apenas uma parte do vídeo.

Há uma opção chamada Generate captions, ativada por padrão. As legendas são destacadas palavra por palavra, o que requer que o modelo de voz forneça resultados de reconhecimento com timestamps. O modelo padrão tem melhor suporte para inglês; se você precisar de outros idiomas, será necessário trocar o modelo — a seção de solução de problemas aborda isso.

Preencha o link e clique em Make clips para iniciar o processamento.

5. Selecione os clipes e ajuste as legendas

Após o processamento, acesse a página de detalhes do vídeo para ver todos os clipes gerados. Cada clipe permite:

  • Pré-visualizar: verificar se o resultado está satisfatório
  • Ajustar início/fim: arrastar na linha do tempo para refinar
  • Editar legendas: corrigir palavras manualmente se o reconhecimento estiver errado
  • Trocar estilo de legenda: alternar entre os três estilos livremente

O PeakCut gera uma imagem de capa e um título atraente (escrito por IA) para cada clipe. Se não gostar do título, você pode editá-lo diretamente.

6. Exporte o vídeo vertical

Quando os clipes estiverem prontos, clique em Download para exportar. A renderização é feita pelo FFmpeg, e o resultado final é o formato vertical 9:16, com legendas incorporadas na imagem.

Se você configurou a conexão com contas do YouTube, Instagram ou TikTok, também pode publicar diretamente daqui. Para uso em máquina única, é recomendável baixar primeiro e enviar manualmente.

Solução de problemas comuns

FFmpeg ausente
Após iniciar, o console avisará que o FFmpeg não foi encontrado. Verifique se ffmpeg -version funciona corretamente; se não, reinstale e certifique-se de que esteja no PATH.

Falha no download do modelo de voz
Se o download do modelo for interrompido na primeira execução, exclua a pasta correspondente em data/models/ e reinicie o serviço para baixar novamente. Se a rede estiver instável, você pode baixar manualmente do Hugging Face e colocar no diretório especificado.

A IA configurada no console não funciona
Verifique na página Settings → AI se a configuração foi salva. As configurações salvas no console têm prioridade sobre o arquivo .env. Se você definiu variáveis de IA no .env anteriormente, depois de salvar no console, elas serão ignoradas. Para voltar à configuração do .env, selecione novamente o provedor no console e salve.

Erro de formato JSON retornado pela IA
Confirme se o ID do modelo preenchido é um modelo de chat com suporte a saída JSON. Alguns modelos (especialmente os de raciocínio puro) não garantem JSON válido; tente trocar de modelo. Você também pode consultar a página AI usage, que tem logs detalhados de solicitações.

Idioma da legenda incorreto
O modelo Parakeet padrão só suporta inglês. Para vídeos em chinês, você pode trocar para um modelo sherpa-onnx com suporte a chinês (é necessário alterar ASR_MODEL_NAME em studio/config.py), ou usar a transcrição em chinês do YouTube (esse recurso está ativado por padrão e prioriza o texto de transcrição do YouTube).

Espaço em disco insuficiente
O diretório data/ armazena todos os vídeos e resultados gerados. Antes de processar vídeos longos, confirme se há espaço suficiente. Vá em Settings → Storage para ver o caminho de armazenamento atual e o espaço restante, e você também pode migrar o diretório de dados para outro disco.

Leitura complementar / Direções avançadas

O PeakCut não apenas edita vídeos já gravados, mas também pode gravar e editar destaques em tempo real durante transmissões ao vivo. Crie um workspace para cada criador, configure o canal e ele monitorará automaticamente, produzindo clipes durante a transmissão.

Para colaboração em equipe ou implantação em rede pública, consulte DEPLOY.md: use Docker para executar o aplicativo + PostgreSQL + Caddy com HTTPS automático, com suporte a registro por e-mail e login do Google. Atenção: em implantação pública, ative PEAKCUT_ACCOUNTS=1; caso contrário, qualquer pessoa que saiba o endereço poderá usar sua chave de IA.

Para conectar contas de mídias sociais (YouTube/Instagram/TikTok), é necessário registrar aplicativos de desenvolvedor em cada plataforma. Durante o período de revisão da plataforma, os vídeos enviados ficam como privados por padrão — isso é uma limitação da plataforma, não do PeakCut.

Para se aprofundar, studio/ai.py é o único arquivo que interage com o serviço de IA; adicionar um novo provedor ou depurar a lógica de solicitação começa por aqui. O código também inclui um conjunto de testes (python tests/run.py); execute os testes após alterações para evitar regressões.