tennant.nvim

---

English

What is it?

tennant.nvim is a Neovim plugin that converts text to speech using each operating system's native TTS engine: say on macOS, PowerShell on Windows, and spd-say / espeak-ng / espeak / festival on Linux. No external Lua dependencies or paid APIs required.

Requirements

Installation

vim.pack.add (Neovim >= 0.12)

Add this to your init.lua:

vim.pack.add({ 'https://github.com/themakunga/tennant.nvim' })
require('tennant').setup()

lazy.nvim (recommended)

{
  'themakunga/tennant.nvim',
  event = 'VeryLazy',
  opts = {
    -- prefix = '<leader>tv', -- default prefix
  },
}

packer.nvim

use {
  'themakunga/tennant.nvim',
  config = function()
    require('tennant').setup()
  end,
}

vim-plug

Plug 'themakunga/tennant.nvim'

Then in your config:

require('tennant').setup()

vim packages (:h packages)

mkdir -p ~/.local/share/nvim/site/pack/plugins/start
git clone https://github.com/themakunga/tennant.nvim \
  ~/.local/share/nvim/site/pack/plugins/start/tennant.nvim

Add to your init.lua:

require('tennant').setup()

rocks.nvim

# in your rocks.toml
[plugins]
"tennant.nvim" = "scm"

Or in your config:

require('rocks').install('tennant.nvim')

Configuration

require('tennant').setup({
  prefix = '<leader>tv',
  language = 'en', -- 'es' (default) or 'en'
  tts = {
    -- backend = 'espeak-ng', -- optional; choose an installed engine
    -- voice = 'en', -- voice name for the chosen engine
    -- rate = 190, -- units and range depend on the engine
  },
})

Set language = 'en' for English announcements, spoken labels, and command/keymap descriptions. Spanish ('es') remains the default. File contents and external notifications are read without translation. tts.voice selects an installed voice; language does not automatically change it. See the options table at the end.

Keymaps

With the default prefix <leader>tv:

Commands

<leader>tvb starts at the nearest block to the cursor. Each <leader>tvp moves up one level through the whole file, then announces “No more nesting levels” when configured in English. Moving the cursor or editing text restarts traversal from the current position. Without a Treesitter parser, reading falls back to the current line.

Reading notifications

<leader>tvn or :TennantNotify opens a temporary window, announces the number of notifications captured during the session, and reads the first in arrival order. Press n for the next notification or x to cancel, stop speech, and close the window. Esc, :TennantStop, and <leader>tvs also cancel. The last notification announces the end; x closes the window. Your usual mappings remain intact outside it. New arrivals are included when starting another traversal; history is retained until Neovim exits.

Treesitter block types

When Treesitter is available, :TennantBlock identifies and announces the block type: function, method, arrow function, variable, constant, class, if block, for loop, while loop, try block, return, import, export.

---

Español

¿Qué es?

tennant.nvim es un plugin de Neovim que convierte texto en voz usando el motor TTS nativo de cada sistema operativo: say en macOS, PowerShell en Windows y spd-say / espeak-ng / espeak / festival en Linux. No requiere dependencias externas de Lua ni APIs de pago.

Requisitos

Instalación

vim.pack.add (Neovim >= 0.12)

Agrega esto a tu init.lua:

vim.pack.add({ 'https://github.com/themakunga/tennant.nvim' })
require('tennant').setup()

lazy.nvim (recomendado)

{
  'themakunga/tennant.nvim',
  event = 'VeryLazy',
  opts = {
    -- prefix = '<leader>tv', -- prefijo por defecto
  },
}

packer.nvim

use {
  'themakunga/tennant.nvim',
  config = function()
    require('tennant').setup()
  end,
}

vim-plug

Plug 'themakunga/tennant.nvim'

Luego en tu config:

require('tennant').setup()

vim packages (:h packages)

mkdir -p ~/.local/share/nvim/site/pack/plugins/start
git clone https://github.com/themakunga/tennant.nvim \
  ~/.local/share/nvim/site/pack/plugins/start/tennant.nvim

Agrega en tu init.lua:

require('tennant').setup()

rocks.nvim

# en tu rocks.toml
[plugins]
"tennant.nvim" = "scm"

O en tu config:

require('rocks').install('tennant.nvim')

Configuración

require('tennant').setup({
  prefix = '<leader>tv',
  language = 'es', -- 'es' (predeterminado) o 'en'
  tts = {
    -- backend = 'espeak-ng', -- opcional; fuerza un motor instalado
    -- voice = 'es', -- nombre de voz del motor seleccionado
    -- rate = 190, -- unidad y rango dependen del motor
  },
})

language cambia los avisos, las etiquetas leídas y las descripciones de comandos y atajos. El contenido del archivo y las notificaciones externas se leen sin traducir. tts.voice selecciona una voz instalada; language no cambia la voz automáticamente. Consulta la tabla de opciones al final.

Atajos de teclado

Con el prefijo por defecto <leader>tv:

Comandos

<leader>tvb inicia la lectura desde el bloque más cercano al cursor. Cada <leader>tvp sube un nivel hasta leer el archivo; después anuncia «No existen más niveles de anidación». Mover el cursor o editar el texto reinicia el recorrido desde la posición actual. Sin un parser de Treesitter, se lee la línea actual.

Lectura de notificaciones

<leader>tvn o :TennantNotify abre una ventana temporal, anuncia el total de notificaciones capturadas durante la sesión y lee la primera, en orden de llegada. Presiona n para leer la siguiente y x para cancelar, detener la voz y cerrar la ventana. Esc, :TennantStop y <leader>tvs también cancelan. Al terminar, se anuncia que no hay más notificaciones; x cierra la ventana. Tus atajos habituales se conservan fuera de ella. Las notificaciones nuevas se incluyen al iniciar otro recorrido; el historial se conserva hasta cerrar Neovim.

Bloques reconocidos por Treesitter

Cuando Treesitter está disponible, :TennantBlock identifica y anuncia el tipo de bloque: función, método, función flecha, variable, constante, clase, bloque if, bucle for, bucle while, bloque try, retorno, importación, exportación.

---

Development / Desarrollo

See CONTRIBUTING.md for hooks, tests, branch policy and daily pre-releases. Consulta esa guía para contribuir mediante PR hacia main. Security reports / Reportes de seguridad: SECURITY.md.

License

MIT

Options / Opciones

require('tennant').setup({ ... }) accepts / acepta:

English: On Linux, the first available engine is selected in this order: spd-say, espeak-ng, espeak, festival. Use tts.backend to choose another. All tts options are optional; an out-of-range value, unavailable engine, or option unsupported by the chosen engine raises a configuration error. Voice names and speed units depend on the engine. Example: tts = { backend = 'espeak-ng', voice = 'en', rate = 190, pitch = 55 }.

Español: En Linux, el primer motor disponible se elige en este orden: spd-say, espeak-ng, espeak, festival. Usa tts.backend para elegir otro. Todas las opciones de tts son opcionales; un valor fuera de rango, un motor inexistente o una opción que no admita el motor produce un error de configuración. El nombre de voz y las unidades de velocidad dependen del motor. Ejemplo: tts = { backend = 'espeak-ng', voice = 'es', rate = 190, pitch = 55 }.