home@slashpaf ~ $

API Local

<- volver a la raíz del documento  

¿Qué hace la API Local?

Audio Forge incluye un pequeño servidor integrado 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 utilizas la integración de MQTT, la API Local admite los mismos comandos exactos. La diferencia es que se ejecuta completamente en tu máquina sin ninguna configuración: no se necesita instalar un broker, ni configurar una red.

Habilitar la API Local

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

Puedes configurar:

  • Activado (por defecto: activado).
  • Número de Puerto (por defecto: 8329).
  • Escuchar en LAN (por defecto: 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.

Primeros pasos

Abre una terminal e intenta:

# See what's playing right now
curl http://localhost:8329/api/state

# List every library and category
curl http://localhost:8329/api/catalog

# List one-shot Echo sounds that are playing now
curl http://localhost:8329/api/echoes/active

# Play a category
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, recibirás respuestas en formato JSON inmediatamente.

Puntos finales HTTP

MétodoRutaDescripción
GET/api/stateEstado de reproducción actual
GET/api/catalogCatálogo completo de bibliotecas y categorías
GET/api/echoes/activeSonidos de un solo disparo Echo que se están reproduciendo actualmente
POST/api/commandEjecutar un comando (cuerpo JSON)

GET /api/state

Devuelve una instantánea JSON de lo que Audio Forge está haciendo en este momento:

{
  "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.5}
}

Todos los campos de volumen utilizan la escala de visualización de la aplicación, desde 0.0 hasta 1.0. Para Música y Ambiente, 0.5 es el volumen normal (unidad) y 1.0 es el máximo aumentado. Para Echoes, 1.0 es el volumen normal.

categoryVolume contiene valores de tiempo de ejecución actuales y puede ser escaso. Utiliza el volume de cada categoría desde /api/catalog cuando necesites un valor completo para cada categoría, incluidas las categorías que aún no se han utilizado.

GET /api/catalog

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

{
  "activeLibraryUuid": "...",
  "libraries": [
    {
      "uuid": "...",
      "name": "[Default]",
      "music": [{
        "uuid": "...",
        "name": "Battle",
        "enabledInForge": true,
        "trackCount": 3,
        "volume": 0.5
      }],
      "ambiance": [{
        "uuid": "...",
        "name": "Rain",
        "enabledInForge": false,
        "trackCount": 0,
        "volume": 0.5
      }]
    }
  ]
}
  • enabledInForge indica si la categoría es visible y está habilitada en Forge.
  • trackCount es el número de pistas reproducibles instaladas actualmente para esa categoría.
  • volume es el volumen efectivo de la categoría en la escala 0.0 a 1.0. Está presente para cada categoría, incluidas las categorías inactivas.

Para una categoría activa, el catálogo informa su volumen de ejecución actual. Para una categoría inactiva, informa el volumen objetivo configurado, o 0.5 cuando no existe un objetivo. Los ajustes de ejecución no reemplazan el objetivo configurado. Cuando una categoría se reinicia, se utiliza un valor de comando explícito si está presente; de lo contrario, se utiliza el objetivo configurado. El ajuste de ejecución anterior no se reutiliza. Restaurar un Enlace de Estado aplica los volúmenes de ejecución registrados en ese enlace.

GET /api/echoes/active

Devuelve una instantánea de cada sonido de un solo disparo Echo que se está reproduciendo actualmente. Los disparos simultáneos se devuelven como entradas separadas, incluso si utilizan la misma categoría o archivo de sonido.

{
  "count": 1,
  "sampledAt": "2026-07-24T12:00:02.500Z",
  "echoes": [
    {
      "playbackId": "7b304347-410f-4eaf-bad7-4e8488778302",
      "categoryUuid": "2e4d51f1-11ce-46af-a411-0c6bc2c420cb",
      "categoryName": "Thunder",
      "fileName": "thunder-01.wav",
      "startedAt": "2026-07-24T12:00:00.000Z",
      "durationMs": 10000,
      "positionMs": 2500,
      "remainingMs": 7500,
      "progress": 0.25,
      "progressPercent": 25.0,
      "playing": true,
      "processingState": "ready"
    }
  ]
}
  • playbackId identifica de forma única este disparador específico. Dos reproducciones superpuestas del mismo categoría reciben diferentes ID.
  • sampledAt es cuándo Audio Forge generó la instantánea. Los valores de posición no se transmiten continuamente, por lo que los clientes deben solicitar una nueva instantánea cuando necesiten el progreso actual.
  • durationMs, remainingMs, progress y progressPercent son null cuando la duración del sonido no está disponible.
  • progress utiliza una escala 0.0 a 1.0. progressPercent utiliza 0.0 a 100.0.
  • fileName contiene solo el nombre del archivo, nunca una ruta del sistema de archivos local.
  • Los sonidos Echo terminados o detenidos se eliminan de la lista.

Los Echo comparten el valor global echoesVolume devuelto por /api/state. No hay un volumen de Echo por reproducción o por categoría.

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), conéctate a un WebSocket en:

ws://localhost:8329/ws

Enviar comandos

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

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

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

Recibir actualizaciones

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

tipoCuándo se envíaQué contiene
stateAl conectarse y cada vez que cambia la reproducciónIgual que GET /api/state
catalogAl conectarse y cuando cambian las bibliotecasIgual que GET /api/catalog
resultDespués de cada comando que envíasok, message o error, requestId
echoCuando se activa un sonido Echouuid, name, at

Las actualizaciones de estado se rebotan (250 ms) para que no se te inunde durante los cambios rápidos, como los barridos de volumen.

Los mensajes son objetos JSON planos. La carga útil no está anidada debajo de un campo data o payload. Ejemplos:

{"type": "state", "musicPlaying": true, "ambiancePlaying": false,
  "musicVolume": 0.5, "ambianceVolume": 0.5,
  "musicCategories": [], "ambianceCategories": [], "categoryVolume": {}}

{"type": "catalog", "activeLibraryUuid": "<uuid>", "libraries": []}

{"type": "result", "ok": true, "message": "play ok", "requestId": "request-1"}

{"type": "echo", "uuid": "<uuid>", "name": "Thunder",
  "at": "2026-07-18T12:34:56Z"}

Comandos

Todos los comandos utilizan el mismo esquema JSON que la integración de MQTT. Cada comando acepta una cadena requestId opcional que puedes utilizar para hacer coincidir las respuestas.

play

Reproducir o reanudar una sección, o seleccionar 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: selecciona y reproduce.
  • El Ambiente utiliza semántica de alternancia. Reproducir una categoría de Ambiente ya activa la desactiva.

pause

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

stop

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

setActiveLibrary

Cambiar la biblioteca activa por UUID o nombre.

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

setVolume

Establecer el volumen para toda la sección, o para una categoría específica dentro de una sección. Utiliza 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 la que el volumen se desvanece al nuevo nivel (por defecto: 500 ms).

La Música y el Ambiente utilizan la misma escala de visualización que la aplicación: 0.5 es el volumen normal (unidad) y 1.0 es el máximo aumentado. Los Echo no tienen un rango aumentado, por lo que 1.0 es el volumen normal. La API convierte estos valores de visualización en la ganancia de reproducción interna automáticamente.

nextTrack

Saltar a la siguiente pista en una categoría de Música o Ambiente activa. La categoría debe estar reproduciéndose.

{"command": "nextTrack", "section": "Music", "categoryUuid": "<uuid>"}
{"command": "nextTrack", "section": "Ambiance", "categoryName": "Rain"}

playEcho

Activar un sonido Echo de un solo disparo.

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

Si el comando se ejecuta correctamente, espera hasta que la reproducción de Echo esté registrada y devuelve sus campos de seguimiento y reproducción:

{
  "ok": true,
  "message": "echo played",
  "requestId": "play-thunder",
  "playbackId": "<playback-id>",
  "categoryUuid": "<category-uuid>",
  "categoryName": "Thunder",
  "fileName": "thunder-01.wav",
  "startedAt": "2026-08-09T12:00:00.000Z",
  "durationMs": 4000,
  "positionMs": 0,
  "remainingMs": 4000,
  "progress": 0.0,
  "progressPercent": 0.0,
  "playing": true,
  "processingState": "ready"
}

Utiliza el playbackId devuelto con stopEcho para detener solo esta instancia de reproducción. También puedes actualizar los valores actuales con GET /api/echoes/active.

stopEcho

Detener la reproducción activa de Echo utilizando exactamente un selector:

{"command": "stopEcho", "playbackId": "<playback-id>"}
{"command": "stopEcho", "categoryUuid": "<category-uuid>"}
{"command": "stopEcho", "categoryName": "Thunder"}
  • playbackId detiene solo esa instancia de reproducción. Obtén los ID de reproducción de GET /api/echoes/active.
  • categoryUuid detiene todos los Echo activos de esa categoría.
  • categoryName detiene todos los Echo activos cuya categoría tenga exactamente ese nombre. Si las categorías en varias bibliotecas comparten el mismo nombre, se detendrán todas las coincidencias.
  • El resultado incluye stoppedCount. Un selector sin coincidencias activas tiene éxito con stoppedCount: 0.
  • Para detener todos los Echo activos independientemente de la categoría, utiliza {"command": "stop", "section": "Echoes"}.

setCategoryEnabled

Habilitar o deshabilitar explícitamente una categoría en una sección.

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

Puedes habilitar una categoría y establecer su volumen de forma atómica incluyendo value. Si value se omite, se utiliza el volumen objetivo configurado de la categoría. Un ajuste de ejecución anterior no se reutiliza.

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

restoreState

Restaurar un estado guardado previamente desde un enlace de uso compartido creado por la aplicación.

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

setConfig

Pasar una configuración a la integración de MQTT (si está conectada). Útil para automatizaciones avanzadas.

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

Manejo de errores

Si un comando no se puede ejecutar (por ejemplo, no existe un nombre de categoría o falta un campo requerido), la respuesta contendrá "ok": false y un mensaje error que describe lo que salió mal.

{"ok": false, "error": "category not found"}
{"ok": false, "error": "section required"}
{"ok": false, "error": "invalid json"}

Seguridad

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

Si habilitas 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 de localhost. La clave se genera automáticamente y se muestra en Configuración → Control externo → API Local; pásala con cada solicitud utilizando uno de:

  • Encabezado: Authorization: Bearer <your-api-key>
  • Parámetro de consulta: ?apiKey=<your-api-key>

Ejemplos:

# Using the Authorization header
curl http://192.168.0.10:8329/api/state ^
  -H "Authorization: Bearer your-api-key-here"

# Using the query parameter
curl "http://192.168.0.10:8329/api/state?apiKey=your-api-key-here"

# Sending a command from another device
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 with API key
wscat -c "ws://192.168.0.10:8329/ws?apiKey=your-api-key-here"

Las solicitudes de 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. Todos los clientes conectados previamente necesitarán la nueva clave.

Comportamiento en segundo plano en dispositivos móviles

Los sistemas operativos móviles pueden suspender el manejo de HTTP y WebSocket entrantes cuando Audio Forge se ejecuta en segundo plano o cuando el dispositivo está bloqueado, incluso cuando la reproducción de audio nativa continúa. La API Local no se detiene deliberadamente, pero no puede garantizar la disponibilidad en segundo plano en iOS o Android.

Para un control remoto estable durante una sesión, mantén Audio Forge en primer plano y mantén la pantalla encendida. Esto evita depender de la ejecución en segundo plano que los sistemas móviles pueden detener en cualquier momento.