# 🎭 AniaPlayer Web
> Player de avatares animados interativo para web com suporte a áudio, TTS e integração com chatbots.
[]()
[]()
[]()
---
## 📋 Índice
- [Sobre](#sobre)
- [Características](#características)
- [Instalação](#instalação)
- [Uso Rápido](#uso-rápido)
- [Configuração](#configuração)
- [Exemplos](#exemplos)
- [API Completa](#api-completa)
- [Segurança](#segurança)
- [Integração com Chatbots](#integração-com-chatbots)
- [Build e Distribuição](#build-e-distribuição)
- [Suporte](#suporte)
---
## 🎯 Sobre
**AniaPlayer Web** é uma biblioteca JavaScript moderna para reproduzir avatares animados (arquivos `.ania`) em navegadores. Desenvolvida para ser integrada facilmente em sites, chatbots e aplicações web, oferece:
- ✅ **Zero dependências externas**
- ✅ **Criptografia dupla camada (AES-256)**
- ✅ **Detecção de fala em tempo real**
- ✅ **Sistema de animação inteligente (idle/talk)**
- ✅ **Chroma key multi-camadas**
- ✅ **Cache LRU otimizado**
- ✅ **Validação de licença server-side**
- ✅ **TypeScript nativo**
---
## ✨ Características
### 🎬 Sistema de Animação
- **Modo Idle**: Animação de descanso com múltiplos pontos de início
- **Modo Talk**: Animação de fala sincronizada com áudio
- **Transições suaves**: Mudanças fluidas entre estados
- **Velocidade ajustável**: 0.25x a 4x (por modo ou global)
- **Reversão automática**: Suporte a ping-pong de frames
### 🎤 Processamento de Áudio
- **Captura de microfone** com MediaDevices API
- **Detecção de fala** automática e configurável
- **Noise gate** e amplificação
- **Redução de ruído** avançada com calibração
- **Smoothing** de amplitude com média móvel
- **Limiter** para evitar clipping
### 🔐 Segurança
- **Criptografia AES-256-CBC** com PBKDF2 (100.000 iterações)
- **Dupla camada** (senha do usuário + serverKey)
- **HMAC SHA-256** para integridade
- **Validação de licença** server-side obrigatória
- **Ofuscação de código** no build de produção
### 🎨 Chroma Key
- **Múltiplas camadas** de chroma key
- **Sensibilidades individuais** RGB
- **Spill reduction** para remover reflexos
- **Smoothing** para bordas suaves
- **Transparência real** (alpha channel)
### ⚡ Performance
- **Cache LRU** para frames (configurável)
- **Preload inteligente** baseado em contexto
- **Streaming de frames** sob demanda
- **Hit rate tracking** para otimização
---
## 📦 Instalação
### Via NPM (Recomendado)
```bash
npm install @aniaplayer/web
```
### Via CDN
```html
```
### Download Manual
Baixe a versão compilada em [Releases](https://github.com/your-repo/releases) e inclua no seu projeto:
```html
```
---
## 🚀 Uso Rápido
### HTML Básico
```html
Meu Avatar Animado
```
### ES6 Modules
```javascript
import { AniaPlayer } from '@aniaplayer/web';
const player = new AniaPlayer('#avatar-container', {
auto_start: true,
audio_enabled: true,
onLoad: () => console.log('Pronto!'),
onStateChange: (isTalking) => {
console.log('Falando:', isTalking);
}
});
await player.load('./avatar.ania', 'senha');
```
### TypeScript
```typescript
import { AniaPlayer, AniaPlayerConfig } from '@aniaplayer/web';
const config: Partial = {
auto_start: true,
playback_speed: 1.5,
audio_enabled: true,
audio_sensitivity: 70,
onLoad: () => {
console.log('Avatar carregado com sucesso!');
},
onError: (error: Error) => {
console.error('Erro ao carregar:', error.message);
}
};
const player = new AniaPlayer('#container', config);
await player.load('./avatar.ania', 'password123');
```
---
## ⚙️ Configuração
### Opções do AniaPlayer
```typescript
interface AniaPlayerConfig {
// Reprodução
playback_speed?: number; // 0.25 a 4.0 (padrão: 1.0)
auto_start?: boolean; // Inicia automaticamente (padrão: true)
loop?: boolean; // Loop contínuo (padrão: true)
// Áudio
audio_enabled?: boolean; // Ativa captura de mic (padrão: false)
audio_device?: string; // ID do dispositivo de áudio
audio_sensitivity?: number; // 0-100 (padrão: 50)
noise_reduction_enabled?: boolean; // Padrão: true
noise_reduction_intensity?: number; // 0-100 (padrão: 50)
// Velocidades individuais
idle_speed?: number; // Velocidade do idle (padrão: 1.0)
talk_speed?: number; // Velocidade do talk (padrão: 1.0)
transition_speed?: number; // Velocidade de transição (padrão: 1.0)
// Display
width?: number; // Largura customizada (px)
height?: number; // Altura customizada (px)
scale?: number; // Escala (padrão: 1.0)
transparent?: boolean; // Fundo transparente (padrão: true)
chroma_enabled?: boolean; // Ativa chroma key (padrão: true)
// API
api_url?: string; // URL da API de validação
api_key?: string; // Chave da API
// Callbacks
onLoad?: () => void;
onError?: (error: Error) => void;
onFrameChange?: (frameIndex: number) => void;
onStateChange?: (isTalking: boolean) => void;
onLicenseValidated?: (valid: boolean) => void;
}
```
### Exemplo Completo de Configuração
```javascript
const player = new AniaPlayer('#container', {
// Reprodução
playback_speed: 1.5,
auto_start: true,
loop: true,
// Áudio
audio_enabled: true,
audio_sensitivity: 70,
noise_reduction_enabled: true,
noise_reduction_intensity: 60,
// Velocidades
idle_speed: 0.8,
talk_speed: 1.2,
transition_speed: 2.0,
// Display
width: 500,
height: 600,
scale: 1.0,
transparent: true,
chroma_enabled: true,
// API
api_url: 'https://api.seuservidor.com',
api_key: 'sua-chave-api',
// Callbacks
onLoad: () => {
console.log('✅ Avatar carregado');
},
onError: (error) => {
console.error('❌ Erro:', error.message);
},
onFrameChange: (frameIndex) => {
console.log('Frame atual:', frameIndex);
},
onStateChange: (isTalking) => {
console.log(isTalking ? '🗣️ Falando' : '😴 Idle');
},
onLicenseValidated: (valid) => {
console.log('Licença:', valid ? 'Válida' : 'Inválida');
}
});
await player.load('./avatar.ania', 'senha123');
```
---
## 📚 Exemplos
### 1. Player Básico
```javascript
const player = new AniaPlayer('#container');
await player.load('./avatar.ania', 'senha');
player.play();
```
### 2. Com Controles de UI
```javascript
import { AniaPlayer, UIController } from '@aniaplayer/web';
const player = new AniaPlayer('#container', {
audio_enabled: true
});
const ui = new UIController(player, container, {
showPlayPause: true,
showSpeed: true,
showSensitivity: true,
showNoiseReduction: true,
position: 'bottom',
style: 'full'
});
await player.load('./avatar.ania');
ui.show();
```
### 3. Integração com Chatbot
```javascript
const player = new AniaPlayer('#avatar', {
audio_enabled: false,
onStateChange: (isTalking) => {
updateChatBotUI(isTalking);
}
});
await player.load('./avatar.ania');
// Quando bot responder, simula fala
function onBotResponse(text) {
// Força modo talk por duração baseada no texto
const duration = calculateDuration(text);
player.animationController.setTalkingState(true);
setTimeout(() => {
player.animationController.setTalkingState(false);
}, duration);
}
```
### 4. Seleção de Dispositivo de Áudio
```javascript
import { AudioProcessor } from '@aniaplayer/web';
// Lista dispositivos
const devices = await AudioProcessor.getAudioDevices();
devices.forEach(device => {
console.log(device.label, device.deviceId);
});
// Usa dispositivo específico
const player = new AniaPlayer('#container', {
audio_enabled: true,
audio_device: devices[0].deviceId
});
```
### 5. Ajustes Dinâmicos
```javascript
const player = new AniaPlayer('#container');
await player.load('./avatar.ania');
// Ajusta velocidade
player.setPlaybackSpeed(2.0); // 2x mais rápido
// Ajusta sensibilidade
player.setAudioSensitivity(80); // 80% de sensibilidade
// Ajusta redução de ruído
player.setNoiseReduction(true, 70); // 70% de intensidade
// Obtém estatísticas
const stats = player.getCacheStats();
console.log('Cache:', stats);
// Obtém estado atual
const state = player.getState();
console.log('Estado:', state);
```
---
## 📖 API Completa
### AniaPlayer
#### Constructor
```typescript
new AniaPlayer(container: HTMLElement | string, config?: Partial)
```
#### Métodos
| Método | Descrição | Retorno |
|--------|-----------|---------|
| `load(source, password)` | Carrega arquivo .ania | `Promise` |
| `play()` | Inicia reprodução | `void` |
| `pause()` | Pausa reprodução | `void` |
| `stop()` | Para e reseta | `void` |
| `setPlaybackSpeed(speed)` | Define velocidade global (0.25-4) | `void` |
| `setAudioSensitivity(value)` | Define sensibilidade (0-100) | `void` |
| `setNoiseReduction(enabled, intensity)` | Configura redução de ruído | `void` |
| `getCacheStats()` | Retorna estatísticas do cache | `CacheStats` |
| `getState()` | Retorna estado atual | `PlayerState` |
| `destroy()` | Destroi player e libera recursos | `void` |
#### PlayerState
```typescript
interface PlayerState {
isPlaying: boolean;
currentFrame: number;
totalFrames: number;
mode: 'idle' | 'talk' | 'transition';
isTalking: boolean;
cacheStats: CacheStats;
}
```
#### CacheStats
```typescript
interface CacheStats {
size: number; // Frames em cache
maxSize: number; // Tamanho máximo
hits: number; // Acertos
misses: number; // Falhas
hitRate: number; // Taxa de acerto (0-1)
}
```
### AudioProcessor
```typescript
class AudioProcessor {
static getAudioDevices(): Promise
start(deviceId?: string): Promise
stop(): void
recalibrate(): void
setSensitivity(value: number): void
setNoiseReduction(enabled: boolean, intensity: number): void
getLevel(): number // 0-100
destroy(): void
}
```
### UIController
```typescript
class UIController {
constructor(player: AniaPlayer, container: HTMLElement, config?: UIControlsConfig)
show(): void
hide(): void
destroy(): void
}
```
---
## 🔒 Segurança
### Sistema de Criptografia
O AniaPlayer usa criptografia de **dupla camada**:
1. **Camada 1 - Senha do Usuário**
- AES-256-CBC
- PBKDF2 com 100.000 iterações
- Salt único de 16 bytes
- HMAC SHA-256 para integridade
2. **Camada 2 - ServerKey** (v3.0)
- Criptografa frames individuais
- Validação obrigatória com servidor
- Chave fornecida apenas após validação de licença
### Validação de Licença
```typescript
interface LicenseValidationRequest {
licenseId: string; // ID da licença
contentHash: string; // Hash do conteúdo
hardwareId: string; // Fingerprint do browser
ipAddress?: string; // IP do cliente
}
interface LicenseValidationResponse {
valid: boolean;
type?: 'lifetime' | 'subscription' | 'trial';
expires_at?: number | null;
decrypt_key?: string; // ServerKey para v3.0
reason?: string; // Código de erro
}
```
### Proteção do Código
O build de produção inclui:
- **Ofuscação** de nomes de variáveis/funções
- **Minificação** com Terser
- **Tree-shaking** para remover código não usado
- **Remoção** de console.log e debugger
---
## 🤖 Integração com Chatbots
### Exemplo com Bot Simples
```javascript
const player = new AniaPlayer('#avatar', { audio_enabled: false });
await player.load('./avatar.ania');
// Simula fala quando bot responde
function onBotResponse(text, duration = 3000) {
// Ativa modo talk
if (player.animationController) {
player.animationController.setTalkingState(true);
setTimeout(() => {
player.animationController.setTalkingState(false);
}, duration);
}
}
// Uso
onBotResponse('Olá! Como posso ajudar?', 2000);
```
### Exemplo com Web Speech API
```javascript
const synthesis = window.speechSynthesis;
function speakText(text) {
const utterance = new SpeechSynthesisUtterance(text);
utterance.onstart = () => {
player.animationController?.setTalkingState(true);
};
utterance.onend = () => {
player.animationController?.setTalkingState(false);
};
synthesis.speak(utterance);
}
speakText('Olá! Eu sou um avatar animado.');
```
### Exemplo com API de TTS Externa
```javascript
async function speakWithTTS(text) {
// Calcula duração aproximada
const wordsPerMinute = 150;
const words = text.split(' ').length;
const durationMs = (words / wordsPerMinute) * 60 * 1000;
// Ativa animação
player.animationController?.setTalkingState(true);
// Chama API de TTS (exemplo)
const audio = new Audio();
audio.src = await getTTSAudioURL(text);
audio.play();
audio.onended = () => {
player.animationController?.setTalkingState(false);
};
}
```
---
## 🔧 Build e Distribuição
### Desenvolvimento
```bash
# Instala dependências
npm install
# Modo desenvolvimento (watch)
npm run dev
# Servidor local
npm run serve
```
### Produção
```bash
# Build completo
npm run build
# Apenas minificação
npm run minify
```
### Estrutura de Distribuição
```
dist/
├── aniaplayer.js # UMD (desenvolvimento)
├── aniaplayer.min.js # UMD (produção)
├── aniaplayer.esm.js # ES Module
├── aniaplayer.d.ts # TypeScript definitions
└── aniaplayer.js.map # Source maps
```
### CDN
Para hospedar em CDN, faça upload da pasta `dist/` e disponibilize:
```
https://cdn.seudominio.com/aniaplayer/
├── 1.0.0/
│ ├── aniaplayer.min.js
│ └── aniaplayer.js
└── latest/
├── aniaplayer.min.js
└── aniaplayer.js
```
---
## 📝 Licenciamento
### Para Desenvolvedores (Você)
Este é um produto **proprietário**. Você distribui aos clientes via:
1. **Link direto** para CDN hospedado por você
2. **NPM package** privado
3. **Download** de versão compilada
### Para Clientes (Usuários Finais)
Os clientes só precisam:
```html
```
**Sem complexidade**, **sem instalação**, apenas funciona! ✨
---
## 🎯 Roadmap
- [ ] Suporte a vídeo WebM/MP4 além de frames
- [ ] PWA para uso offline
- [ ] React/Vue/Angular components
- [ ] Plugin para WordPress
- [ ] Sistema de temas/skins
- [ ] Analytics integrado
- [ ] Modo VR/AR experimental
---
## 💡 Dicas de Uso
### Performance
1. **Use cache adequado**: Padrão de 200 frames é bom para a maioria dos casos
2. **Desative chroma se não usar**: Economiza processamento
3. **Ajuste scale**: Se não precisa de alta resolução, use scale < 1.0
4. **Preload**: Sistema automático é inteligente, não precisa ajustar
### Segurança
1. **Sempre use HTTPS** para validação de licença
2. **Não exponha api_key** no código cliente (use servidor proxy)
3. **Valide no servidor** além do cliente
4. **Monitore uso** da API para detectar abusos
### UX
1. **Mostre loading** durante carregamento do arquivo
2. **Peça permissão** para microfone antes de ativar
3. **Forneça controles** visíveis para sensibilidade
4. **Indique estado** (idle/talking) visualmente
---
## 🆘 Suporte
### Problemas Comuns
**❓ Avatar não carrega**
- Verifique se o arquivo .ania está acessível
- Confirme a senha (se houver)
- Veja erros no console do navegador
**❓ Áudio não funciona**
- Verifique permissão do microfone
- Teste em HTTPS (requerido para getUserMedia)
- Ajuste sensibilidade
**❓ Performance ruim**
- Reduza tamanho do cache
- Desative chroma key se não usar
- Use scale menor
### Contato
- 📧 Email: suporte@aniaplayer.com
- 💬 Discord: [servidor](https://discord.gg/...)
- 📚 Docs: https://docs.aniaplayer.com
- 🐛 Issues: https://github.com/your-repo/issues
---
## 📜 Changelog
### v1.0.0 (2025-12-26)
- 🎉 Lançamento inicial
- ✅ Suporte completo a arquivos .ania (v1.0, v2.0, v3.0)
- ✅ Sistema de animação idle/talk
- ✅ Captura e processamento de áudio
- ✅ Chroma key multi-camadas
- ✅ Cache LRU otimizado
- ✅ TypeScript nativo
---
**Feito com ❤️ por AniaPlayer Team**