TROUBLESHOOTING_FAQ_STICKERS.md

​# 🔧 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