| # 🔧 TROUBLESHOOTING & FAQ - SISTEMA STICKER | |
| **v21.2025 Enterprise-Grade** | |
| **Última atualização**: Janeiro 2025 | |
| --- | |
| ## ❓ PERGUNTAS FREQUENTES (FAQ) | |
| ### P1: Como personalizar o nome do sticker? | |
| **A:** Automático! O sticker pega o primeiro nome do usuário: | |
| - Usuário: "João Silva" → Pack: "akira-bot-joao" | |
| - Usuário: "Maria Santos" → Pack: "akira-bot-maria" | |
| - Não precisa fazer nada, é automático! | |
| --- | |
| ### P2: Por que meu sticker não aparece com metadados? | |
| **A:** Existem 3 motivos possíveis: | |
| 1. **Webpmux não instalado** (não é obrigatório) | |
| ```bash | |
| npm install node-webpmux | |
| ``` | |
| Sem isto, sticker funciona mas sem EXIF | |
| 2. **WhatsApp não carrega metadados** | |
| - Alguns celulares antigos não mostram | |
| - Tente em outro aparelho | |
| 3. **Sticker muito antigo** | |
| - Metadados só em stickers novos | |
| - Resend com #sticker novamente | |
| --- | |
| ### P3: Qual é a diferença entre #sticker e #gif? | |
| **A:** | |
| | Comando | Entrada | Saída | Limite | | |
| |---------|---------|-------|--------| | |
| | #sticker | Imagem | Sticker estático | 100KB | | |
| | #gif | Vídeo | Sticker animado | 500KB, 30s | | |
| **Resumido**: #sticker = foto, #gif = vídeo | |
| --- | |
| ### P4: Por que não consigo usar #reveal? | |
| **A:** Precisa ser **Admin ou Dono** do grupo: | |
| ``` | |
| ✅ Permitido: | |
| - Criador do grupo | |
| - Admin (pode ver conversas deletadas) | |
| ❌ Bloqueado: | |
| - Membro comum | |
| - Moderador (sem permissão admin) | |
| ``` | |
| **Solução**: Pedir ao admin para usar ou virar admin | |
| --- | |
| ### P5: View-once desaparece depois que eu revelo? | |
| **A:** **NÃO!** Comportamento correto: | |
| ``` | |
| 1. Amigo envia imagem com view-once (será deletada automaticamente) | |
| 2. Você (admin) faz #reveal | |
| 3. Você recebe a imagem revelada | |
| 4. Imagem original AINDA desaparece (é por design) | |
| 5. Você tem a cópia revelada pra sempre | |
| ``` | |
| **É assim que deve ser!** Protege privacidade | |
| --- | |
| ### P6: Posso converter qualquer view-once em sticker? | |
| **A:** Sim! Todos os tipos: | |
| ``` | |
| ✅ Imagem view-once → Sticker estático | |
| ✅ Vídeo view-once → Sticker animado | |
| ✅ Áudio view-once → [Não, só imagem/vídeo] | |
| ✅ Sticker view-once → Sticker repersonalizado | |
| ``` | |
| Use `#vosticker` para qualquer um | |
| --- | |
| ### P7: Por que algumas músicas do YouTube não baixam? | |
| **A:** 3 causas possíveis: | |
| 1. **Vídeo geobloqueado** | |
| - **Solução**: Sistema tenta yt-dlp primeiro (faz bypass) | |
| - Se ainda falhar: Use VPN ou outro link | |
| 2. **Copyright/DMCA takedown** | |
| - **Solução**: Nenhuma, video removido do YouTube | |
| 3. **URL inválida ou deletada** | |
| - **Solução**: Verificar link ou tentar outro | |
| **Dica**: Se falhar com ytdl-core, yt-dlp geralmente funciona! | |
| --- | |
| ### P8: Qual método de download YouTube é melhor? | |
| **A:** Sistema escolhe automaticamente: | |
| ``` | |
| Prioridade 1: yt-dlp | |
| ✅ Mais robusto | |
| ✅ Bypass geobloqueio | |
| ✅ Bypass 403 Forbidden | |
| ⚠️ Precisa instalar no sistema | |
| Prioridade 2: ytdl-core (fallback) | |
| ✅ Puro Node.js | |
| ✅ Sem instalação extra | |
| ⚠️ Limitado em alguns casos | |
| ``` | |
| **Recomendação**: Instalar yt-dlp para melhor resultado | |
| --- | |
| ### P9: Sticker fica comprimido/ruim - por quê? | |
| **A:** Possíveis causas: | |
| 1. **Imagem original ruim** | |
| - Solução: Usar imagem de melhor qualidade | |
| 2. **Redimensionamento automático** | |
| - Solução: Enviar em 512x512 (ou próximo) | |
| 3. **Compressão do WhatsApp** | |
| - Solução: Normal, nem sempre dá pra evitar | |
| **Dica**: Quanto melhor a imagem original, melhor o resultado | |
| --- | |
| ### P10: Posso criar sticker de sticker? | |
| **A:** Sim! Pode repersonalizar: | |
| ``` | |
| 1. Enviar sticker de outro bot | |
| 2. Responder com: #sticker | |
| 3. Resultado: Mesmo sticker, novo pack "akira-bot-[seu_nome]" | |
| ``` | |
| **Útil para**: Reorganizar stickers antigos | |
| --- | |
| ## 🚨 TROUBLESHOOTING - ERROS COMUNS | |
| ### ❌ Erro: "Imagem não encontrada" | |
| **Causa**: Mensagem não tem imagem | |
| **Solução**: | |
| ``` | |
| Correto: Responder a uma imagem com #sticker | |
| Errado: Digitar #sticker sem responder a nada | |
| Exemplo certo: | |
| [Imagem enviada] | |
| Responder: #sticker | |
| ``` | |
| --- | |
| ### ❌ Erro: "Vídeo muito grande" | |
| **Causa**: Arquivo > 100MB | |
| **Solução**: | |
| ``` | |
| 1. Usar vídeo menor (< 100MB) | |
| 2. Comprimir antes: | |
| ffmpeg -i video.mp4 -crf 28 -s 512x512 output.mp4 | |
| 3. Ou usar #gif (máx 30s, 500KB) | |
| ``` | |
| --- | |
| ### ❌ Erro: "FFmpeg não encontrado" | |
| **Causa**: FFmpeg não instalado | |
| **Solução**: | |
| ```bash | |
| # Linux (Ubuntu/Debian) | |
| sudo apt-get update | |
| sudo apt-get install ffmpeg | |
| ffmpeg -version # Verificar | |
| # Windows (Chocolatey) | |
| choco install ffmpeg | |
| ffmpeg -version # Verificar | |
| # macOS | |
| brew install ffmpeg | |
| ffmpeg -version # Verificar | |
| ``` | |
| --- | |
| ### ❌ Erro: "yt-dlp não encontrado" | |
| **Causa**: Sistema opcional, mas recomendado | |
| **Solução**: | |
| ```bash | |
| # Instalação 1: Via pacote (recomendado) | |
| # Linux | |
| sudo apt-get install yt-dlp | |
| yt-dlp --version | |
| # Windows | |
| choco install yt-dlp | |
| yt-dlp --version | |
| # Instalação 2: Via Python | |
| pip install yt-dlp | |
| yt-dlp --version | |
| # Instalação 3: Manual | |
| # Download: https://github.com/yt-dlp/yt-dlp/releases | |
| # Windows: Colocar em C:\bin\yt-dlp.exe | |
| # Linux: Colocar em /usr/local/bin/yt-dlp | |
| chmod +x /usr/local/bin/yt-dlp | |
| ``` | |
| **Teste**: | |
| ```bash | |
| yt-dlp "https://youtube.com/watch?v=abc123" --extract-audio --audio-format mp3 -o "test.mp3" | |
| ``` | |
| --- | |
| ### ❌ Erro: "Webpmux não instalado" | |
| **Causa**: Pacote opcional (graceful fallback ativo) | |
| **Solução**: | |
| ```bash | |
| # Instalar (recomendado para metadados EXIF) | |
| npm install node-webpmux | |
| # Se falhar, instale dependências: | |
| # Linux | |
| sudo apt-get install libwebp-dev | |
| # Windows (já incluído no npm) | |
| # Teste | |
| node -e "require('node-webpmux')" | |
| ``` | |
| **Sem Webpmux**: Sticker funciona, apenas sem metadados EXIF | |
| --- | |
| ### ❌ Erro: "403 Forbidden - YouTube" | |
| **Causa**: Vídeo bloqueado/geobloqueado | |
| **Solução**: | |
| ``` | |
| Automática: Sistema tenta yt-dlp primeiro (faz bypass) | |
| Manual: | |
| 1. Instalar yt-dlp (vê acima) | |
| 2. Tentar #play novamente | |
| 3. Se ainda falhar: usar VPN | |
| Alternativa: Tentar outro link do mesmo vídeo | |
| ``` | |
| --- | |
| ### ❌ Erro: "Não é view-once" | |
| **Causa**: Mensagem não é view-once | |
| **Solução**: | |
| ``` | |
| Diferenciar: | |
| View-once (auto-deleta): | |
| [Uma imagem com "ícone de relógio"] | |
| → Use #reveal ou #vosticker | |
| Mensagem normal: | |
| [Uma imagem normal, sem ícone especial] | |
| → Use #sticker normalmente | |
| ``` | |
| **Dica**: View-once aparece com ícone especial no WhatsApp | |
| --- | |
| ### ❌ Erro: "Comando restrito" | |
| **Causa**: Você não é admin/dono | |
| **Solução**: | |
| ``` | |
| Para #reveal (admin-only): | |
| 1. Peça ao admin para revelar | |
| 2. Ou vire admin | |
| 3. Ou use #vosticker (permite qualquer um) | |
| Para outros comandos: | |
| Pode usar normalmente (sem restrição) | |
| ``` | |
| --- | |
| ### ❌ Erro: "Sticker muito grande" | |
| **Causa**: Imagem > 1024x1024 pixels | |
| **Solução**: | |
| ``` | |
| Opção 1: Redimensionar antes de enviar | |
| - Usar app de edição (Photoshop, Paint, etc) | |
| - Reduzir para 512x512 ou menos | |
| Opção 2: Sistema faz automático | |
| - Enviar que o bot redimensiona | |
| - Mas PIOR qualidade | |
| Recomendação: Redimensionar antes = melhor resultado | |
| ``` | |
| --- | |
| ### ❌ Erro: "Vídeo muito longo" | |
| **Causa**: Vídeo > 30 segundos em #gif | |
| **Solução**: | |
| ``` | |
| Opção 1: Cortar vídeo antes de enviar | |
| ffmpeg -i video.mp4 -ss 0 -t 30 output.mp4 | |
| Opção 2: Enviar tipo-time menor | |
| [Vídeo 10s] #gif → OK | |
| Limite duro: #gif é 30s máximo, 500KB | |
| ``` | |
| --- | |
| ### ❌ Erro: "Nenhum método funcionou" | |
| **Causa**: Ambos yt-dlp e ytdl-core falharam | |
| **Solução**: | |
| ``` | |
| Debug steps: | |
| 1. Verificar internet: ping youtube.com | |
| 2. Verificar URL: Copiar e abrir no navegador | |
| 3. Verificar firewall: Bloqueia YouTube? | |
| 4. Verificar VPN: Tem VPN ligado? | |
| Se tudo OK: | |
| - Tentar outro URL | |
| - Tentar outra música | |
| - Reportar bug com URL específico | |
| ``` | |
| --- | |
| ## 🔍 DEBUG - VERIFICAR INSTALAÇÕES | |
| ### Checklist de Dependências | |
| ```bash | |
| # 1. Node.js | |
| node --version # Deve ser v14+ | |
| # 2. NPM Packages | |
| npm list @distube/ytdl-core # Ou ytdl-core | |
| npm list node-webpmux # Opcional mas recomendado | |
| npm list fluent-ffmpeg # Deve estar | |
| # 3. Sistema | |
| ffmpeg -version # Deve estar instalado | |
| yt-dlp --version # Opcional mas recomendado | |
| # 4. Caminhos (Linux) | |
| which ffmpeg | |
| which yt-dlp | |
| which python3 | |
| # 5. Permissões (Linux) | |
| ls -la /usr/local/bin/yt-dlp | |
| # Deve ter: -rwxr-xr-x | |
| ``` | |
| --- | |
| ### Verificar Logs | |
| ```bash | |
| # Ver logs detalhados | |
| grep -i "sticker" logs/bot.log | tail -20 | |
| grep -i "error" logs/bot.log | tail -20 | |
| grep -i "youtube" logs/bot.log | tail -20 | |
| # Ou em tempo real | |
| tail -f logs/bot.log | grep -i "sticker" | |
| ``` | |
| --- | |
| ## 📞 CONTATO PARA SUPORTE | |
| Se nenhuma solução acima funcionar: | |
| ``` | |
| Forneça: | |
| 1. Mensagem de erro completa | |
| 2. Comando usado | |
| 3. Sistema operacional (Windows/Linux) | |
| 4. Versão do Node.js (node --version) | |
| 5. Último log relevante | |
| 6. Se possível: Reprodutor mínimo | |
| Exemplo: | |
| OS: Ubuntu 20.04 | |
| Node: v16.13.0 | |
| Comando: #gif [responder a video.mp4] | |
| Erro: "FFmpeg not found" | |
| Log: [14:32:10] ERROR FFmpeg is not installed | |
| ``` | |
| --- | |
| ## ✅ CHECKLIST DE VERIFICAÇÃO | |
| Antes de reportar bug: | |
| - [ ] Atualizei todas as dependências | |
| - [ ] Instalei FFmpeg (sistema) | |
| - [ ] Instalei yt-dlp (recomendado) | |
| - [ ] Restarteiu o bot | |
| - [ ] Limpei cache temporário | |
| - [ ] Testei em outro grupo | |
| - [ ] Tentei comando diferente | |
| - [ ] Verifiquei internet está OK | |
| - [ ] Confirmei que é realmente view-once (se aplicável) | |
| - [ ] Li este FAQ completamente | |
| --- | |
| ## 🎓 DICAS PRO | |
| ### Dica 1: Otimizar Conversão de Sticker | |
| ```bash | |
| # Pré-processar imagem antes de enviar: | |
| ffmpeg -i image.jpg -vf "scale=512:512:force_original_aspect_ratio=decrease,pad=512:512:(ow-iw)/2:(oh-ih)/2" -quality 90 output.jpg | |
| # Resultado: Melhor qualidade, mais rápido | |
| ``` | |
| ### Dica 2: Verificar Integridade yt-dlp | |
| ```bash | |
| # Testar download com yt-dlp | |
| yt-dlp "https://www.youtube.com/watch?v=...key..." \ | |
| --extract-audio \ | |
| --audio-format mp3 \ | |
| --audio-quality 0 \ | |
| -o "test.mp3" | |
| # Se funcionar aqui, funciona no bot também | |
| ``` | |
| ### Dica 3: Cache de Downloads | |
| ```bash | |
| # Limpar cache de FFmpeg | |
| rm -rf /tmp/ffmpeg_* | |
| # Limpar cache do sistema | |
| df -h # Ver espaço disponível | |
| ``` | |
| ### Dica 4: Monitorar Performance | |
| ```bash | |
| # Ver uso de CPU/memória | |
| top -p $(pgrep -f "index.js") | |
| # Ver processos abertos | |
| ps aux | grep -E "(ffmpeg|yt-dlp)" | |
| # Ver arquivos temporários | |
| ls -lah /tmp/ | grep -E "(webp|mp3|mp4)" | |
| ``` | |
| --- | |
| ## 📚 REFERÊNCIAS | |
| - [Node.js Docs](https://nodejs.org/docs/) | |
| - [FFmpeg Wiki](https://trac.ffmpeg.org/wiki) | |
| - [yt-dlp GitHub](https://github.com/yt-dlp/yt-dlp) | |
| - [Webpmux Docs](https://npm.im/node-webpmux) | |
| - [WhatsApp Web Docs](https://docs.whatsapp.com/) | |
| --- | |
| **Desenvolvido com ❤️ por Isaac Quarenta** | |
| **Akira Bot v21 - Enterprise Grade 2025** | |
| **Última atualização**: Janeiro 2025 | |
| **Versão**: v21.2025 | |
| **Status**: ✅ Pronto para produção | |