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_ONLYpara 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:
- Frontend: http://localhost:3107
- Verificação de saúde do backend: http://localhost:8000/health
- Documentação interativa da API: http://localhost:8000/docs
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_PROVIDERparawhispere useLLM=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-keyse 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".