# Recorder Component | AudioDN Docs

> In-browser voice recorder with live waveform, preview player, and direct upload to AudioDN.

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

---

# Recorder

Capture microphone audio in the browser, preview it with a mini player and waveform, then upload a single track to AudioDN.

## Usage

Install from npm and import the component, then drop the element into your page. Provide a Client-Side upload API key and, optionally, a collection ID to upload into. With an `api-key`, the recorder creates the upload session **and** the track in one request, then PUTs the recording. If the API key is scoped to a collection, the collection ID is resolved automatically.

Recording starts after a short 3‑2‑1 countdown, and filenames are generated automatically from the UTC timestamp. The browser picks a supported mime type, preferring Opus in WebM/Ogg, then MP4/AAC on Safari.

When the recording finishes transferring, the component fires `file-uploaded` with the new `trackId`. That means the bytes reached storage — not that processing is done. Poll `GET /v1/track/:track_id` until `track_status_id` is `ready` (or listen for a track webhook) before starting playback.

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

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

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

Prefer no build step? Load it straight from a CDN instead:

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

### Attributes

| Attribute | Type | Default | Description |
| --- | --- | --- | --- |
| `api-key` | string | — | Client-Side upload API key (safe to use in front-end code). Creates the session and track on send. Either `api-key` or `upload-session-id` is required. |
| `upload-session-id` | string | — | Server-provisioned upload session ID. Use this when your server creates sessions on behalf of the client. Either `upload-session-id` or `api-key` is required. |
| `collection-id` | string | — | Target collection to upload the track into (used with `api-key`). Optional when the API key is scoped to a collection. |
| `accent-color` | string | `”#fe008a”` | Accent color for the record button, waveform, and controls. A 6-digit hex is preferred (also sent as `player_color` when uploading via `api-key`). When omitted, the collection/organization `player_color` is used. |
| `theme` | string | `”auto”` | Color theme: `“dark”` (white text on a dark background), `“light”` (dark text on a soft light-gray background), or `“auto”`. `“auto”` follows the visitor’s operating system / browser `prefers-color-scheme` setting and switches live when it changes. Individual CSS custom properties (see Themes) still override the palette. |
| `locale` | string | `”en”` | UI language. Values: `en`, `fr`, `es`, `de`. |
| `countdown` | number | `3` | Pre-record countdown length (`3` → 3‑2‑1). Set to `0` to skip the countdown and start recording immediately. |
| `max-duration` | number | `0` | Maximum recording length in seconds. `0` (or omit) means unlimited; recording stops automatically when the limit is reached. |
| `auto-hide` | boolean | `false` | After a successful upload, sets the host element to `display: none`. Clear the inline style (or remount the element) to show it again. |
| `disabled` | boolean | `false` | Disables the recording controls when set. |

### Events

All events bubble and are composed (cross shadow DOM). Listen for `file-uploaded` when the upload finishes — this is the “upload complete” signal for hosts and does **not** mean processing is `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>
```

| Event | `detail` | Fired when |
| --- | --- | --- |
| `recording-started` | — | Microphone capture actually began (after the countdown, if any). |
| `recording-stopped` | `{ blob, duration }` | Recording finished; the preview is ready. |
| `recording-discarded` | — | The user discarded the clip (or cancelled mid-record / mid-countdown). |
| `upload-progress` | `{ percent }` | Upload progress (0–100). |
| `file-uploaded` | `{ trackId, fileName, blob }` | Bytes finished uploading to storage. Does **not** mean the track is `ready`. |
| `session-error` | `{ error }` | An existing upload session could not be fetched. |
| `adn-session-refreshed` | `{ uploadSessionId }` | A new session was created on send (the `api-key` path). |
| `adn-session-expired` | `{ uploadSessionId }` | A pre-created session expired. |

## Default

Tap to record, preview the clip, then send it. Requires an API key and collection ID.

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

## Countdown & max duration

Use `countdown` to set the pre-record 3‑2‑1 timer (or `0` to start immediately), and `max-duration` to automatically stop after a number of seconds. This example counts down from 2 and caps recordings at 30 seconds.

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

## Themes

The quickest way to switch light and dark is the `theme` attribute (`“auto”`, `“dark”`, or `“light”`) documented above — `“auto”` follows the visitor’s system preference. For finer control you can still override CSS custom properties on the host to restyle the recorder, using the same `—adn-*` API as the player.

### Light / Dark (system preference)

```
.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>
```