Recorder
A drop-in web component for capturing high-quality audio recordings in any web application.
Installation
Include the recorder script in your page:
HTML
<script type="module" src="https://cdn.jsdelivr.net/npm/@44-audio/[email protected]/dist/recorder.es.js"></script>
Or install via npm:
Bash
npm install @44-audio/components
JavaScript
import "@44-audio/components/recorder";
Usage
Add the recorder component to your page with a valid session ID. Sessions are created server-side using your API key and expire after 1 hour.
HTML
<fortyfour-recorder session-id="YOUR_SESSION_ID"></fortyfour-recorder>
Configuration Options
The recorder supports the following attributes:
| Attribute | Type | Default | Description |
|---|---|---|---|
session-id |
string | — | A valid session ID from your server |
labels |
string | "" |
Comma-separated labels for organizing recordings |
countdown-ms |
number | 3000 |
Countdown duration in ms before recording starts |
max-duration-ms |
number | — | Maximum recording length in ms |
shape |
string | "pill" |
Container shape: "rounded", "pill", "square" |
button-label |
string | "icon" |
Button style: "icon" or "label" (icon + text) |
spacing |
string | "default" |
Padding/gaps: "compact", "default", "comfortable" |
CSS Variables
Customize the recorder appearance with CSS custom properties:
| Variable | Default | Description |
|---|---|---|
--fortyfour-recorder-font-family |
system-ui, sans-serif |
Font family |
--fortyfour-recorder-font-size |
14px |
Base font size |
--fortyfour-recorder-accent |
#c4956a |
Accent color (record button, active states) |
--fortyfour-recorder-background |
#faf8f5 |
Container background color |
--fortyfour-recorder-text |
#2c2620 |
Primary text color |
--fortyfour-recorder-muted |
#8c8279 |
Secondary/muted text color |
--fortyfour-recorder-border |
#d9d4cc |
Border color |
--fortyfour-recorder-waveform-progress |
(uses accent) | Waveform progress color |
CSS Parts
Style internal elements from outside the shadow DOM using ::part():
CSS
/* Style all buttons (record, stop, save, discard, etc.) */
fortyfour-recorder::part(button) {
border-radius: 4px;
}
/* Style the microphone selector dropdown */
fortyfour-recorder::part(select) {
font-size: 12px;
}
| Part | Description |
|---|---|
button |
All buttons (record, stop, play, save, discard, retry) |
select |
The microphone selector dropdown |
State Attribute
The recorder element has a data-state attribute that reflects the current state, useful for
CSS styling:
CSS
/* Style based on recorder state */
fortyfour-recorder[data-state="recording"] {
/* Recorder is actively recording */
}
fortyfour-recorder[data-state="error"] {
/* Recorder encountered an error */
}
| State | Description |
|---|---|
initializing |
Component is loading |
needs-permission |
Waiting for user to grant microphone access |
permission-denied |
Microphone access was denied |
no-microphone |
No microphone detected |
idle |
Ready to record |
counting-down |
Countdown before recording starts |
recording |
Actively recording audio |
preview |
Recording complete, previewing before save |
uploading |
Uploading the recording |
processing |
Server is processing the recording |
done |
Recording saved successfully |
error |
An error occurred during upload or processing |
interrupted |
Recording was interrupted (e.g. tab hidden) |
Dark Theme Example
HTML
<fortyfour-recorder
session-id="YOUR_SESSION_ID"
style="
--fortyfour-recorder-accent: #60a5fa;
--fortyfour-recorder-background: #1f2937;
--fortyfour-recorder-text: #f9fafb;
--fortyfour-recorder-muted: #9ca3af;
--fortyfour-recorder-border: #4b5563;
"
></fortyfour-recorder>
Events
The recorder emits events you can listen to:
JavaScript
const recorder = document.querySelector("fortyfour-recorder");
recorder.addEventListener("recording-complete", (event) => {
console.log("Recording ID:", event.detail.recordingId);
// The recording object contains the full recording data
const recording = event.detail.recording;
console.log("Transcription:", recording.transcription);
console.log("Duration (ms):", recording.duration);
});
The recording-complete event detail includes:
| Field | Type | Description |
|---|---|---|
recordingId |
string | The recording ID |
recording |
object | The full recording data (see below) |
The recording object contains:
| Field | Type | Description |
|---|---|---|
status |
string | Recording status (e.g. "ready") |
duration |
number | Duration in milliseconds |
size |
number | File size in bytes |
waveform |
number[] | Waveform amplitude samples |
lang |
string | Detected language code |
transcription |
string | Transcribed text |
translation |
string | Translated text (if available) |
words |
object[] | Word-level timing: { text, type, start, end } |
audioUrl |
string | URL to the audio file |
createdAt |
string | ISO 8601 timestamp |