# Componente Recorder | Docs de AudioDN

> Grabadora de voz en el navegador con forma de onda en vivo, reproductor de vista previa y subida directa a AudioDN.

Source: https://audiodeliverynetwork.com/es/docs/components/recorder/

---

# Recorder

Captura audio del micrófono en el navegador, previsualízalo con un mini reproductor y forma de onda, y luego sube una pista a AudioDN.

## Uso

Instala desde npm e importa el componente, luego coloca el elemento en tu página. Proporciona una clave API de subida del lado del cliente y, opcionalmente, un ID de colección al que subir. Con una `api-key`, la grabadora crea la sesión de subida **y** la pista en una sola petición, y luego sube la grabación (PUT). Si la clave API está limitada a una colección, el ID de colección se resuelve automáticamente.

La grabación comienza tras una breve cuenta atrás 3‑2‑1, y los nombres de archivo se generan automáticamente a partir de la marca de tiempo UTC. El navegador elige un tipo MIME compatible, prefiriendo Opus en WebM/Ogg, luego MP4/AAC en Safari.

Cuando la grabación termina de transferirse, el componente dispara `file-uploaded` con el nuevo `trackId`. Eso significa que los bytes llegaron al almacenamiento — no que el procesamiento haya terminado. Consulta `GET /v1/track/:track_id` hasta que `track_status_id` sea `ready` (o escucha un webhook de pista) antes de iniciar la reproducción.

```
npm install @audiodn/components
```

```
import '@audiodn/components/recorder'
```

```
<audiodn-recorder
api-key="YOUR_API_KEY"
collection-id="COLLECTION_ID"
></audiodn-recorder>
```

¿Prefieres sin paso de compilación? Cárgalo directamente desde un CDN:

```
<script type="module" src="https://unpkg.com/@audiodn/components@latest/dist/recorder.js"></script>
```

### Atributos

| Atributo | Tipo | Predeterminado | Descripción |
| --- | --- | --- | --- |
| `api-key` | string | — | Clave API de subida del lado del cliente (segura para usar en código de front-end). Crea la sesión y la pista al enviar. Se requiere `api-key` o `upload-session-id`. |
| `upload-session-id` | string | — | ID de sesión de subida provisto por el servidor. Úsalo cuando tu servidor crea las sesiones en nombre del cliente. Se requiere `upload-session-id` o `api-key`. |
| `collection-id` | string | — | Colección de destino a la que subir la pista (se usa con `api-key`). Opcional cuando la clave API está limitada a una colección. |
| `accent-color` | string | `”#fe008a”` | Color de acento para el botón de grabación, la forma de onda y los controles. Se prefiere un hex de 6 dígitos (también se envía como `player_color` al subir mediante `api-key`). Si se omite, se usa el `player_color` de la colección/organización. |
| `theme` | string | `”auto”` | Tema de color: `“dark”` (texto blanco sobre fondo oscuro), `“light”` (texto oscuro sobre fondo gris claro suave), o `“auto”`. `“auto”` sigue la preferencia `prefers-color-scheme` del sistema operativo / navegador del visitante y cambia en vivo cuando esta cambia. Las propiedades CSS personalizadas individuales (ver Temas) siguen sobrescribiendo la paleta. |
| `locale` | string | `”en”` | Idioma de la interfaz. Valores: `en`, `fr`, `es`, `de`. |
| `countdown` | number | `3` | Duración de la cuenta atrás previa a la grabación (`3` → 3‑2‑1). Ponlo en `0` para omitir la cuenta atrás y empezar de inmediato. |
| `max-duration` | number | `0` | Duración máxima de grabación en segundos. `0` (u omitido) significa ilimitada; la grabación se detiene automáticamente al alcanzar el límite. |
| `auto-hide` | boolean | `false` | Tras una subida exitosa, aplica `display: none` al elemento anfitrión. Borra el estilo inline (o vuelve a montar el elemento) para mostrarlo de nuevo. |
| `disabled` | boolean | `false` | Deshabilita los controles de grabación cuando se establece. |

### Eventos

Todos los eventos se propagan y son compuestos (cruzan el shadow DOM). Escucha `file-uploaded` cuando la subida finaliza — esta es la señal de «subida completa» para los anfitriones y **no** significa que el procesamiento esté `ready`.

```
<audiodn-recorder
api-key="YOUR_API_KEY"
collection-id="COLLECTION_ID"
countdown="3"
auto-hide
></audiodn-recorder>

<script type="module">
const recorder = document.querySelector('audiodn-recorder')
recorder.addEventListener('file-uploaded', (e) => {
  const { trackId, fileName, blob } = e.detail
  console.log('uploaded', trackId, fileName, blob.size)
})
</script>
```

| Evento | `detail` | Se dispara cuando |
| --- | --- | --- |
| `recording-started` | — | La captura del micrófono comenzó realmente (después de la cuenta atrás, si la hay). |
| `recording-stopped` | `{ blob, duration }` | La grabación terminó; la vista previa está lista. |
| `recording-discarded` | — | El usuario descartó el clip (o canceló durante la grabación / la cuenta atrás). |
| `upload-progress` | `{ percent }` | Progreso de la subida (0–100). |
| `file-uploaded` | `{ trackId, fileName, blob }` | Los bytes terminaron de subirse al almacenamiento. **No** significa que la pista esté `ready`. |
| `session-error` | `{ error }` | No se pudo obtener una sesión de subida existente. |
| `adn-session-refreshed` | `{ uploadSessionId }` | Se creó una nueva sesión al enviar (la ruta `api-key`). |
| `adn-session-expired` | `{ uploadSessionId }` | Una sesión creada previamente expiró. |

## Predeterminado

Toca para grabar, previsualiza el clip y luego envíalo. Requiere una clave API y un ID de colección.

```
<audiodn-recorder
api-key="YOUR_API_KEY"
collection-id="COLLECTION_ID"
></audiodn-recorder>
```

## Cuenta atrás y duración máxima

Usa `countdown` para fijar el temporizador 3‑2‑1 previo a la grabación (o `0` para empezar de inmediato), y `max-duration` para detener automáticamente tras un número de segundos. Este ejemplo cuenta atrás desde 2 y limita las grabaciones a 30 segundos.

```
<audiodn-recorder
api-key="YOUR_API_KEY"
collection-id="COLLECTION_ID"
countdown="2"
max-duration="30"
></audiodn-recorder>
```

## Temas

La forma más rápida de alternar entre claro y oscuro es el atributo `theme` (`“auto”`, `“dark”` o `“light”`) documentado arriba — `“auto”` sigue la preferencia del sistema del visitante. Para un control más fino, aún puedes sobrescribir propiedades CSS personalizadas en el anfitrión para reestilizar la grabadora, con la misma API `—adn-*` que el reproductor.

### Claro / Oscuro (preferencia del sistema)

```
.theme-recorder-lightdark {
--adn-main-border: 1px solid light-dark(#ccc, #444);
--adn-bg: light-dark(#fff, #111);
--adn-bg-light: light-dark(#eee, #222);
--adn-color-font: light-dark(#222, #eee);
--adn-color-font-muted: light-dark(#666, #aaa);
--adn-color-accent: light-dark(#0066cc, #4da6ff);
--adn-color-accent-alt: light-dark(#fff, #111);
--adn-border-color: light-dark(#ccc, #444);
--adn-radius: 6px;
}
```

```
<audiodn-recorder
class="theme-recorder-lightdark"
api-key="YOUR_API_KEY"
collection-id="COLLECTION_ID"
></audiodn-recorder>
```

### Midnight

```
.theme-recorder-midnight {
--adn-bg: #1a1a2e;
--adn-bg-light: #2a2a4e;
--adn-color-font: #e0e0e0;
--adn-color-font-muted: #8888aa;
--adn-color-accent: #7c3aed;
--adn-color-accent-rgb: 124, 58, 237;
--adn-color-accent-alt: #fff;
--adn-border-color: #3a3a5e;
--adn-color-highlight: rgba(124, 58, 237, 0.12);
--adn-radius: 12px;
--adn-main-border: 1px solid #3a3a5e;
--adn-box-shadow: 0 4px 24px rgba(0, 0, 0, 0.4);
}
```

```
<audiodn-recorder
class="theme-recorder-midnight"
api-key="YOUR_API_KEY"
collection-id="COLLECTION_ID"
></audiodn-recorder>
```