API Local

<- volver a la raíz del documento  

Qué hace la API Local

Audio Forge incluye un pequeño servidor interno que se ejecuta en tu máquina. Permite que herramientas externas, como un plugin de Elgato Stream Deck, un script personalizado, o cualquier aplicación en tu PC, controlen la reproducción a través de HTTP o WebSocket, sin necesidad de software adicional.

Si ya usas la integración MQTT, la API Local soporta los mismos comandos. La diferencia es que se ejecuta completamente en tu máquina sin necesidad de configuración: no hay que instalar ningún broker ni configurar una red.

Activando la API Local

Ve a Configuración → Control Externo → API Local y asegúrate de que la función esté habilitada (viene activada por defecto).

Puedes configurar:

• Alternar Habilitado (predeterminado: activado).
• Número de Puerto (predeterminado: 8329).
• Alternar Escuchar en LAN (predeterminado: desactivado). Cuando está activado, los dispositivos en tu red local pueden acceder a la API. Cuando está desactivado, solo el software en la misma máquina puede conectarse.
• Clave de API (generada automáticamente). Requerida al conectarse desde otro dispositivo en la red. Puedes copiarla o regenerarla desde Configuración.

Una vez habilitada, Audio Forge escucha en http://localhost:8329. Si “Escuchar en LAN” está activado, escucha en todas las interfaces de red.

Inicio rápido

Abre un terminal y prueba:

# Ver lo que se está reproduciendo ahora
curl http://localhost:8329/api/state

# Listar todas las bibliotecas y categorías
curl http://localhost:8329/api/catalog

# Reproducir una categoría
curl -X POST http://localhost:8329/api/command ^
  -H "Content-Type: application/json" ^
  -d "{\"command\":\"play\",\"section\":\"Music\",\"categoryName\":\"Battle\"}"

Eso es todo, si Audio Forge se está ejecutando con la API Local habilitada, obtendrás respuestas JSON de inmediato.

Endpoints HTTP

GET /api/state

Devuelve una instantánea JSON de lo que está haciendo Audio Forge ahora mismo:

{
  "libraryUuid": "...",
  "libraryName": "[Default]",
  "musicPlaying": true,
  "ambiancePlaying": false,
  "musicVolume": 0.75,
  "ambianceVolume": 0.5,
  "echoesVolume": 1.0,
  "musicCategories": [{"uuid": "...", "name": "Battle"}],
  "ambianceCategories": [{"uuid": "...", "name": "Rain"}],
  "lastEcho": {"uuid": "...", "name": "Thunder", "at": "2025-06-01T12:34:56Z"},
  "categoryVolume": {"<uuid>": 0.8}
}

GET /api/catalog

Devuelve cada biblioteca con sus categorías de Música y Ambiente:

{
  "activeLibraryUuid": "...",
  "libraries": [
    {
      "uuid": "...",
      "name": "[Default]",
      "music": [{"uuid": "...", "name": "Battle"}],
      "ambiance": [{"uuid": "...", "name": "Rain"}]
    }
  ]
}

POST /api/command

Envía un comando JSON en el cuerpo de la solicitud. Al éxito:

{"ok": true, "message": "play ok"}

En caso de error:

{"ok": false, "error": "category not found"}

WebSocket

Para herramientas que quieren actualizaciones en tiempo real (como un plugin de Stream Deck que necesita mostrar el estado actual), conecta un WebSocket a:

ws://localhost:8329/ws

Enviando comandos

Envía los mismos objetos de comando JSON que enviarías con POST a /api/command:

{"command": "play", "section": "Music", "categoryName": "Battle"}

El servidor responde con un mensaje de resultado para cada comando.

Recibiendo actualizaciones

El servidor envía actualizaciones automáticamente cada vez que algo cambia. Cada mensaje tiene un campo type:

Las actualizaciones de estado tienen un tiempo de espera (250 ms) para que no te veas inundado durante cambios rápidos como ajustes de volumen.

Comandos

Todos los comandos usan el mismo esquema JSON que la integración MQTT. Cada comando acepta un requestId opcional que puedes usar para relacionar las respuestas.

play

Reproduce o reanuda una sección, o selecciona una categoría específica.

{"command": "play", "section": "Music"}
{"command": "play", "section": "Music", "categoryName": "Battle"}
{"command": "play", "section": "Ambiance", "categoryUuid": "<uuid>"}

• Sin categoría: reanuda toda la sección.
• Con categoría: la selecciona y la reproduce.
• Ambiente usa semántica de alternancia. Reproducir una categoría de Ambiente ya activa la apaga.

pause

{"command": "pause", "section": "Music"}

stop

{"command": "stop", "section": "Ambiance"}

setActiveLibrary

Cambia la biblioteca activa por UUID o por nombre.

{"command": "setActiveLibrary", "libraryName": "My Library"}
{"command": "setActiveLibrary", "libraryUuid": "<uuid>"}

setVolume

Ajusta el volumen de toda una sección, o de una categoría específica dentro de una sección. Usa value de 0.0 a 1.0, o de 0 a 100 con valueScale: percent.

{"command": "setVolume", "section": "Music", "value": 1.0}
{"command": "setVolume", "section": "Music", "value": 75, "valueScale": "percent"}
{"command": "setVolume", "section": "Echoes", "value": 0.5}
{"command": "setVolume", "section": "Ambiance", "value": 0.5,
  "categoryName": "Rain", "transitionMs": 1000}

El transitionMs opcional controla la rapidez con que el volumen se desvanece al nuevo nivel (por defecto: 500 ms).

playEcho

Activa un sonido de eco de un solo golpe.

{"command": "playEcho", "categoryName": "Thunder"}
{"command": "playEcho", "section": "Ambiance", "categoryUuid": "<uuid>"}

setCategoryEnabled

Habilita o deshabilita explícitamente una categoría en una sección.

{"command": "setCategoryEnabled", "section": "Ambiance",
  "categoryName": "Rain", "enabled": true}

restoreState

Restaura un estado previamente guardado desde un enlace compartido creado por la aplicación.

{"command": "restoreState", "link": "slashpaf://..."}

setConfig

Envía un ajuste de configuración a la integración MQTT (si está conectada). Útil para automatización avanzada.

{"command": "setConfig", "key": "someKey", "value": "someValue"}

Manejo de errores

Si un comando no puede ser ejecutado (por ejemplo, un nombre de categoría no existe o falta un campo requerido), la respuesta contendrá "ok": false y un mensaje de error describiendo qué salió mal.

{"ok": false, "error": "categoria no encontrada"}
{"ok": false, "error": "sección requerida"}
{"ok": false, "error": "json inválido"}

Seguridad

Por defecto, la API Local se vincula a 127.0.0.1 (solo localhost) y no es accesible desde otros dispositivos en tu red.

Si activas Escuchar en LAN, la API se vuelve accesible desde otros dispositivos. En ese caso, se requiere una clave de API para todas las solicitudes que no sean localhost. La clave se genera automáticamente y se muestra en Configuración → Control Externo → API Local; pásala con cada solicitud usando uno de estos métodos:

• Header: Authorization: Bearer <tu-clave-api>
• Parámetro de consulta: ?apiKey=<tu-clave-api>

Ejemplos:

# Usando el encabezado de autorización
curl http://192.168.0.10:8329/api/state ^
  -H "Authorization: Bearer your-api-key-here"

# Usando el parámetro de consulta
curl "http://192.168.0.10:8329/api/state?apiKey=your-api-key-here"

# Enviando un comando desde otro dispositivo
curl -X POST http://192.168.0.10:8329/api/command ^
  -H "Authorization: Bearer your-api-key-here" ^
  -H "Content-Type: application/json" ^
  -d "{\"command\":\"play\",\"section\":\"Music\",\"categoryName\":\"Battle\"}"

# WebSocket con clave de API
wscat -c "ws://192.168.0.10:8329/ws?apiKey=your-api-key-here"

Las solicitudes localhost nunca requieren una clave, incluso cuando el modo LAN está activado.

Puedes regenerar la clave de API en cualquier momento desde Configuración → Control Externo → API Local. Cualquier cliente previamente conectado necesitará la nueva clave.