MediaRecorderController
Records the microphone or camera as a state machine with pause, a time limit, a result URL it cleans up and a stream other controllers can read.
Reach for it for voice notes, a camera capture or any recording that needs permission handling and a recording indicator that goes off when it should.
Import
import { MediaRecorderController, createMediaRecorderController } from '@ecopages/radiant-ui/controllers';Try it
Press Record and allow the microphone. The recording stops by itself after 30 seconds. After Stop the result plays back below. Nothing leaves the page.
Ready 0.0 s
<div data-example="media-recorder">
<button type="button" data-record>Record</button>
<button type="button" data-pause disabled>Pause</button>
<button type="button" data-stop disabled>Stop</button>
<p data-status>Ready 0.0 s</p>
<audio controls hidden></audio>
</div>import { MediaRecorderController, type MediaRecorderSnapshot } from '@ecopages/radiant-ui/controllers';
export function mount(root: HTMLElement): () => void {
const record = root.querySelector<HTMLButtonElement>('[data-record]')!;
const pause = root.querySelector<HTMLButtonElement>('[data-pause]')!;
const stop = root.querySelector<HTMLButtonElement>('[data-stop]')!;
const status = root.querySelector('[data-status]')!;
const player = root.querySelector('audio')!;
const labels: Record<MediaRecorderSnapshot['status'], string> = {
idle: 'Ready',
requesting: 'Waiting for the microphone',
recording: 'Recording',
paused: 'Paused',
stopped: 'Recorded',
denied: 'Microphone access was denied',
unsupported: 'This browser cannot record',
error: 'Recording failed',
};
const recorder = new MediaRecorderController({
mimeTypes: ['audio/webm;codecs=opus', 'audio/mp4'],
maxDuration: 30,
onState: ({ status: next, duration }) => {
status.textContent = `${labels[next]} ${duration.toFixed(1)} s`;
record.disabled = next === 'requesting' || next === 'recording' || next === 'paused';
pause.disabled = next !== 'recording' && next !== 'paused';
pause.textContent = next === 'paused' ? 'Resume' : 'Pause';
stop.disabled = pause.disabled;
},
onStop: ({ url }) => {
player.src = url;
player.hidden = false;
},
});
recorder.attach();
record.addEventListener('click', () => {
player.hidden = true;
player.removeAttribute('src');
player.load();
void recorder.start();
});
pause.addEventListener('click', () => {
if (recorder.getState().status === 'paused') {
recorder.resume();
} else {
recorder.pause();
}
});
stop.addEventListener('click', () => void recorder.stop());
return () => recorder.destroy();
}mount runs once for each example element on the page, and the function it returns undoes it; see how the examples run.
The status line is not a live region, because onState writes it about ten times a second while recording. Announce status changes separately; see Accessibility.
Recipe: a voice note with a download
The controller revokes the result URL on discard(), on the next start() and on destroy(). A download link therefore points at a URL that is valid only until then, and a note that is kept has to be copied from the blob.
import { MediaRecorderController } from '@ecopages/radiant-ui/controllers';
const extensions: Record<string, string> = { 'audio/webm': 'webm', 'audio/mp4': 'm4a', 'audio/ogg': 'ogg' };
const recorder = new MediaRecorderController({
mimeTypes: ['audio/webm;codecs=opus', 'audio/mp4', 'audio/ogg;codecs=opus'],
maxDuration: 120,
onStop: ({ blob, url, mimeType }) => {
link.href = url;
link.download = `voice-note.${extensions[mimeType.split(';')[0]] ?? 'bin'}`;
link.hidden = false;
upload.onclick = () => void fetch('/notes', { method: 'POST', body: blob });
},
});
recorder.attach();
record.onclick = () => void recorder.start();
stop.onclick = () => void recorder.stop();
discard.onclick = () => {
recorder.discard();
link.hidden = true;
};Config
| Option | Meaning |
|---|---|
constraints | MediaStreamConstraints, or a getter read on each start(). Default { audio: true }. Use { video: true } or both for the camera. |
mimeTypes | MIME types in order of preference. The first one MediaRecorder.isTypeSupported accepts is used, else the browser default. |
timeslice | Milliseconds between onData chunks. Without it the data arrives once, on stop. |
maxDuration | Seconds after which the recording stops by itself. Paused time does not count. |
getAudioContext | An AudioContext you own. Only when given, the stream also feeds an AnalyserNode, so getAnalyser() and level work. The controller never creates or closes a context and never connects the analyser to the speakers. |
getUserMedia | Replaces navigator.mediaDevices.getUserMedia: a test double, or a stream the page already holds. |
onState | Called with a snapshot on every status change and about every 100 ms while recording. |
onData | Called with each non-empty chunk. |
onStop | Called with { blob, url, mimeType, duration } when a recording ends through stop() or maxDuration. |
onError | Called with the error for every failure other than a refused permission. A refusal is denied, reported through onState and getState() only. |
Methods
| Method | What it does |
|---|---|
start() | Asks for the device and records. Does nothing while requesting, recording or paused. Resolves when recording began or failed; never rejects. |
pause() | Pauses a recording. resume() continues it. |
stop() | Ends the recording and resolves with the result, or null when nothing was recording. Stopping while requesting cancels the request. |
discard() | Drops the recording and the last result, stops the device and returns to idle. onStop does not run. |
getState() | { status, duration, level, mimeType, error }. duration is seconds, advancing while recording and frozen while paused. level is a smoothed loudness from 0 to 1, always 0 without getAudioContext, while paused, and while the context you pass is suspended. |
getAnalyser() | The AnalyserNode while recording or paused when getAudioContext is set, otherwise null. |
getStream() | The live MediaStream while recording or paused, otherwise null, for another controller to analyse. Do not connect it to the speakers. |
Statuses: idle, requesting, recording, paused, stopped, denied (permission refused), unsupported (no MediaRecorder or getUserMedia) and error.
Recipe: a level meter
Pass a context you created from a user gesture; a suspended one reads silence. The same analyser can feed a visualizer.
const context = new AudioContext();
const recorder = new MediaRecorderController({
getAudioContext: () => context,
onState: ({ level }) => meter.style.setProperty('--level', String(level)),
});
record.onclick = async () => {
await context.resume();
await recorder.start();
};Lifecycle
start() does nothing before attach(). Every track is stopped when the recording ends, on discard() and on destroy(), so the browser's recording indicator goes off. A stream that arrives after stop(), discard() or destroy() while requesting is stopped on arrival. The result URL is an object URL the controller owns: it is revoked on discard(), on the next start() and on destroy(), so clear any audio element that plays it before recording again (the example removes its src) and keep the blob if the recording must outlive it. A recording also finishes by itself, with a result and onStop, when every track ends (a device unplugged or a permission revoked) or the browser stops the recorder. With getAudioContext, the source and analyser are disconnected at the same points and the context stays open. destroy() returns the state to idle without calling onState.
With a host, createMediaRecorderController(host, config) does the same on connect and disconnect; see bindController.
Accessibility
Give each button a visible text name that matches its action, and keep Pause and Resume one button whose label changes. Announce status changes through a polite live region, not the running timer. Tell people why the microphone is needed before start(), and give denied its own message with the way back (the browser's site settings), because the page cannot ask again. Offer the recording as an audio element with controls so it is playable by keyboard. Recording needs a visible, discoverable stop; do not hide it after start().
Caveats
- The page must be in a secure context (HTTPS or localhost) for
getUserMedia. Without it the controller reportsunsupported. - Supported formats differ: Chromium and Firefox record
audio/webmoraudio/ogg, Safari recordsaudio/mp4. List several inmimeTypesand readmimeTypefrom the result instead of assuming one. mimeTypein the snapshot may benulluntil the first chunk arrives when no listed type is supported.- Without
timeslicethe whole recording is kept in memory until stop. UsetimesliceandonDatato stream long recordings out. - The controller does not watch for a device that is unplugged or taken by another tab. Listen for
endedon the tracks ofgetStream()if that matters. - A recording is lost if the page is closed before
stop(); the controller does not persist anything.
Protected hooks
None. It decides nothing an owner would change.