Arquitectura y modelo de ejecución
La sesión persistente y el cliente CLI, el socket de control, el adaptador de backend Whisper y la cascada de inserción de texto.
Una sesión persistente, un cliente que le habla
whispskrid iniciado sin argumento de control lanza una sesión persistente en primer plano: carga la configuración, carga el modelo Whisper una sola vez, abre el dispositivo de captura, inicia el escuchador de tecla y el socket de control, y luego espera.
Un modelo CTranslate2 tarda del orden de un segundo a varios segundos en cargar, según su tamaño y la máquina. Recargarlo en cada dictado haría inservible el pulsar para hablar: esa es la razón de ser del proceso persistente.
whispskrid iniciado con un argumento de control (--dictate, --status, --stop…) actúa como cliente: se conecta al socket de la sesión en curso, envía un comando de una línea, imprime la respuesta y sale con un código de retorno que refleja OK o ERR. Si no hay ninguna sesión, lo dice y sale con error.
Dos vías para activar un dictado
El mismo estado interno de la sesión persistente lo gobiernan un escuchador de tecla local y el socket de control.
- Escuchador de atajo local (
pynput) — observa el servidor X.pynputdistingue la pulsación de la liberación, así que la semántica «hablo mientras mantengo» es nativa en esta vía. Bajo Wayland solo ve las ventanas que pasan por XWayland, nunca una ventana Wayland nativa; es una comodidad de mejor esfuerzo. Tecla por defecto: Mayús derecho (shift_r), reescribible mediantehotkeys.push_to_talk. - Subcomandos CLI a través del socket — una vía universal, independiente del tipo de sesión. Un atajo del escritorio no transmite «tecla mantenida / tecla soltada», así que esta vía funciona por conmutación.
--dictateinicia la captura,--dictate-stopla detiene e inserta,--togglehace una u otra cosa según el estado,--canceldescarta la captura en curso sin insertar.
Una captura iniciada con la tecla puede cancelarse con --cancel, y a la inversa.
Salvaguarda de duración
La única salvaguarda automática es capture.max_seconds (por defecto 300).
Si la tecla sigue mantenida más allá, la captura se detiene sola, lo grabado se transcribe e inserta con normalidad, y se registra una advertencia. No es un temporizador de comodidad: es protección frente a una tecla bloqueada o a un búfer de audio que crece sin fin. El corte automático por silencio (VAD) sigue siendo posible más adelante, como opción; la clave vad.enabled está reservada en el esquema pero no está implementada en la v1.0.1.
El adaptador de backend
Un módulo backend/ expone una interfaz estrecha — load, transcribe(audio, language), info — para que un segundo motor pueda añadirse más adelante sin tocar el resto.
faster-whisper (CTranslate2) es la única implementación entregada en la v1.0.1; la clave backend.name está reservada pero solo acepta ese valor. whisper.cpp se contempla como segundo backend, más adelante.
El adaptador instancia WhisperModel con device (auto: CPU o CUDA), compute_type (auto: int8 en la CPU, float16 en CUDA) y download_root apuntando al directorio de modelos gestionado. transcribe() se llama con beam_size (por defecto 5), el idioma forzado o None, y sin filtro VAD; concatena los segmentos devueltos y recorta el texto.
Gestión de los modelos
Los modelos viven en un directorio gestionado — /usr/share/whispskrid/whisper-models/ y ~/.local/share/whispskrid/whisper-models/ para una instalación por paquete, whisper-models/ en la raíz del repositorio para una instalación desde el código fuente.
Resolver un nombre corto (base) recorre esas ubicaciones en orden. La caché de Hugging Face por defecto de faster-whisper es solo un último recurso: la herramienta debe arrancar sin conexión una vez que el modelo está presente. whispskrid --download-model [NOMBRE] descarga el modelo pedido en el directorio de usuario, comprueba que carga y sale; el postinst del paquete ofrece esta descarga en el primer arranque si no hay ningún modelo.
Inserción de texto: un pegado por el portapapeles, con cascada de motores
Una vez que el texto está transcrito y posprocesado, la capa de inserción lo coloca en el portapapeles y simula un pegado. El motor se elige una sola vez al arrancar.
| Vía | Herramientas | Condición |
|---|---|---|
| Primero | ydotool + wl-clipboard | Pulsaciones a nivel del controlador (/dev/uinput) vía el demonio ydotoold; keycodes dependientes de la distribución del teclado; exige pertenecer al grupo input. |
| Si no | xdotool + xclip | Vía estándar. La detección de la ventana (combinación de pegado para terminal) solo existe aquí — ydotool no conoce la ventana de destino. |
| En otro caso | modo degradado | No se envía ninguna pulsación; el texto transcrito queda en el terminal durante el resto de la sesión. |
El motor de tecleo necesita una herramienta de portapapeles a su lado: wl-clipboard bajo Wayland — requerida incluso en la reserva ydotool — y xclip bajo X11. El paquete Debian trae wl-clipboard y recomienda xclip; una instalación desde el código fuente los añade por sí misma. Sin ella, el texto transcrito nunca llega al portapapeles y el pegado vuelve a insertar el último contenido copiado a mano.
El contenido anterior del portapapeles se vuelve a leer y se restaura tras el pegado (regulable con clipboard.restore, activo por defecto). Un contenido no textual — una imagen, archivos — se deja intacto. Bajo Wayland con una aplicación GTK, la restauración puede adelantarse a la lectura del portapapeles por la ventana; clipboard.defer_restore aplaza la restauración al final de la sesión para que el pegado nunca recupere el contenido antiguo.
Si ningún motor adecuado a la sesión en curso funciona, la herramienta no se cae ni abandona nada en silencio: pasa a modo degradado. El texto transcrito sigue mostrándose en el terminal y el tecleo automático se desactiva para el resto de la sesión, en lugar de reintentarlo — sin éxito — en cada dictado. Algunas ventanas también rechazan el pegado — ciertas aplicaciones Java, campos protegidos; en el primero de esos casos, la herramienta pasa a modo degradado de la misma manera.
El socket de control
Una sesión en curso abre un socket Unix privado en $XDG_RUNTIME_DIR/whispskrid.sock (modo 0600). El mismo comando llamado con --dictate, --dictate-stop, --toggle, --cancel, --status o --stop se conecta a ese socket en lugar de iniciar una segunda sesión.
Es lo que hace que los atajos del escritorio funcionen en todas partes bajo Wayland, incluso para las ventanas Wayland nativas que el escuchador pynput nunca ve. El protocolo son líneas de texto, un comando por línea, respuesta con el prefijo OK o ERR; un comando desconocido responde ERR unknown-command. No hay sleep / wake: WhispSkrid no tiene estado de reposo.
Solo se ejecuta una sesión por usuario a la vez; un socket dejado por un fallo se detecta y se reemplaza en el arranque siguiente.
Idioma de la interfaz e idioma del dictado
Son dos ajustes distintos.
Idioma de la interfaz
Las cadenas de la herramienta misma pasan por la cadena GNU gettext — catálogos .po compilados a .mo, extraídos del código Python. Cuatro idiomas: inglés, francés, alemán, español.
Idioma del dictado
-l fr fuerza el idioma pasado a Whisper para esa sesión; sin argumento, default_language y luego la autodetección de Whisper. Ninguna configuración por idioma más allá de esa elección.
Whisper puntúa y aplica las mayúsculas de frase por sí mismo. El posprocesado de WhispSkrid se limita a recortar el espacio de los bordes y a forzar una mayúscula en la primera letra del texto insertado. Ninguna tabla de sustitución, ninguna regla por idioma.
Consulte el repositorio del proyecto para el código, y Guías para empezar.