🎙️ VoiceFlow

Biometric voice verification + custom command recognition powered by deep learning. No passwords. No apps. Just your voice.

🚀 Live Demo • 📖 Technical Docs • 🐙 GitHub

---

🎯 El Problema

Los sistemas de control por voz existentes tienen problemas críticos:

• ❌ No verifican quién habla — cualquiera puede activar el comando
• ❌ Comandos fijos — no puedes definir tus propias frases
• ❌ Requieren servicios de pago (Google Assistant, Alexa, etc.)
• ❌ Sin privacidad — tu audio se procesa en servidores de terceros

💡 Mi Solución

VoiceFlow combina verificación biométrica + reconocimiento de comandos personalizado en un solo sistema:

• ✅ Verifica tu identidad antes de ejecutar cualquier comando
• ✅ Define tus propias frases — entrena el modelo con tu voz
• ✅ 100% tuyo — corre en tu servidor, tus datos no se comparten
• ✅ Funciona desde cualquier dispositivo — browser en PC o móvil
• ✅ Pipeline ML doble — Resemblyzer + SpeechBrain ECAPA-TDNN

---

🎬 Demo

🌐 Demo en vivo: voiceflow-lemon.vercel.app

Flujo completo en 4 pasos:

1. Define tus comandos  →  2. Enrolla tu voz  →  3. Entrena comandos  →  4. Reconocimiento en vivo

⚠️ El backend corre en Hugging Face Spaces gratuito — el primer request tras inactividad puede tardar ~30s en despertar.

---

✨ Features

🛡️ Verificación Biométrica

• Huella vocal de 448 dimensiones — pipeline dual Resemblyzer (256d) + SpeechBrain ECAPA-TDNN (192d)
• Threshold dinámico — calibrado automáticamente con la varianza intra-clase de tus muestras
• Reducción de ruido dual — stationary + non-stationary, funciona con voces de fondo
• Data augmentation — 6× variantes por muestra (pitch shift, time stretch, noise) para mayor robustez

🎯 Comandos Personalizados

• Frases libres — define cualquier palabra o frase como comando
• Action payload — asigna un string a cada comando (MQTT topic, URL, tecla, etc.)
• Múltiples frases por comando — varía cómo lo dices para mejor detección
• Re-entrenamiento — vuelve a entrenar cualquier comando sin empezar de cero
• Configuración de muestras — elige 1×, 3×, o 5× repeticiones por frase

📱 UX / Interfaz

• Stepper navegable — flujo guiado con progreso visual, puedes volver a pasos anteriores
• RecordButton con progreso circular — ring SVG animado durante la grabación
• AudioVisualizer en tiempo real — barras con gradiente reactivas al nivel de audio
• Funciona desde móvil — sin instalación, desde el browser directamente
• Fondo WebGL interactivo — shader de hilos que responde al movimiento del cursor (OGL)

☁️ Persistencia

• Guardar perfil en la nube — sincroniza tu modelo a Firestore con código de 8 caracteres
• Restaurar en cualquier dispositivo — introduce el código y recuperas tu perfil completo
• Descargar perfil local — descarga tu .npz para respaldo

---

🛠️ Tech Stack

Frontend	Backend	ML / Audio
Next.js 14 (App Router)	FastAPI 0.110	Resemblyzer (GE2E)
TypeScript 5.x	Python 3.10	SpeechBrain ECAPA-TDNN
Zustand (state)	Uvicorn	noisereduce (dual-pass)
Framer Motion	slowapi (rate limiting)	librosa
Tailwind CSS	Firebase Firestore	PyAV (audio convert)
OGL (WebGL shaders)	Clean Architecture	NumPy / SciPy

🤔 Por qué este stack

Elección	Razón
Resemblyzer + SpeechBrain	Dos modelos complementarios → embeddings 448d más robustos que uno solo
FastAPI async	Maneja múltiples requests de audio sin bloquear el event loop
Next.js App Router	Server components + layout compartido para el fondo WebGL global
Zustand	Estado global sin boilerplate, persistencia del sessionId sin complejidad
Clean Architecture	Separación domain/infrastructure → fácil swapear modelos ML sin tocar routers

---

🚀 Quick Start

Prerrequisitos

• Python 3.10+
• Node.js 18+
• Proyecto Firebase con Firestore habilitado

Backend

# 1. Clonar
git clone https://github.com/AlanDev-fr/voiceflow.git
cd voiceflow/voiceflow-backend

# 2. Instalar dependencias
pip install -r requirements.txt

# 3. Configurar variables
cp .env.example .env
# Edita .env con la ruta a tu firebase-credentials.json

# 4. Arrancar
uvicorn app.main:app --reload --port 7860

Frontend

cd voiceflow/voiceflow-frontend

# 1. Instalar
npm install

# 2. Configurar
echo "NEXT_PUBLIC_API_URL=http://localhost:7860/api/v1" > .env.local

# 3. Dev
npm run dev

# O build de producción (menor consumo de CPU)
npm run build && npm start

Abre http://localhost:3000.

Firebase Setup

1. Crea un proyecto en Firebase Console
2. Habilita Firestore Database
3. Descarga la clave de servicio → firebase-credentials.json
4. Colócala en voiceflow-backend/
5. Configura .env:

   GOOGLE_APPLICATION_CREDENTIALS=./firebase-credentials.json
   

Testing desde móvil (sin deploy)

# Instalar cloudflared
winget install Cloudflare.cloudflared  # Windows
brew install cloudflared               # macOS

# Exponer ambos puertos
cloudflared tunnel --url http://localhost:7860   # Backend
cloudflared tunnel --url http://localhost:3000   # Frontend

# Actualizar .env.local con la URL del backend tunnel
NEXT_PUBLIC_API_URL=https://xxxx.trycloudflare.com/api/v1

---

📂 Project Structure

voiceflow/
├── voiceflow-backend/
│   ├── app/
│   │   ├── application/
│   │   │   └── use_cases/            # Lógica de aplicación
│   │   ├── domain/
│   │   │   ├── entities/             # VoiceProfile, Command, Result
│   │   │   ├── services/             # VoiceEngine (ML logic)
│   │   │   └── repositories/         # Interfaces de persistencia
│   │   ├── infrastructure/
│   │   │   ├── audio/                # Procesamiento de audio
│   │   │   ├── ml/                   # ModelLoader singleton
│   │   │   └── storage/              # Firestore & NPZ impl.
│   │   ├── presentation/
│   │   │   ├── routers/              # API endpoints
│   │   │   └── schemas/              # Pydantic models (IO)
│   │   ├── config.py
│   │   └── main.py                   # FastAPI initialization
│   ├── Dockerfile
│   └── requirements.txt
│
└── voiceflow-frontend/
    ├── app/
    │   ├── layout.tsx                # Threads WebGL global
    │   └── demo/page.tsx             # Stepper principal
    ├── components/
    │   ├── flows/                    # Enroll, Train, Live
    │   ├── landing/                  # Hero, Tech, Info
    │   ├── ui/                       # Kit de UI reusable
    │   ├── voice/                    # Audio visuals & recording
    │   └── background/               # WebGL Shaders
    ├── hooks/                        # Recorders & logic
    ├── store/                        # Zustand core state
    ├── types/                        # TypeScript definitions
    └── lib/api/                      # API client logic

---

🔥 Key Technical Highlights

1. Pipeline de Embeddings Dual (448d)

def get_embedding(self, audio: np.ndarray, sr: int) -> np.ndarray:
    embeddings = []

    # Resemblyzer — captura timbre y entonación general (256d)
    emb_resemblyzer = self._resemblyzer.embed_utterance(audio)
    embeddings.append(emb_resemblyzer)

    # SpeechBrain ECAPA-TDNN — captura características del tracto vocal (192d)
    tensor = torch.FloatTensor(audio).unsqueeze(0)
    emb_speechbrain = self._speechbrain.encode_batch(tensor).squeeze().numpy()
    embeddings.append(emb_speechbrain)

    # L2-normalize cada embedding + concatenar → 448d
    embeddings = [e / (np.linalg.norm(e) + 1e-10) for e in embeddings]
    return np.concatenate(embeddings)

2. Reducción de Ruido Dual-Pass

def reduce_noise(self, audio: np.ndarray, sr: int) -> np.ndarray:
    # Pasada 1: ruido constante (ventilador, hiss del micrófono)
    reduced = nr.reduce_noise(y=audio, sr=sr, stationary=True, prop_decrease=0.6)

    # Pasada 2: ruido variable (voces de fondo, ambiente)
    reduced = nr.reduce_noise(
        y=reduced, sr=sr,
        stationary=False,
        prop_decrease=0.5,
        freq_mask_smooth_hz=500,
        time_mask_smooth_ms=50,
    )
    return reduced

3. Threshold Dinámico por Usuario

def recalculate_command_threshold(self, engine, intra_min: float) -> None:
    # Se adapta a la consistencia vocal del usuario:
    # Usuario consistente → threshold más alto (más exigente)
    # Usuario con variabilidad natural → threshold más permisivo
    self.command_threshold = max(intra_min - 0.18, 0.38)

4. AudioVisualizer con Curva de Amplificación

// Curva exponencial para amplificar niveles bajos
// level=10 (casi silencio) → amplified≈40 (visible en el canvas)
// level=80 (voz fuerte) → amplified≈93 (sin saturar)
const amplified = Math.pow(level / 100, 0.4) * 100

barsRef.current = barsRef.current.map((bar, i) => {
    const phase = (Date.now() / 180 + i * 0.35) % (Math.PI * 2)
    const wave = Math.sin(phase) * 0.4 + 0.8
    const noise = (Math.random() * 0.8 + 0.2) * amplified * 0.5
    const target = recording
        ? (amplified * 0.9 + noise) * wave
        : Math.sin(Date.now() / 900 + i * 0.5) * 4 + 4  // idle suave
    return bar + (target - bar) * 0.4  // easing
})

---

🚀 Deployment

Backend → Hugging Face Spaces

1. Crea un nuevo Space con Docker SDK
2. Sube el contenido de voiceflow-backend/
3. Añade tus credenciales Firebase como Secret
4. URL resultante: https://tu-usuario-voiceflow.hf.space

Frontend → Vercel

1. Conecta tu repo en vercel.com
2. Configura la variable de entorno:

   NEXT_PUBLIC_API_URL=https://tu-usuario-voiceflow.hf.space/api/v1
   

3. Deploy automático en cada push a main

💡 La URL de HF Spaces es fija — configúrala en Vercel antes de hacer el primer deploy del backend.

---

📊 Performance

Operación	Tiempo (CPU)
Extracción embeddings 448d	800–1200ms
Reducción de ruido dual-pass	200–400ms
Cosine similarity	<1ms
Total /recognize	~1–2s

GPU acelera SpeechBrain significativamente. HF Spaces gratuito corre en CPU.

---

🚧 Roadmap

✅ v1.0 (Actual)

• Pipeline dual Resemblyzer + SpeechBrain (448d)
• Definición y entrenamiento de comandos personalizados
• Reducción de ruido dual-pass
• Guardado/restauración de perfiles via Firestore
• Interfaz responsive (PC + móvil)
• Rate limiting por IP

🔄 v1.1 (Próximo)

• Integración MQTT real para IoT
• Múltiples perfiles por sesión
• Historial persistente de reconocimientos

💡 v2.0 (Planeado)

• Modo continuo — escucha activa sin presionar botón
• Wake word detection
• WebSocket streaming en tiempo real
• SDK embebible para otras apps

---

🤝 Contributing

¡Las contribuciones son bienvenidas!

1. Fork del repo
2. Crea una rama (git checkout -b feature/nueva-feature)
3. Commit (git commit -m 'feat: descripción')
4. Push (git push origin feature/nueva-feature)
5. Abre un Pull Request

Antes de enviar:

• Verifica que el backend arranca sin errores
• Verifica que el frontend compila con npm run build
• Prueba el flujo completo: enroll → train → recognize

---

⚠️ Disclaimer

VoiceFlow es un prototipo / proof of concept. No está listo para producción en aplicaciones sensibles sin hardening adicional (autenticación, cifrado de embeddings, etc.). Ver TECHNICAL.md.

---

📄 License

MIT © AlanDev-fr

---

📬 Contact

¿Buscas un desarrollador Full Stack / ML?

• 💼 Abierto a oportunidades remotas (LATAM/USA timezones)
• 🌎 Basado en Quito, Ecuador
• 🇺🇸 English: A2 Technical
• 📧 alandev.fr@gmail.com
• 💻 LinkedIn
• 🐙 @AlanDev-fr

---

Hecho con ❤️ usando FastAPI + Next.js + SpeechBrain

⭐ Si te resulta útil, dale una estrella al repo!