Vocalis TTS

English summary

Vocalis TTS reads your Obsidian notes aloud with natural neural voices (Spanish and English). Speech is generated on your computer by Piper, so reading works the same with or without internet, with no accounts, API keys or telemetry.

• Follows along: highlights and scrolls to the current sentence in both Reading view and Live Preview, without moving your cursor.
• Smooth playback: sentences run together with short, adjustable pauses; 0.75x to 2.5x speed with natural pitch.
• Remembers your place: each note keeps its own position, with a Continue listening list in the side panel.
• Your language: the interface follows Obsidian's language (Spanish or English). Reading language is a setting, or per note with lang: en in the frontmatter.

Requirements: Windows x64, desktop only. The Piper engine and voices are installed once with a separate installer, because Obsidian plugins may not install their own dependencies.

Setup:

1. Install and enable Vocalis TTS from Community plugins.
2. Download vocalis-setup.cmd (or use the button in the plugin's panel) and double-click it. Choose your vault and voices. It is not code-signed, so Windows may warn you: click More info → Run anyway. It is plain text if you want to review it first.
3. Press Check again in the panel, open a note and press Alt + E (play / pause). Alt + D stops.

Network use: the plugin itself never uses the network. Only the installer downloads, once, the Piper engine from GitHub and the voices from Hugging Face. If those are unavailable it uses identical copies from vocalis-engine. Every file must match a pinned SHA-256.

Updates: nothing updates by itself. When a tested engine or voice update is released, Settings tells you; run the installer again and it changes only what is needed.

Files outside the vault: while reading, short-lived audio files are written to the system temp folder and deleted right away; the plugin runs the piper.exe you configured.

Advanced: silent install with the VOCALIS_VAULT and VOCALIS_LANG (es, en, both) environment variables, or use your own Piper and models by setting both paths in the plugin's settings.

Plugin de lectura en voz alta (Text-to-Speech) neuronal de alto rendimiento, privacidad absoluta y 100% offline para Obsidian, en español e inglés. Integra teleprompter visual sin desfase (tanto en Modo Edición como en Modo Lectura), velocidad dinámica hasta 2.5x en tiempo real y memoria de posición independiente por cada nota.

Potenciado por el motor de síntesis neuronal de código abierto Rhasspy Piper TTS. Publicado bajo Licencia MIT por Mack Chirinos.

🌟 Características Principales

• 100% Offline y Privado: Sin dependencias de la nube, sin claves de API, sin suscripciones ni telemetría. Todo el procesamiento se realiza en tu procesador local.
• Audio Cristalino sin Residuos: Síntesis binaria nativa ultra-rápida con ciclo de vida efímero garantizado. El audio se carga directamente a memoria RAM (Blob URL) y el archivo temporal se destruye al instante en el directorio temporal del sistema (os.tmpdir()), garantizando cero corrupción acústica por CRLF y cero acumulación de archivos en disco.
• Teleprompter Dual sin Desfase:
  • Modo Edición (Live Preview / Source): Resaltado y centrado de la frase locutada sin mover tu cursor ni tu selección.
  • Modo Lectura (Reading View renderizado): Resalta la frase sin modificar el contenido de la nota, aunque cruce negritas o enlaces, y llega a ella en notas muy largas.
  • Se recupera solo al alternar entre modos, cambiar de pestaña o volver a la nota.
• Velocidad Real hasta 2.5x con Tono Preservado:
  • Escala de velocidades: 0.75x, 1.0x, 1.25x, 1.5x, 1.75x, 2.0x, 2.25x y 2.5x.
  • Los cambios de velocidad se aplican al vuelo en tiempo real, incluso a mitad de frase, conservando el tono natural de la voz (sin distorsión ni voz de ardilla).
• Memoria de Lectura Independiente por Nota:
  • Cada archivo de tu Vault conserva su propio progreso guardado en data.json.
  • Puedes pausar en una nota, leer otra diferente y retomar cada una en su frase exacta, incluso tras cerrar y reabrir Obsidian.
• Detección Inteligente de Inicio:
  • Si seleccionas un texto o haces clic en una frase con el ratón: inicia inmediatamente desde ese punto.
  • Si no hay selección activa: reanuda desde el progreso guardado de la nota.
• Panel en la Barra Lateral Derecha:
  • Reproductor fijo en la barra lateral derecha (como Esquema o Backlinks). Se abre solo al empezar a leer o con el comando Abrir panel de Vocalis.
  • Tarjeta con el nombre de la nota, la frase actual y un botón de play grande; iconos nativos de Obsidian, que respetan tu tema.
  • Barra de progreso interactiva (Seek-bar): haz clic en cualquier porcentaje para saltar directamente a esa frase.
  • Botones de salto (+/- 1 frase), reinicio de nota, detener, cambio de voz y de velocidad.
  • Continuar escuchando: lista de las notas con lectura a medias, con su porcentaje y una barrita de progreso; un clic abre la nota y reanuda. La ✕ de cada fila (aparece al pasar el mouse) borra solo dónde ibas, sin tocar la nota.
• Memoria que Sigue a tus Notas: si renombras o mueves una nota, conserva su progreso; si la borras, su memoria se limpia.
• Lectura Limpia: se omiten las URLs sueltas (de los enlaces Markdown se lee solo el texto) y las tablas se leen fila por fila, con una pausa entre celdas.
• Lectura Continua: la voz mantiene el modelo cargado y prepara por adelantado las frases siguientes. Las pausas entre frases y entre párrafos se ajustan en Ajustes > Vocalis TTS.
• Funciona con o sin Internet: una vez instaladas las voces, nada de la lectura usa la red.
• Interfaz en tu Idioma: los textos siguen el idioma de Obsidian (español o, en cualquier otro caso, inglés).
• Español e Inglés:
  • En Ajustes > Vocalis TTS eliges el Idioma de lectura y, para ese idioma, su voz.
  • Una nota puede indicar su propio idioma en el frontmatter (lang: en o lang: es), sin cambiar el ajuste global.
• Catálogo de Voces Neuronales en Español:
  • 🇪🇸 Sharvard Femenina (es_ES-sharvard-medium, Speaker 1): Tono claro, natural y expresivo.
  • 🇪🇸 Sharvard Masculina (es_ES-sharvard-medium, Speaker 0): Locución masculina equilibrada.
  • 🇪🇸 Davefx Masculina (es_ES-davefx-medium): Ideal para audiolibros y resúmenes pausados.
  • 🇦🇷 Daniela Femenina (es_AR-daniela-high): Voz latinoamericana de alta fidelidad (descarga opcional en 1 clic).
• Catálogo de Voces Neuronales en Inglés (descarga opcional):
  • 🇺🇸 LJSpeech Femenina (en_US-ljspeech-medium): Voz por defecto del instalador; dataset de dominio público.
  • 🇺🇸 Lessac Femenina (en_US-lessac-medium): Voz clara y natural.
  • 🇺🇸 Ryan Masculina (en_US-ryan-medium): Locución masculina natural.

📁 Estructura del Repositorio

Vocalis TTS/
├── LICENSE                       # Licencia MIT (Mack Chirinos, 2026)
├── README.md                     # Documentación de usuario y despliegue
├── manifest.json                 # Manifiesto del plugin para Obsidian
├── styles.css                    # Estilos CSS del panel lateral y teleprompter
├── main.js                       # Código fuente del plugin para Obsidian
├── package.json                  # Metadatos del paquete npm
├── .gitignore                    # Reglas de exclusión para Git (archivos de contexto y temporales)
├── piper/                        # Motor Piper standalone y modelos locales
│   ├── piper.exe                 # Ejecutable nativo C++ para Windows x64
│   ├── *.dll                     # Bibliotecas dinámicas (ONNX Runtime, espeak-ng, etc.)
│   ├── espeak-ng-data/           # Diccionarios y datos fonéticos
│   └── models/                   # Modelos neuronales ONNX (.onnx y .json)
│       ├── es_ES-sharvard-medium.onnx (+ .json)
│       ├── es_ES-davefx-medium.onnx (+ .json)
│       ├── es_AR-daniela-high.onnx (+ .json)
│       ├── en_US-lessac-medium.onnx (+ .json)
│       └── en_US-ryan-medium.onnx (+ .json)
└── scripts/
    ├── vocalis-setup.cmd         # Instalador para usuarios: motor y voces
    ├── check-upstream.mjs        # Vigilante semanal de Piper y voces
    ├── selfcheck.js              # Comprobación de la lógica (npm test)
    ├── download-voice.ps1        # Descarga de voces adicionales (Daniela, Lessac, Ryan)
    ├── install-to-vault.ps1      # Despliegue y sincronización rápida en un Vault de Obsidian
    └── test-piper.ps1            # Test de síntesis de voz en PowerShell

⌨️ Atajos de Teclado y Controles

También puedes hacer clic en el icono de volumen en la barra Ribbon izquierda o en el menú contextual del editor. El comando Abrir panel de Vocalis muestra el panel lateral.

🚀 Instalación y Despliegue en Obsidian

Opción 1: Instalador (recomendada)

1. Instala y activa Vocalis TTS desde Plugins de la comunidad.
2. Descarga vocalis-setup.cmd (también desde el botón del panel del plugin) y ábrelo con doble clic. Elige tu vault y tus voces: Sharvard (español), LJSpeech (inglés) o ambas.
3. Pulsa Volver a comprobar en el panel. No hace falta reiniciar Obsidian.

El instalador no está firmado, así que Windows puede avisar: pulsa Más información → Ejecutar de todos modos. Es texto legible, por si quieres revisarlo. El plugin no descarga nada por sí mismo, porque las normas de Obsidian no permiten que un plugin instale sus dependencias.

Opción 2: Desde el repositorio (avanzado)

Clona el repositorio, descarga las voces con download-voice.ps1 y ejecuta el script indicando la ruta de tu Vault:

powershell -ExecutionPolicy Bypass -File .\scripts\install-to-vault.ps1 -VaultPath "C:\Ruta\A\Tu\Vault"

Opción 3: Instalación Manual

Si ya tienes Piper y sus modelos, basta indicar ambas rutas en Ajustes > Vocalis TTS. Si no:

1. Crea la carpeta vocalis-tts dentro de tu Vault en: <Tu_Vault>/.obsidian/plugins/vocalis-tts/
2. Copia los archivos main.js, manifest.json, styles.css y la carpeta piper/ dentro de dicha ubicación.
3. Abre Obsidian, ve a Ajustes > Plugins de la comunidad y activa Vocalis TTS.

🎙️ Descargar Voces Adicionales (Opcional)

powershell -ExecutionPolicy Bypass -File .\scripts\download-voice.ps1 -Voice english

Luego ejecuta install-to-vault.ps1: copia al vault los modelos que falten. El plugin los detecta solo; las voces no instaladas aparecen marcadas en Ajustes.

🔒 Uso de Red y Archivos Fuera del Vault

• Red: el plugin no usa la red. Solo el instalador y download-voice.ps1 descargan, una vez, el motor desde GitHub (rhasspy/piper) y las voces desde Hugging Face (rhasspy/piper-voices), porque pesan demasiado para distribuirse con el plugin. Si esas fuentes no responden, el instalador usa copias idénticas de vocalis-engine, y cada archivo debe coincidir con un SHA-256 fijo.
• Actualizaciones: nada se actualiza solo. Cuando se publica una actualización probada, Ajustes lo indica y basta con repetir el instalador, que cambia solo lo necesario.
• Vigilante del repositorio: una tarea semanal de GitHub Actions comprueba estas fuentes y abre un issue si hay novedades. No se ejecuta en tu equipo.
• Archivos fuera del vault: durante la lectura se escriben audios breves en la carpeta temporal del sistema, que se borran al instante, y se ejecuta el piper.exe configurado.

🎖️ Reconocimientos y Autoría (Credits & Attribution)

Vocalis TTS es posible gracias al trabajo de creadores y proyectos de código abierto excepcionales:

• Rhasspy Piper TTS: Motor neuronal rápido y local desarrollado por Michael Hansen (@synesthesiam) y la comunidad de Rhasspy / Nabu Casa. Licenciado bajo MIT y Apache 2.0.
• eSpeak-NG: Motor de fonemización y reglas fonéticas de texto a habla.
• Datasets y Modelos Neuronales:
  • Sharvard: Conjunto de frases fonéticas Spanish Harvard Sentences, entrenado para Piper con locutores femenino y masculino de España.
  • Davefx: Modelo narrativo de locutor masculino en español de España.
  • Daniela: Modelo neuronal de locutora femenina en español latinoamericano (Argentina).
  • LJSpeech, Lessac y Ryan: Modelos en inglés de Estados Unidos.
  • Licencias de los datasets según la ficha oficial de cada voz en Piper Voices: Sharvard, CC BY 3.0; Davefx, CC0; Daniela, CC BY-SA 4.0; LJSpeech, dominio público; Ryan, CC BY-NC-SA 4.0 (no comercial); Lessac, licencia Blizzard 2013 con fines de investigación. Por eso Lessac y Ryan son opcionales y solo se descargan de su fuente oficial.
• Motor: Piper y piper-phonemize (MIT), eSpeak-NG (GPL-3.0) y ONNX Runtime (MIT). Licencias y código fuente en vocalis-engine.
• Obsidian: Plataforma de gestión del conocimiento extensible desarrollada por Dynalist Inc.

🔄 Historial de Versiones

v1.5.0

• Instalador con respaldo: si una fuente oficial no responde, usa copias idénticas de vocalis-engine, con el mismo SHA-256.
• LJSpeech es la nueva voz inglesa del instalador, por su licencia abierta. Quien ya eligió Lessac o Ryan conserva su voz.
• Actualizaciones controladas: Ajustes avisa cuando hay un motor o voces nuevos; repetir el instalador cambia solo lo necesario.
• Avisos de licencia del motor y atribuciones de las voces.

v1.4.0

• Instalador de un clic (vocalis-setup.cmd): instala el motor y las voces elegidas desde sus fuentes oficiales y verifica su SHA-256.
• Guía en el panel cuando falta el motor, con el botón para descargar el instalador y Volver a comprobar, sin reiniciar Obsidian.
• README: declaración del uso de red y de los archivos fuera del vault.

v1.3.0

• Resaltado renovado: ya no se queda quieto en notas largas ni se pierde al alternar lectura y edición o al cambiar de pestaña. Resalta frases con negritas o enlaces y filas de tabla, distingue frases repetidas y no mueve tu cursor.
• Interfaz en español e inglés, según el idioma de Obsidian. El idioma de lectura de una instalación nueva sigue al de la interfaz.
• Sin avisos molestos: iniciar, detener o cambiar de voz ya no muestran notificaciones; solo quedan los errores.
• Audio más fluido: un solo proceso de Piper por lectura, tres frases preparadas por adelantado y silencios recortados. Nuevos ajustes de pausa entre frases y entre párrafos (reemplazan a Pausa entre oraciones).
• Corrección: reanudar tras pausar durante la síntesis ya no deja la lectura atascada.
• download-voice.ps1 también descarga Sharvard y Davefx.

v1.2.0

• Panel rediseñado: tarjeta con play redondo, iconos nativos de Obsidian en lugar de emojis y chips de voz y velocidad.
• Borrar de «Continuar escuchando»: la ✕ de cada fila quita la posición guardada de esa nota (la nota no se toca).

v1.1.0

• Voces en inglés (Lessac y Ryan) y selector de idioma en Ajustes, con la voz elegida por idioma. Las notas pueden fijar su idioma con lang: en el frontmatter.
• Panel en la barra lateral derecha en lugar del reproductor flotante, con la lista Continuar escuchando.
• La memoria de lectura sobrevive a renombrar o mover notas y se limpia al borrarlas.
• No se leen las URLs sueltas; las tablas se leen por filas.
• Corrección: la detección automática de piper.exe y de la carpeta de modelos ahora encuentra la carpeta del plugin dentro del vault.
• Corrección: pausar justo cuando arranca una frase ya no salta a la siguiente.

v1.0.3

• Prefetching Asíncrono (Latencia Cero entre Frases): Síntesis anticipada en segundo plano de la siguiente frase mientras se reproduce la actual. Elimina completamente las pausas muertas entre frases en voces pesadas de alta fidelidad como Daniela (Argentina High), permitiendo transiciones instantáneas y fluidas.
• Teleprompter Universal Infalible: Algoritmo de mapeo DOM con colapso de espacios en blanco en Modo Lectura, eliminando pérdidas de resaltado causadas por saltos de línea internos o etiquetas Markdown anidadas (<strong>, <em>, <a>). Soporte de resaltado continuo en elementos contenedores y eventos dinámicos de cambio de vista.
• Reactividad Instantánea en Controles: Cancelación inmediata de procesos huérfanos de Piper al saltar, pausar o usar la barra de progreso (seek-bar), liberando la CPU al 100% de inmediato.
• Depuración de Metadatos Markdown: Filtrado automático de cabeceras de callouts (> [!NOTE]) y símbolos sintácticos huérfanos para una locución auditiva limpia.

v1.0.2

• Corrección Crítica de Audio (Fidelidad Cristalina): Solución definitiva al problema de distorsión y ruido parasitario en Windows provocado por la traducción CRLF en el stdout de C++. Se implementa síntesis binaria nativa directa con ciclo de vida efímero en os.tmpdir() y limpieza inmediata al pasar a memoria RAM (Blob URL).
• Gestión de Memoria y Recursos: Revocación proactiva de objetos Blob URL (URL.revokeObjectURL) en pausas y cambios de frase para evitar fugas de memoria en Chromium/Obsidian.

v1.0.1

• Síntesis en Memoria (Zero Disk I/O): Transmisión directa del audio sintetizado a la memoria RAM vía stdout de Piper. Se elimina la creación, lectura y borrado de archivos .wav temporales en disco.
• CSS Linter Compliance: Eliminación total de declaraciones !important en styles.css mediante selectores de mayor especificidad para máxima compatibilidad con temas de la comunidad.
• Seguridad: Validación estricta de rutas ejecutables y aislamiento seguro de argumentos en child_process.spawn.
• Atestación Criptográfica: Configuración de GitHub Actions para firma de procedencia (Artifact Attestations).

v1.0.0

• Lanzamiento inicial con teleprompter dual (Modo Edición y Modo Lectura), velocidad en tiempo real de 0.75x a 2.5x con pitch preservado, memoria independiente por nota y voces neuronales en español.

📄 Licencia

Este proyecto está distribuido bajo la Licencia MIT - creado y mantenido por Mack Chirinos (2026).