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

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"}

GET /api/icon/{categoryUuid}

Devuelve la imagen del icono de una categoría. Utiliza el UUID de categoría de /api/catalog. La categoría debe pertenecer a una biblioteca activa. El parámetro de consulta opcional size establece el tamaño solicitado para los iconos de fuente y SVG, y utiliza 144 píxeles de forma predeterminada.

• Los iconos de fuente y SVG se renderizan como imágenes PNG y se tiñen con el color de la categoría.
• Si falta un archivo personalizado o no se puede rasterizar un SVG, la API utiliza el icono de fuente como alternativa.
• Los iconos PNG, JPG y JPEG personalizados se devuelven sin cambios; el parámetro size se ignora.
• Las respuestas correctas utilizan image/png o image/jpeg y pueden almacenarse en caché durante una hora.
• Si no se encuentra la categoría, la respuesta es 404 con {"error":"category not found"}.
• Si no se puede renderizar el icono, la respuesta es 500 con {"error":"failed to render icon"}.

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:

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"}

Detección de funciones

Las versiones más recientes de Audio Forge añaden funciones a la API. Así que una herramienta puede determinar qué características admite la aplicación en ejecución, el servidor anuncia su versión. Es el primer mensaje WebSocket, y GET /api/info devuelve lo mismo:

{"type": "hello", "apiVersion": 3,
  "features": {"aiDirector": {"available": true, "enabled": true},
               "roomControl": {"commands": ["play", "pause", "stop", "..."]}}}

Las versiones más antiguas de Audio Forge no envían ningún mensaje hello y no tienen /api/info: trata eso como apiVersion 1 y no llames a nada más reciente. Solo muestra o llama a las funciones del Director de IA cuando available y enabled sean ambos true.

Room control

Cuando alojas una sala en línea, puedes permitir que los invitados controlen Audio Forge desde la página de invitados. Dos comandos establecen quién puede (solo funcionan mientras la sala está abierta):

{"command": "setRoomDefaultPermission", "permission": "control"}
{"command": "setRoomGuestPermission", "clientId": "<guest clientId>", "permission": "listen"}

permission es "listen" (solo tú controlas Audio Forge) o "control". El estado de la sala en GET /api/state (room) incluye entonces defaultGuestPermission y un permission para cada entrada de guests (el efectivo: con "control" como predeterminado, aún puedes establecer un solo invitado en "listen"). room.chatMessages también lista lo que los invitados que controlan han hecho, como entradas con kind: "activity", command y params resueltos; las entradas de chat tienen kind: "chat". Los invitados que se unen o abandonan aparecen como entradas de actividad con command guestJoined, guestLeft, guestRemoved o guestReconnected. Mientras los invitados pueden controlar, Audio Forge también sube los iconos de las categorías al servidor de la sala para que la página de invitados pueda mostrarlos. Los invitados con control solo pueden ejecutar los comandos que figuran en features.roomControl.commands; la captura, la eliminación de invitados, la configuración, el Director de IA y los permisos permanecen contigo.

Director de IA

El Director de IA escucha tu mesa y cambia la música y el ambiente por ti. A través de la API local, puedes iniciarlo y detenerlo, elegir de dónde obtiene su audio, proporcionarle texto y seguir lo que entendió y hizo. Necesita que el Director de IA esté habilitado en la aplicación y que sus modelos estén instalados.

Commands

inputSource es "device" (el dispositivo de entrada elegido en Audio Forge, el valor predeterminado) o "remote" (audio enviado por tu herramienta a través de WebSocket).

{"command": "aiDirectorStart", "inputSource": "remote", "fresh": true}

Enviar texto

aiDirectorSendText es “dispara y olvida”: la respuesta solo confirma que el texto se ha puesto en cola. Al igual que con el habla, el Director de IA recopila lo que escucha durante unos segundos y luego decide qué, si es que algo, cambiar. Se rechaza a menos que el Director de IA se esté ejecutando.

{"command": "aiDirectorSendText", "text": "Heavy rain starts to fall on the old market square."}

Esto es útil para herramientas que ya tienen una transcripción, para sesiones basadas en texto y para probar cómo reacciona el Director de IA a una escena.

Estado

GET /api/ai_director/status, y el mensaje WebSocket ai_director, que se envía cada vez que algo cambia:

{"type": "ai_director", "available": true, "enabled": true, "entitled": true,
  "modelsReady": true, "state": "listening", "inputSource": "device",
  "sceneDescription": "Heavy rain over a market square", "lastTranscript": "...", "error": null}

Registro de actividad

El mensaje WebSocket ai_director_log contiene lo que el Director de IA escuchó y hizo. Se envía completo cuando te conectas (reset: true, las últimas 100 entradas), y luego solo nuevas entradas:

{"type": "ai_director_log", "reset": false,
  "entries": [{"id": 42, "at": "2026-10-27T15:20:48Z", "kind": "transcript", "text": "..."}]}

kind es transcript (lo que se escuchó), action (lo que cambió), error o info.

Para una visión más profunda, GET /api/ai_director/debug?since=<id> devuelve cada entrada después de id, incluyendo el prompt enviado al modelo de lenguaje y su respuesta sin procesar. Está destinado a la afinación, no a la visualización.

Enviar tu propio audio de micrófono

Con inputSource configurado en "remote", envía frames WebSocket binarios de audio sin procesar: 16 kHz, mono, firmado de 16 bits little-endian PCM. Audio Forge aplica su habitual detección de silencio, por lo que puedes transmitir continuamente. Los frames se ignoran mientras la fuente es "device". Solo un cliente WebSocket puede suministrar audio a la vez; cuando se desconecta, el Director de IA vuelve al dispositivo de entrada.

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.