SupoClip na prática: vídeos longos automaticamente convertidos em clipes verticais

O problema que o SupoClip resolve é direto: dado um vídeo longo — podcast, entrevista, replay de transmissão ao vivo — ele automaticamente encontra os 3 a 7 segmentos com maior potencial de viralização, os pontua com base no apelo e os renderiza como vídeos curtos verticais 9:16, com legendas palavra por palavra, recorte centralizado no rosto e ganchos de título. Todo o processo roda no seu próprio hardware, sem marcas d'água e sem aprisionamento a plataformas.

O fluxo técnico é dividido em cinco etapas: AssemblyAI ou Whisper fazem a transcrição com timestamps palavra por palavra; um LLM seleciona os trechos de destaque a partir da transcrição e atribui pontuações; a detecção facial determina quem fica centralizado no quadro vertical; as legendas aparecem sincronizadas por palavra; por fim, o FFmpeg concatena e exporta. O frontend é Next.js, o backend é FastAPI, e as tarefas em segundo plano são executadas por um worker ARQ que consome o Redis, enquanto o PostgreSQL armazena os dados de usuários e tarefas.

Dependências principais e ambiente

Primeiro, confirme os requisitos básicos:

  • Git
  • Docker Engine ou Docker Desktop, com o plugin Compose
  • Pelo menos 10 GB de espaço em disco disponível (arquivos de vídeo, cache de modelos e arquivos intermediários de renderização ocupam espaço)
  • CPU é suficiente, mas as etapas de transcrição e renderização serão mais lentas; com uma GPU NVIDIA você pode desativar BACKEND_CPU_ONLY para acelerar

Duas chaves são obrigatórias:

  • Chave da API AssemblyAI: para transcrição, caminho padrão
  • Chave de um provedor de LLM: Google, OpenAI, Anthropic ou OpenRouter — escolha um

Para rodar 100% local, você pode trocar a transcrição pelo Whisper e o modelo de seleção pelo Ollama, sem precisar de nenhuma chave de API.

Árvore de estrutura do projeto

supoclip/
├── frontend/          # Frontend Next.js, porta 3107, autenticação e requisições proxy para o backend
├── backend/           # Backend FastAPI, porta 8000, inclui documentação interativa da API em /docs
├── worker/            # Processo de tarefas em segundo plano ARQ, lida com transcrição, análise e renderização
├── mcp/               # Servidor MCP, para chamadas via Claude/Cursor
├── docs/              # Documentação de instalação, configuração e solução de problemas
├── scripts/           # Scripts operacionais como reparos de banco de dados
├── docker-compose.yml # Orquestra cinco serviços: frontend/backend/worker/postgres/redis
└── .env.example       # Modelo de variáveis de ambiente

Os dados ficam em volumes nomeados: postgres_data, redis_data, uploads, clips. O backend também monta dois diretórios locais, backend/fonts e backend/transitions, para fontes de legenda e materiais de transição.

Passo a passo de implantação

1. Clone o repositório e prepare o arquivo de ambiente

git clone https://github.com/FujiwaraChoki/supoclip.git
cd supoclip
cp .env.example .env

Edite o .env e preencha pelo menos estas três variáveis:

ASSEMBLY_AI_API_KEY=sua_chave_assemblyai
LLM=google-gla:gemini-3-flash-preview
GOOGLE_API_KEY=sua_chave_google

2. Configure o modelo de seleção de destaques

A variável LLM define qual modelo ajudará a escolher os segmentos. Além dos modelos em nuvem como Gemini, GPT e Claude, você pode usar o prefixo ollama: para apontar para qualquer serviço compatível com o protocolo v1/chat/completions. Por exemplo, usando Defapi para modelos locais:

LLM=ollama:seu_id_de_modelo
OLLAMA_BASE_URL=https://api.defapi.org/v1
OLLAMA_API_KEY=sua_chave_defapi

O prefixo ollama: no SupoClip apenas seleciona o tipo de cliente, não obriga a rodar o Ollama localmente. No código, o OllamaProvider usa AsyncOpenAI para receber a base_url e a API key, então qualquer serviço compatível com o protocolo de chat completion da OpenAI funcionará. Defapi é um exemplo desse tipo de serviço, com preço cerca de metade dos canais oficiais, e todos os modelos são basicamente compatíveis com os três protocolos v1/chat/completions, v1/messages e v1beta/models/. A capacidade de seleção depende de testes práticos; a transcrição e a edição de IA no estúdio de edição continuam sendo caminhos independentes.

3. Construa e inicie

./start.sh

Se preferir usar o Docker diretamente:

docker-compose up -d --build

Na primeira compilação, imagens são baixadas e dependências instaladas; em máquinas com CPU pode levar alguns minutos. Acompanhe o progresso com:

docker-compose logs -f

Quando todos os cinco serviços aparecerem como healthy, a inicialização estará concluída:

docker-compose ps

4. Verifique a saúde dos serviços

Acesse estes endereços para confirmar:

A saída de docker-compose ps deve listar cinco contêineres: supoclip-frontend, supoclip-backend, supoclip-worker, supoclip-postgres, supoclip-redis.

5. Crie uma conta e envie o vídeo

Abra a página inicial do frontend no navegador e registre-se. A home aceita duas entradas: colar um link do YouTube/Twitch/Kick ou enviar diretamente um arquivo de vídeo local. Note que o limite de upload padrão é 4 GB, suficiente para um vídeo 1080p completo com bitrate comum.

6. Visualize, edite e exporte clipes verticais

Após enviar a tarefa, a página da tarefa mostrará o progresso em tempo real: o status de transcrição, análise de IA e renderização serão atualizados. Ao concluir, você verá a duração de cada segmento, um resumo da transcrição, a justificativa da IA e a pontuação de potencial de viralização.

Acesse o estúdio de edição para fazer os seguintes ajustes:

  • Arraste as bordas do segmento para cortar o início e o fim
  • Divida segmentos longos em vários menores
  • Combine vários segmentos
  • Reescreva o texto das legendas
  • Alterne o estilo das legendas (fonte, animação, tamanho, cor)
  • Exporte com predefinições por plataforma: TikTok, Reels, Shorts

Na exportação, escolha "Vertical output" para gerar o vídeo final 9:16, com o rosto centralizado e as legendas palavra por palavra já embutidas.

Solução de problemas comuns

A página do frontend não abre

Verifique a porta do host. O modelo padrão usa FRONTEND_PORT=3107, mas se você estiver atualizando de uma versão antiga, sem essa variável no .env, o padrão será 3001. Use docker-compose port frontend 3107 para ver o mapeamento real.

Erro "Invalid origin" no login

NEXT_PUBLIC_APP_URL e BETTER_AUTH_URL devem corresponder exatamente ao endereço do navegador, incluindo protocolo e porta. localhost e 127.0.0.1 são origens diferentes. Para acessar de outros domínios ou portas, defina BETTER_AUTH_TRUSTED_ORIGINS com uma lista explícita separada por vírgulas; curingas não são suportados.

A tarefa fica presa em "queued"

Primeiro, veja os logs do worker. docker-compose logs -f worker mostrará qualquer erro. Depois, verifique o heartbeat do worker com curl -f http://localhost:8000/health/worker; se retornar 503, o worker está offline ou o Redis não está acessível. O heartbeat do ARQ expira em cerca de 31 segundos.

Transcrição parada em 30%

Essa etapa está chamando a AssemblyAI. Veja os logs do backend para verificar se a chave da API é válida e se há créditos suficientes. A consulta de status tem um tempo limite total, padrão de 900 segundos; se exceder, a mesma tarefa é tentada novamente, sem cobrança duplicada. Para vídeos longos, aumente ASSEMBLY_AI_HTTP_TIMEOUT_SECONDS.

Erro ou formato de saída incorreto no modelo de seleção

O prefixo LLM e a chave do provedor devem corresponder: ollama: usa OLLAMA_BASE_URL e OLLAMA_API_KEY; google-gla: usa GOOGLE_API_KEY; e assim por diante. Se o modelo local retornar JSON mal estruturado, o agente tentará novamente no máximo duas vezes (output_retries=2). Trocar para um modelo com melhor capacidade de seguir instruções geralmente resolve.

Erro "Falha ao criar conta" ao registrar

Provavelmente o esquema do banco de dados está desatualizado em relação ao código. Execute o script de reparo idempotente, que apenas adiciona colunas sem tocar nos dados existentes:

docker compose exec -T postgres psql -U supoclip -d supoclip < scripts/selfhost-schema-repair.sql

Nunca execute prisma db push ou prisma migrate deploy nesse banco; o backend gerencia tabelas que o Prisma desconhece, e db push as excluiria.

Leitura complementar / direções avançadas

  • Rota 100% local: Troque TRANSCRIPTION_PROVIDER para whisper e use LLM=ollama:... com um serviço Ollama local. Note que, dentro do Docker, o endereço padrão do Ollama é http://host.docker.internal:11434/v1, exigindo que o Ollama do host escute na porta correspondente.
  • Integração MCP: O diretório mcp/ do repositório fornece um servidor MCP para chamar as capacidades de edição do SupoClip a partir de clientes como Claude e Cursor.
  • API REST: Gere uma chave de API em /settings/api-keys e chame os endpoints do backend diretamente, adequado para processamento em lote via scripts.
  • Material B-roll: Defina PEXELS_API_KEY; após a seleção pela IA, o Pexels fornecerá automaticamente vídeos de stock gratuitos para cenas de ilustração.
  • Limites de licença: A versão atual usa a Licença de Código Aberto Não Comercial SupoClip 1.1. É gratuita para uso não comercial e para criadores individuais que monetizam conteúdo próprio; empresas, instituições, equipes ou serviços de edição terceirizados devem solicitar licença por escrito por e-mail. Antes de começar, leia o arquivo LICENSE, especialmente a definição de "Criadores Individuais".