11 KiB
Arisu AI
Asistente de IA con avatar Live2D animado. Responde por voz y texto, te sigue con la mirada a través de la cámara, y habla con voz expresiva usando ElevenLabs.
Stack
| Capa | Tecnología |
|---|---|
| Backend | FastAPI + WebSocket |
| LLM | Groq (llama-3.1-8b-instant) |
| STT | Groq Whisper (whisper-large-v3-turbo) |
| TTS | ElevenLabs (eleven_v3) |
| Clima | Open-Meteo (gratis, sin API key) |
| Avatar | Live2D Cubism 4 + pixi-live2d-display |
| Seguimiento ocular | MediaPipe FaceMesh |
| Frontend | HTML/CSS/JS + Bootstrap 5 + Bootstrap Icons (UI bilingüe ES/EN) |
Requisitos
- Python 3.9+
- API keys de Groq y ElevenLabs
- Navegador con micrófono (Chrome, Firefox, Safari)
Instalación
cd waifu
pip install -r requirements.txt
cp .env.example .env
# Edita .env con tus claves API
python main.py
Abrir http://localhost:8000 en el navegador.
Al primer arranque se descarga automáticamente live2dcubismcore.min.js (~202 KB) desde los servidores de Live2D.
Seguridad: Si las claves estuvieron expuestas en código, rótalas en los dashboards de Groq y ElevenLabs.
Estructura
waifu/
├── PLAN.md # Plan de auditoría y mejoras
├── main.py # Backend FastAPI + WebSocket + LLM
├── workspace.py # Herramientas terminal (archivos + shell)
├── websearch.py # Búsqueda web (Serper / DuckDuckGo / Wikipedia)
├── weather.py # Clima Open-Meteo + detección de intención
├── .env.example # Plantilla de variables de entorno
├── requirements.txt
└── static/
├── index.html # UI principal
├── style.css # Tema cyberpunk-anime
├── app.js # WebSocket, audio, chat, wake word, i18n
├── live2d.js # Wrapper Live2D + expresiones + lip-sync
└── live2dcubismcore.min.js # Runtime Cubism 4
Diagrama de funcionamiento
Arquitectura general
flowchart TB
subgraph Browser["🌐 Navegador"]
UI["Chat · Live2D · Ajustes"]
Mic["Micrófono continuo + VAD"]
Cam["Cámara + FaceMesh"]
Geo["Geolocalización"]
end
subgraph Server["⚙️ Servidor — main.py"]
WS["WebSocket /ws"]
Wake["Wake check «Arisu»"]
STT["Groq Whisper STT"]
Prefetch["Prefetch clima"]
LLM["Groq LLM + historial"]
Tools["Tool calling"]
TTS["ElevenLabs TTS"]
end
subgraph Modules["📦 Módulos"]
W["weather.py"]
S["websearch.py"]
T["workspace.py"]
end
subgraph APIs["☁️ APIs externas"]
Groq["Groq"]
Eleven["ElevenLabs"]
OM["Open-Meteo"]
Web["Serper · DuckDuckGo · Wikipedia"]
end
UI <-->|"texto · chunks · widget"| WS
Mic -->|"PCM 16 kHz · wake_check"| WS
Geo -->|"geo_config"| WS
Cam --> UI
WS --> Wake --> STT
WS --> STT
WS --> Prefetch --> W --> OM
Prefetch -->|"weather_widget"| WS
STT --> LLM
WS -->|"question"| LLM
LLM --> Tools
Tools --> S --> Web
Tools --> T
LLM --> Groq
STT --> Groq
LLM --> TTS --> Eleven
TTS -->|"tts_audio"| WS
Flujo de una conversación
sequenceDiagram
autonumber
participant U as Usuario
participant B as Navegador
participant S as Servidor
participant G as Groq
participant X as Open-Meteo / Web / Terminal
participant E as ElevenLabs
alt Voz con «Arisu»
U->>B: «Arisu, ¿clima en Madrid?»
B->>S: wake_check (PCM base64)
S->>G: Whisper
G-->>S: transcripción
S-->>B: wake_ok + text
Note over B: Si no hay pregunta en wake_ok,<br/>graba la siguiente frase (post-buffer)
else Micrófono manual
U->>B: Hablar → Detener
B->>S: PCM binario
S->>G: Whisper
G-->>S: texto
S-->>B: transcript
else Texto escrito
U->>B: Escribe en el chat
end
B->>S: question
opt Pregunta de clima
S->>X: Open-Meteo
X-->>S: datos
S-->>B: weather_widget
end
S->>G: LLM (+ historial + datos clima)
loop Herramientas si el LLM las necesita
S->>X: web_search / workspace
X-->>S: resultados
S-->>B: tool_event · tool_result
S->>G: continúa con resultados
end
G-->>S: respuesta con [tags]
S-->>B: thinking → chunk × N → done
opt TTS activado
S->>E: texto con tags
E-->>S: MP3
S-->>B: tts_audio
B->>B: lip-sync Live2D + expresiones
end
Uso
| Acción | Cómo |
|---|---|
| Activación por voz | Di «Arisu» y luego tu pregunta (activo por defecto; ⚙️ para desactivar) |
| Hablar manualmente | Clic en Hablar, habla, clic en Detener (o barra espaciadora) |
| Escribir | Campo de texto → Enter o botón Enviar |
| Cancelar respuesta | Botón Detener o tecla Escape |
| Limpiar chat | Icono papelera en el header |
| Activar terminal | ⚙️ → Modo terminal + Directorio base |
| Cambiar modelo Live2D | ⚙️ → Modelo |
| Cambiar cámara/mic | ⚙️ → Cámara / Micrófono |
| Idioma UI | ⚙️ → Idioma UI (Español / English) |
| Idioma voz (STT) | ⚙️ → Idioma voz |
| Activar/desactivar TTS | ⚙️ → Reproducir voz |
Activación por voz «Arisu»
Compatible con Safari (no usa Web Speech API). Flujo:
- El micrófono escucha continuamente con VAD (detección de voz).
- Al detectar habla, envía audio al servidor → Whisper busca la palabra «Arisu».
- Si la frase incluye pregunta tras «Arisu» («Arisu, qué clima hace en Madrid»), se envía directamente.
- Si solo dice «Arisu», graba tu siguiente frase automáticamente.
El audio que llega mientras el servidor transcribe se guarda en un buffer para no perder la pregunta.
Clima
Pregunta por el tiempo y verás una tarjeta visual en el chat con icono, temperatura, mín/máx, humedad y viento.
Ejemplos:
- «¿Qué clima hace hoy en Tokio?»
- «Arisu, clima en Madrid»
- «¿Hace calor hoy?» (usa geolocalización del navegador si la permites)
El servidor detecta la intención de clima, consulta Open-Meteo y muestra el widget sin depender del tool-calling del LLM (evita errores con modelos pequeños).
Búsqueda web
Arisu puede buscar en internet cuando no sabe algo o necesita datos actuales. El LLM usa la herramienta web_search automáticamente.
| Fuente | Cuándo |
|---|---|
| Serper (Google) | Si configuras SERPER_API_KEY en .env |
| DuckDuckGo | Siempre (gratis) |
| Wikipedia | Fallback en el idioma de la sesión |
La fecha actual del sistema se inyecta en el prompt del LLM para consultas de «hoy» o noticias recientes.
Verás en el chat: Buscando en la web mientras consulta.
Modo terminal (workspace)
Arisu puede crear archivos y ejecutar comandos solo dentro de un directorio base que tú elijas.
- Abre ⚙️ Ajustes
- Activa Modo terminal
- Escribe la ruta absoluta, p. ej.
/Users/tu/proyectos/mi-app - Pide por voz o texto: "Crea un programa Python que sume dos números"
Herramientas disponibles (LLM)
| Herramienta | Función |
|---|---|
web_search |
Buscar en internet (siempre activa) |
list_directory |
Listar archivos y carpetas |
read_file |
Leer un archivo de texto |
write_file |
Crear o sobrescribir un archivo |
create_directory |
Crear carpetas |
run_command |
Ejecutar comandos shell en el workspace |
El clima no usa tool-calling del LLM; se resuelve en el servidor vía
weather.py.
Seguridad
- Todas las rutas deben estar dentro del directorio base (sin
../) - Comandos peligrosos bloqueados (
sudo,rm -rf /, etc.) - Timeout de 45 s por comando
- Solo úsalo en carpetas de desarrollo, nunca en
/o tu home completo
Memoria conversacional
Cada conexión WebSocket mantiene un historial de hasta 20 mensajes (≈10 turnos). Arisu recuerda el contexto dentro de la sesión. Usa Limpiar chat para resetear.
Persistencia: sesión WebSocket + preferencias UI en localStorage. No usa base de datos.
Modelos Live2D disponibles
- Mao — chica con uniforme escolar (por defecto)
- Natori — chica con traje casual
- Haru — chica con vestido
- Rice — personaje AR de Live2D Garage
Audio tags de ElevenLabs
| Tag | Voz | Expresión |
|---|---|---|
[laughs] |
Risa | Cara muy feliz, mejillas rojas |
[giggles] |
Risita | Cara feliz, ojos sonrientes |
[excited] |
Emocionada | Cara muy expresiva |
[whispers] |
Susurro | Expresión calmada |
[sighs] |
Suspiro | Expresión neutral |
[gasps] |
Sorpresa | Expresión sorprendida |
Pipeline de audio
Micrófono → ScriptProcessor → Float32 → Downsample 16 kHz → Int16 PCM
→ WebSocket binario → WAV → Groq Whisper → texto
→ Groq LLM (streaming + historial + herramientas) → chunks con tags
→ ElevenLabs TTS (opcional) → MP3 base64
→ AudioContext + AnalyserNode → lip-sync Live2D
Mensajes WebSocket
| Dirección | Tipo | Significado |
|---|---|---|
| cliente→servidor | audio_config |
Idioma STT, sample_rate, tts_enabled |
| cliente→servidor | geo_config |
Lat/lon del navegador (clima local) |
| cliente→servidor | question |
Texto del usuario |
| cliente→servidor | wake_check |
Audio PCM base64 para detectar «Arisu» |
| cliente→servidor | workspace_config |
Activar terminal + ruta base |
| cliente→servidor | cancel |
Cancelar respuesta en curso |
| cliente→servidor | clear_history |
Borrar historial de sesión |
| cliente→servidor | binario | PCM-16LE a 16 kHz (grabación manual) |
| servidor→cliente | transcript |
Resultado Whisper |
| servidor→cliente | wake_ok |
«Arisu» detectado (text opcional = pregunta incluida) |
| servidor→cliente | no_wake |
No se detectó «Arisu» |
| servidor→cliente | thinking |
LLM iniciado |
| servidor→cliente | chunk |
Delta streaming |
| servidor→cliente | done |
LLM terminado |
| servidor→cliente | cancelled |
Respuesta cancelada |
| servidor→cliente | busy |
Servidor ocupado |
| servidor→cliente | tts_audio |
MP3 en base64 |
| servidor→cliente | tts_error |
ElevenLabs falló |
| servidor→cliente | no_speech |
Audio demasiado corto o silencioso |
| servidor→cliente | tool_event |
Herramienta en ejecución |
| servidor→cliente | tool_result |
Resultado de herramienta |
| servidor→cliente | weather_widget |
Datos de clima para tarjeta visual |
| servidor→cliente | workspace_ok |
Workspace validado |
| servidor→cliente | workspace_error |
Workspace inválido |
| servidor→cliente | history_cleared |
Historial borrado |
| servidor→cliente | error |
Error genérico |
Variables de entorno
GROQ_API_KEY=gsk_...
ELEVENLABS_API_KEY=sk_...
# Opcional
SERPER_API_KEY= # Búsqueda Google vía Serper
APP_TIMEZONE=America/Mexico_City # Zona horaria para «hoy»
GROQ_MODEL=llama-3.1-8b-instant
GROQ_STT_MODEL=whisper-large-v3-turbo
ELEVEN_VOICE_ID=B8gJV1IhpuegLxdpXFOE
ELEVEN_MODEL=eleven_v3