> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.rhombus.community/llms.txt
> Use this file to discover all available pages before exploring further.

# Recuperar audio del Audio Gateway A100

> Descarga audio grabado de un Rhombus A100 Audio Gateway usando la API: obtén manifiestos MPD de DASH, recupera segmentos y reproduce audio mediante WAN VOD.

<Note>
  Esta página fue traducida automáticamente. Si encuentra errores o tiene sugerencias, [contáctenos](mailto:support@rhombus.com).
</Note>

En esta guía, aprenderás a recuperar **audio grabado** de un Rhombus **A100 Audio Gateway** usando la API de Rhombus. Vas a:

1. Llamar a la API para obtener las plantillas de URI de medios
2. Generar un token de sesión federado para la reproducción por WAN
3. Descargar el MPD de DASH y los segmentos de audio
4. Opcionalmente convertir el audio Opus/WebM resultante usando ffmpeg

Rhombus expone el acceso a los medios mediante **plantillas de URI** en lugar de devolver los bytes de audio sin procesar directamente desde una única respuesta REST.

## Requisitos previos

<Note>
  Todas las llamadas a la API en esta guía usan los siguientes encabezados de autenticación:

  ```http theme={null}
  Content-Type: application/json
  x-auth-scheme: api-token
  x-auth-apikey: YOUR_API_KEY
  ```

  URL base: `https://api2.rhombussystems.com`
</Note>

**Necesitarás:**

* Un UUID del A100 Audio Gateway (cadena de estilo DeviceFacetUuid / RUUID de Rhombus)
* Audio grabado que exista y esté disponible (determinado por las licencias de tu dispositivo y la configuración de grabación)
* Un cliente capaz de:
  * Realizar solicitudes HTTP
  * Analizar XML (para el manifiesto MPD)
  * Escribir los bytes binarios de los segmentos en disco

## Pasos de implementación

<Steps>
  <Step title="Obtener los URIs de medios del A100 Audio Gateway">
    Llama al endpoint `getMediaUris` para recuperar las plantillas de URI de tu audio gateway.

    **Endpoint:** `POST /api/audiogateway/getMediaUris`

    ```bash theme={null}
    curl --request POST \
      --url https://api2.rhombussystems.com/api/audiogateway/getMediaUris \
      --header 'Content-Type: application/json' \
      --header 'x-auth-scheme: api-token' \
      --header 'x-auth-apikey: YOUR_API_KEY' \
      --data '{
        "gatewayUuid": "AAAAAAAAAAAAAAAAAAAAAA.v0"
      }'
    ```

    **Campos relevantes de la respuesta:**

    | Campo                    | Descripción                                                 |
    | ------------------------ | ----------------------------------------------------------- |
    | `wanVodMpdUriTemplate`   | Plantilla MPD de WAN VOD (úsala para audio grabado por WAN) |
    | `wanLiveOpusUri`         | URI de la transmisión Opus en vivo por WAN                  |
    | `wanLiveMpdUri`          | URI MPD en vivo por WAN                                     |
    | `lanVodMpdUrisTemplates` | Plantillas de LAN VOD                                       |
  </Step>

  <Step title="Generar un token de sesión federado">
    El acceso al MPD por WAN requiere un token de sesión federado de corta duración añadido como parámetros de consulta.

    **Endpoint:** `POST /api/org/generateFederatedSessionToken`

    ```bash theme={null}
    curl --request POST \
      --url https://api2.rhombussystems.com/api/org/generateFederatedSessionToken \
      --header 'Content-Type: application/json' \
      --header 'x-auth-scheme: api-token' \
      --header 'x-auth-apikey: YOUR_API_KEY' \
      --data '{
        "domain": ".rhombussystems.com",
        "durationSec": 60
      }'
    ```

    **Respuesta:** Devuelve `federatedSessionToken`

    <Tip>
      Elige un `durationSec` lo suficientemente largo para obtener el MPD y todos los segmentos del rango solicitado. Para descargas grandes (hasta 24 horas), aumenta este valor según corresponda.
    </Tip>
  </Step>

  <Step title="Construir la URL del MPD de WAN VOD">
    Toma el `wanVodMpdUriTemplate` del Paso 1 y realiza la sustitución de cadenas:

    * Reemplaza `{START_TIME}` con la hora de inicio solicitada (en segundos)
    * Reemplaza `{DURATION}` con la duración solicitada (en segundos)

    <Warning>
      **¡Las unidades de las marcas de tiempo importan!**

      Los endpoints de audio de Rhombus usan **segundos desde la época** (`startTimeSec`, `durationSec`). Si tus marcas de tiempo están almacenadas en milisegundos, conviértelas:

      ```text theme={null}
      startTimeSec = startTimeMs / 1000
      durationSec = durationMs / 1000
      ```
    </Warning>
  </Step>

  <Step title="Obtener el MPD con el token federado">
    Añade los parámetros de consulta de autenticación a tu URL del MPD:

    ```text theme={null}
    <mpdUri>?x-auth-scheme=federated-token&x-auth-ft=<TOKEN>
    ```

    Este MPD es un manifiesto DASH que describe cómo obtener el segmento de inicialización y los segmentos de audio posteriores.
  </Step>

  <Step title="Descargar y unir los segmentos">
    Descarga los segmentos en orden, añadiendo los mismos parámetros de consulta `?x-auth-scheme=federated-token&x-auth-ft=<TOKEN>` que usaste para el MPD: los segmentos se sirven desde el mismo host de WAN y usan la misma autenticación:

    1. **Segmento de inicialización** (p. ej., `seg_init_audio.hdr`)
    2. **Segmentos de medios** (p. ej., `seg_1.webm`, `seg_2.webm`, ...)

    <Info>
      Cada segmento dura **2 segundos**. Calcula el número de segmentos:

      ```text theme={null}
      numSegments = durationSec / 2
      ```
    </Info>

    Escribe los bytes del encabezado de inicialización seguidos de los bytes de cada segmento para producir un archivo de audio WebM/Opus válido (48 kHz, mono).
  </Step>
</Steps>

***

## Ejemplo completo en Python

Este ejemplo implementa el flujo de trabajo completo descrito anteriormente:

```python theme={null}
import requests

BASE_URL = "https://api2.rhombussystems.com"
API_KEY = "YOUR_API_KEY"

HEADERS = {
    "Content-Type": "application/json",
    "x-auth-scheme": "api-token",
    "x-auth-apikey": API_KEY,
}


def generate_federated_token(domain: str, duration_sec: int) -> str:
    """Genera un token de sesión federado de corta duración para acceso por WAN."""
    url = f"{BASE_URL}/api/org/generateFederatedSessionToken"
    resp = requests.post(
        url, headers=HEADERS, json={"domain": domain, "durationSec": duration_sec}
    )
    resp.raise_for_status()
    return resp.json()["federatedSessionToken"]


def get_audio_gateway_media_uris(gateway_uuid: str) -> dict:
    """Obtiene las plantillas de URI de medios para un audio gateway."""
    url = f"{BASE_URL}/api/audiogateway/getMediaUris"
    resp = requests.post(url, headers=HEADERS, json={"gatewayUuid": gateway_uuid})
    resp.raise_for_status()
    return resp.json()


def build_mpd_uri(template: str, start_time_sec: int, duration_sec: int) -> str:
    """Sustituye los marcadores de posición en la plantilla de URI del MPD."""
    return template.replace("{START_TIME}", str(start_time_sec)).replace(
        "{DURATION}", str(duration_sec)
    )


def download_wan_vod_audio(
    gateway_uuid: str, start_time_sec: int, duration_sec: int, out_path: str
):
    """Descarga audio grabado de un Rhombus A100 Audio Gateway."""
    # Paso 1: Obtener los URIs de medios
    media = get_audio_gateway_media_uris(gateway_uuid)
    mpd_template = media["wanVodMpdUriTemplate"]

    # Paso 2: Generar el token federado
    ft = generate_federated_token(domain=".rhombussystems.com", duration_sec=60)

    # Paso 3: Construir la URL del MPD
    mpd_uri = build_mpd_uri(mpd_template, start_time_sec, duration_sec)

    # Paso 4: Obtener el MPD (autenticado mediante la cadena de consulta)
    auth_qs = f"?x-auth-scheme=federated-token&x-auth-ft={ft}"
    mpd_resp = requests.get(mpd_uri + auth_qs)
    mpd_resp.raise_for_status()

    # Paso 5: Descargar el segmento de inicialización y los segmentos de medios.
    # Se sirven desde el mismo host de WAN que el MPD, así que autentícalos con
    # los parámetros de consulta del token federado, no con el encabezado de API key.
    init_uri = mpd_uri.replace("file.mpd", "seg_init_audio.hdr")
    num_segments = duration_sec // 2

    with open(out_path, "wb") as f:
        # Descargar el segmento de inicialización
        init_resp = requests.get(init_uri + auth_qs)
        init_resp.raise_for_status()
        f.write(init_resp.content)

        # Descargar los segmentos de medios
        for i in range(1, int(num_segments) + 1):
            seg_uri = mpd_uri.replace("file.mpd", f"seg_{i}.webm")
            seg_resp = requests.get(seg_uri + auth_qs)
            seg_resp.raise_for_status()
            f.write(seg_resp.content)


if __name__ == "__main__":
    gateway_uuid = "AAAAAAAAAAAAAAAAAAAAAA.v0"
    start_time_sec = 1700000000  # Ejemplo: 14 de noviembre de 2023
    duration_sec = 60  # 1 minuto (máx.: 86400 segundos / 24 horas)

    download_wan_vod_audio(
        gateway_uuid=gateway_uuid,
        start_time_sec=start_time_sec,
        duration_sec=duration_sec,
        out_path="rhombus_audio.webm",
    )
    print("Wrote rhombus_audio.webm")
```

## Convertir audio con ffmpeg

El audio descargado está en formato **Opus/WebM** (48 kHz, mono). Puedes convertirlo a otros formatos usando ffmpeg:

<CodeGroup>
  ```bash WAV (16-bit PCM) theme={null}
  ffmpeg -i rhombus_audio.webm -acodec pcm_s16le rhombus_audio.wav
  ```

  ```bash MP3 theme={null}
  ffmpeg -i rhombus_audio.webm rhombus_audio.mp3
  ```
</CodeGroup>

## Solución de problemas

<AccordionGroup>
  <Accordion title="Manifiestos vacíos o segmentos faltantes">
    **Causa:** La sustitución de la plantilla usa unidades de tiempo incorrectas.

    **Solución:** Si tus marcas de tiempo están en milisegundos pero la plantilla espera segundos, conviértelas:

    ```python theme={null}
    start_time_sec = start_time_ms // 1000
    duration_sec = duration_ms // 1000
    ```
  </Accordion>

  <Accordion title="La reescritura del MPD no coincide con tu plantilla">
    **Causa:** El código asume que el nombre del archivo MPD es `file.mpd`.

    **Solución:** Si tu plantilla usa un nombre de archivo diferente, ajusta la lógica de reemplazo de cadenas:

    ```python theme={null}
    # Lógica actual
    init_uri = mpd_uri.replace("file.mpd", "seg_init_audio.hdr")

    # Ajusta para que coincida con tu nombre de archivo real
    init_uri = mpd_uri.replace("your_filename.mpd", "seg_init_audio.hdr")
    ```
  </Accordion>

  <Accordion title="El token expira antes de que se complete la descarga">
    **Causa:** La duración del token federado es demasiado corta para descargas de audio grandes.

    **Solución:** Aumenta `durationSec` al generar el token. Para descargas de 24 horas, es posible que necesites duraciones considerablemente más largas para obtener todos los segmentos.

    ```python theme={null}
    ft = generate_federated_token(domain=".rhombussystems.com", duration_sec=300)  # 5 minutos
    ```
  </Accordion>
</AccordionGroup>

## Referencia de la API

Los siguientes endpoints se usan en esta guía. Visita la pestaña [API Reference](/api-reference) para ver los esquemas completos de solicitud y respuesta.

* `POST /api/audiogateway/getMediaUris` — Obtener los URIs de medios del Audio Gateway
* `POST /api/org/generateFederatedSessionToken` — Generar un token de sesión federado