Comandos de voz locales · habla atipica

Tu voz, como es. Reconocimiento de comandos local, sin nube.

NAC3 Kikoe reconoce un punado de comandos personales por voz -- local y dependiente del hablante -- pensado para habla atipica (disartria, pronunciacion no estandar). No transcribe todo lo que decis: compara tu voz contra unas pocas muestras tuyas por proximidad matematica. El audio nunca sale de tu dispositivo.

Como instalarlo → Codigo en GitHub

Codigo abierto (MIT) · Cero dependencias · Node 22+ / ESM · El audio nunca se guarda

聞

Que es y que no es

Un comparador liviano de MFCC + DTW para un punado de comandos tuyos.

Kikoe extrae una huella numerica de cada muestra que grabas (una secuencia de vectores MFCC) y, cuando hablas, mide la distancia con Dynamic Time Warping normalizado por longitud contra esas huellas, con un umbral de rechazo. No es un dictado general: es reconocimiento de pocos comandos, afinado a tu voz y 100% local.

Lo que es

  • Un comparador MFCC + DTW liviano, sin dependencias.
  • Afinado a un punado de comandos por usuario.
  • Totalmente local y adaptado al hablante.
  • Preserva la privacidad: el audio se descarta tras extraer la huella.

Lo que no es

  • Un sistema de speech-to-text general.
  • Apto para dictado libre por si solo (necesita un reconocedor externo para eso).
  • Un servicio en la nube: nada se transmite a un servidor.

Privacidad por diseno

La voz se usa un instante y se descarta. Solo quedan numeros.

El audio crudo (PCM) se consume de forma transitoria durante la extraccion de caracteristicas y luego se descarta. Lo unico que llega al almacenamiento son huellas numericas y metadatos del comando -- nunca la voz. El test suite verifica que ningun objeto pasado a storage.save(...) contenga la clave pcm.
Audio descartado Solo huellas numericas Almacenamiento que vos elegis Sin nube
  • El reconocimiento ocurre en el dispositivo: la voz nunca viaja por la red.
  • El host decide donde se persisten las huellas (archivo, base de datos, navegador) via un StorageAdapter.
  • En el navegador, la extraccion de caracteristicas es client-side: el audio no abandona el equipo.
  • Cero dependencias en tiempo de ejecucion: menos superficie, menos terceros.

Tres capas

Reconoce, corrige y, si queres, colabora con un reconocedor externo.

Kikoe se compone en tres capas independientes. Podes usar solo la primera, o sumar las otras dos segun tu caso.

Capa A

Sesgo de vocabulario

Produce listas de palabras sin duplicados para alimentar al reconocedor anfitrion via buildBiasVocabulary(commands, contacts) y empujarlo hacia tus comandos conocidos.

Capa B

Memoria de correcciones

CorrectionMemory registra pares "escuche -> queria decir" (sin distinguir mayusculas ni espacios) para arreglar de forma deterministica las confusiones que se repiten.

Capa C

Enrollment de Google (opcional)

La integracion con Project Euphonia / enrollment de Google queda fuera del alcance del paquete: es responsabilidad del host si decide integrarla.

耳

Metricas y enrutador · v0.2.0

Aprende cuanto confiar en lo local, y cuando pedir una segunda opinion.

Con el uso real, cada comando madura dos metricas (ambas arrancan suavizadas en 0,5) y un enrutador decide -- sin ejecutar nada -- si conviene resolver localmente o escalar a la nube.

Confianza

De las veces que el motor local disparo este comando, cuantas el usuario dejo en pie (en vez de corregir o cancelar). El usuario es la fuente de verdad; la mueve observeOutcome.

Efectividad

De las emisiones medidas, cuantas veces el acuerdo local coincidio con la ruta de nube (Google STT). La nube es una segunda opinion, no un juez supremo: una baja efectividad para habla atipica valida la via local.

Enrutador eco -> nube

El enrutador nunca ejecuta: devuelve { preferLocal, runCloud } para que el host decida. Cero comandos enrolados siempre enruta a la nube.

Tres modos (perilla)

on_doubt: dispara local sin nube si esta seguro, escala si duda. learning: dispara local y mide contra la nube hasta graduarse. always: dispara local y siempre mide contra la nube.

Instalacion y quickstart

Sumalo a tu app en minutos.

1Instala el paquete desde npm

Necesitas Node 22 o mayor. El paquete es ESM y no tiene dependencias en tiempo de ejecucion.

npm install @yujinapp/nac3-kikoe
2Enrola un comando con unas muestras

Grabas dos o tres muestras del comando; Kikoe extrae las huellas y descarta el PCM.

import { Trainer, Matcher, InMemoryStorage } from "@yujinapp/nac3-kikoe";

const storage = new InMemoryStorage();
const trainer = new Trainer(storage, {
  matcher: new Matcher({ threshold: 8, margin: 0.5 }),
});

await trainer.enroll("leer bandeja", [
  { pcm: sample1, sampleRate: 16000 },
  { pcm: sample2, sampleRate: 16000 },
]);
3Entrena y reconoce

Tras entrenar, cada emision en vivo se compara contra tus huellas y devuelve si fue aceptada y a que distancia.

await trainer.train("leer bandeja");
const result = await trainer.recognize({ pcm: liveAudio, sampleRate: 16000 });
if (result.accepted) {
  console.log("comando:", result.command, "distancia:", result.distance);
}
4(Opcional) Suma metricas y enrutador

El KikoeEngine agrega las metricas de confianza/efectividad y el enrutador eco -> nube en una sola API.

const engine = new KikoeEngine(new InMemoryKikoeStorage("learning"), {
  now: () => Date.now(),
  router: { minConfidence: 0.6 },
});

const { match, route } = await engine.recognize({ pcm: live, sampleRate: 16000 });
await engine.observeOutcome("leer bandeja", userAccepted);
const metrics = await engine.listMetrics();

El host provee el almacenamiento y, opcionalmente, el reconocedor externo. El adoptante de referencia es Yuemail.

Para quien

Para voces que los reconocedores genericos no terminan de entender.

Los modelos de voz entrenados con habla estandar suelen fallar con pronunciaciones atipicas. Kikoe da vuelta el problema: en vez de pedirte que hables "claro", aprende de tus propias muestras y reconoce tus comandos como vos los decis.

Disartria

Te entiende como hablas

Al ser dependiente del hablante, el modelo es tu voz: no compite con un promedio de habla estandar. Cuanto mas atipica es la pronunciacion, mas valor aporta la via local frente a la nube.

Pocos comandos, mucha precision

Un punado de acciones clave

No intenta transcribir todo: reconoce los comandos que importan ("leer bandeja", "enviar", "firmar") con un umbral de rechazo que evita disparos en falso.

Sin conexion

Funciona offline

Como todo ocurre en el dispositivo, no depende de internet ni de un servicio externo. Util en entornos sin conexion o donde la privacidad es innegociable.

Hibrido

Lo mejor de los dos mundos

Cuando hay un reconocedor en la nube disponible, el enrutador combina la confianza local con una segunda opinion solo cuando hace falta -- sin perder la autonomia local.

Contrato NAC3

Once verbos NAC3 nativos, listos para tu agente.

Kikoe expone su funcionalidad como verbos NAC3, con politica de acceso por verbo (libre, requiere confirmacion o destructivo). Conoce NAC3 →

Verbo Politica Que hace
yujin.voicetrainer.enrollconfirmarEnrola un comando con muestras de voz.
yujin.voicetrainer.trainconfirmarEntrena el modelo de un comando enrolado.
yujin.voicetrainer.recognizelibreReconoce una emision contra los comandos.
yujin.voicetrainer.listlibreLista los comandos enrolados.
yujin.voicetrainer.forgetdestructivoBorra un comando y sus huellas.
yujin.voicetrainer.set-vocabularyconfirmarFija el vocabulario de sesgo para el reconocedor externo.
yujin.voicetrainer.correctconfirmarRegistra una correccion "escuche -> queria decir".
yujin.voicetrainer.metricslibreDevuelve confianza y efectividad por comando.
yujin.voicetrainer.observe-outcomelibreRegistra si el usuario acepto el resultado.
yujin.voicetrainer.observe-cloudlibreRegistra la opinion de la nube para medir efectividad.
yujin.voicetrainer.set-modeconfirmarCambia el modo del enrutador (on_doubt / learning / always).

Preguntas frecuentes

Preguntas frecuentes.

Sirve para dictado libre?
No por si solo. Kikoe reconoce un punado de comandos personales, no transcribe texto libre. Para dictado general, lo combinas con un reconocedor externo y usas la Capa A para sesgar su vocabulario.
Mi voz viaja a algun servidor?
No. El audio crudo se usa un instante para extraer la huella y se descarta. Solo se guardan huellas numericas. En el navegador, la extraccion es client-side: el audio no sale del equipo.
Cuantas muestras necesito por comando?
Con dos o tres muestras por comando suele alcanzar. Al ser dependiente del hablante, importa mas que las muestras sean tuyas que que sean muchas.
Que requisitos tecnicos tiene?
Node 22 o mayor, ESM, y cero dependencias en tiempo de ejecucion. Se instala con npm install @yujinapp/nac3-kikoe.
Donde se guardan las huellas?
Donde vos decidas: el host provee un StorageAdapter (archivo, base de datos, navegador). Kikoe solo le pasa numeros, nunca audio.
Donde reporto un problema o pido ayuda?
En el repositorio: github.com/pkuschnirof/nac3-kikoe.

Dale voz a tus comandos.

Codigo abierto, local y respetuoso de tu privacidad. Pensado para que tu voz, como es, alcance para controlar lo que importa.

Ver en GitHub → Paquete en npm