API Local

<- volver a la raíz de la documentación  

Qué hace el API Local

Audio Forge incluye un pequeño servidor incorporado 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, el API Local soporta exactamente los mismos comandos. La diferencia es que se ejecuta completamente en tu máquina sin ninguna configuración: no hay que instalar un broker ni configurar una red.

Activando el API Local

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

Puedes configurar:

• Palanca de Habilitado (por defecto: activado).
• Número de Puerto (por defecto: 8329).
• Palanca de Escuchar en LAN (por defecto: desactivado). Cuando está activada, los dispositivos en tu red local pueden acceder al API. Cuando está desactivada, solo el software en la misma máquina puede conectarse.
• Clave API (autogenerada). Se requiere al conectarse desde otro dispositivo en la red. Puedes copiarla o regenerarla desde Configuración.

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

Inicio rápido

Abre una terminal y prueba:

# Ver qué está sonando ahora mismo
curl http://localhost:8329/api/state

# Listar cada biblioteca y categoría
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 el API Local habilitado, recibirás respuestas en JSON de inmediato.

Endpoints HTTP

GET /api/state

Devuelve un snapshot en JSON de lo que Audio Forge está haciendo en este momento:

{
  "libraryUuid": "...",
  "libraryName": "[Default]",
  "musicPlaying": true,
  "ambiancePlaying": false,
  "musicVolume": 0.75,
  "ambianceVolume": 0.5,
  "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. En caso de éxito:

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

En caso de error:

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

WebSocket

Para herramientas que desean 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 por POST a /api/command:

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

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

Recibiendo actualizaciones

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

Las actualizaciones de estado se suavizan (250 ms) para que no te inundes durante cambios rápidos como barridos 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 emparejar 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 una categoría: reanuda toda la sección.
• Con una categoría: la selecciona y reproduce.
• La ambientación utiliza semántica de alternancia. Reproducir una categoría de Ambientación ya activa la apaga.

pause

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

stop

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

setActiveLibrary

Cambia la biblioteca activa por UUID o nombre.

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

setVolume

Ajusta el volumen de toda una sección (0.0 a 1.0), o de una categoría específica dentro de una sección.

{"command": "setVolume", "section": "Music", "value": 0.65}
{"command": "setVolume", "section": "Ambiance", "value": 0.5,
  "categoryName": "Rain", "transitionMs": 1000}

El transitionMs opcional controla cuán rápidamente el volumen cambia al nuevo nivel (por defecto: 500 ms).

playEcho

Activa un sonido de Eco de una sola vez.

{"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 una configuración al MQTT (si está conectado). Útil para automatización avanzada.

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

Manejo de errores

Si un comando no se puede ejecutar (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": "categoría no encontrada"}
{"ok": false, "error": "sección requerida"}
{"ok": false, "error": "json inválido"}

Seguridad

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

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

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

Ejemplos:

# Usando el encabezado Authorization
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 API
wscat -c "ws://192.168.0.10:8329/ws?apiKey=your-api-key-here"

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

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