Instalación y permisos

Tras la instalación y con los permisos correctos, los atajos globales y la escritura por voz se mantienen fiables. Las figuras son vistas previas de UI generadas automáticamente (escenas HTML + página de Releases en vivo). Puedes sustituir los PNG en public/screenshots/ por capturas reales en cualquier momento.

Requisitos

• macOS 14 o posterior
• Apple Silicon o Intel
• Opcional: claves API (BYOK) de ASR / LLM
• La escritura por voz real necesita: Micrófono + Accesibilidad
• Con la voz del sistema de Apple, además: Ajustes del Sistema → Privacidad y seguridad → Reconocimiento de voz

1. Descargar el instalador

1. Abrir Releases
   Ve a VoiceHotkey-releases · Latest.

2. Descargar el DMG
   Elige el archivo .dmg de macOS. No uses los archivos Source code como la app.

3. Abrir la imagen de disco
   Haz doble clic en el DMG y espera a la ventana de instalación.

Fig. 1 · Página de Releases (vista previa · install-01-releases.webp)

2. Instalar en una ruta estable

1. Arrastrar a Aplicaciones
   Arrastra VoiceHotkey.app a Aplicaciones, o a ~/Applications.

2. Expulsar el DMG (opcional)
   Puedes guardar el DMG como respaldo si lo prefieres.

3. Recordar la ruta
   Siempre inicia desde la misma ubicación, p. ej.

   • /Applications/VoiceHotkey.app
   • o ~/Applications/VoiceHotkey.app

Fig. 2 · Ventana de instalación del DMG (vista previa · install-02-dmg.webp)

Fig. 3 · Confirmar la ruta de la app (vista previa · install-03-path.webp)

No ejecutes a largo plazo desde Descargas

Iniciar desde ~/Downloads o una carpeta temporal hace que macOS trate Accesibilidad como otra app tras mover o volver a descargar — los atajos dejan de funcionar “al azar”. Instala primero en Aplicaciones y luego concede el acceso.

3. Primer inicio

1. Abrir la app
   Desde Launchpad o el Finder. Si Gatekeeper la bloquea, permítela en Privacidad y seguridad (las builds notarizadas van más fluidas).

2. Comprobar la barra de menú
   Debe aparecer un icono tipo micrófono a la derecha. Si falta, revisa el desbordamiento de la barra de menú o que la app siga en ejecución.

3. Completar el onboarding
   El primer inicio muestra Configuración rápida (bienvenida → permisos → plan → listo). Puedes conceder el acceso ahí o después en Ajustes del Sistema.

Fig. 4 · Icono de la barra de menú (vista previa · install-07-menubar.webp)

Fig. 5 · Permisos del onboarding (vista previa · install-06-onboarding.webp)

4. Conceder Accesibilidad

Necesario para atajos globales, insertar texto en el cursor e inyección de teclas. Sin esto, el atajo normalmente no hace nada.

1. Abre Ajustes del Sistema → Privacidad y seguridad → Accesibilidad.
2. Haz clic en + (o desbloquea) y agrega VoiceHotkey.app.
3. Confirma que la ruta coincide con la app que realmente ejecutas.
4. Activa el interruptor.
5. Si ves varias filas de “VoiceHotkey”: elimina las antiguas, deja solo la ruta actual, luego cierra y vuelve a abrir la app.

Fig. 6 · Accesibilidad (vista previa · install-04-accessibility.webp)

Abrir desde la app

Ajustes → General (o el onboarding) suele tener un botón que salta a Accesibilidad. Tras conceder, la barra de menú debería dejar de advertir “Need Accessibility”.

5. Conceder Micrófono

Obligatorio para el escritura por voz real. El modo demo puede omitir el micrófono; el uso en producción lo necesita.

1. Abre Ajustes del Sistema → Privacidad y seguridad → Micrófono.
2. Activa VoiceHotkey.
3. Acepta el aviso del sistema en la primera grabación si aparece.
4. Con micrófonos externos, revisa Ajustes del Sistema → Sonido → Entrada. Usa el mismo dispositivo en General de la app si se muestra un selector de micrófono.

5b. Reconocimiento de voz (solo motor Apple)

Con Apple Speech / SpeechAnalyzer, el sistema pide además el permiso de Reconocimiento de voz (SFSpeechRecognizer). Los motores en la nube (Doubao, Whisper, etc.) normalmente no dependen de él.

1. Abre Ajustes del Sistema → Privacidad y seguridad → Reconocimiento de voz.
2. Permite VoiceHotkey.
3. Si falta un idioma, descarga su paquete en Ajustes del Sistema o cambia de motor.

Fig. 7 · Micrófono (vista previa · install-05-microphone.webp)

6. Lista de comprobación de permisos

Comprobar	Esperado
Icono de la barra de menú	Visible, el menú se abre
Ajustes → General · permisos	Accesibilidad + micrófono concedidos; con motor Apple, también reconocimiento de voz
Pulsar el atajo	Overlay / cambio de estado (incluso en demo)
Ruta de instalación	Coincide con la entrada de Accesibilidad

¿Sigue fallando? Consulta Solución de problemas.

Siguiente

Configuración inicialModo demo, motor, atajos y una prueba real de escritura.

Atajos y grabaciónToque / mantener, Quick Send, cancelar.