Recording
Record from the microphone with a live wave, hear the recording on a player, then send it to your app. The microphone is asked for only when someone presses record.
Try it
Press record and allow the microphone. Send keeps everything on this page and only says what it would hand over.
Adding it
import { createRecorder } from 'sonicframe/record';
createRecorder({
container: document.querySelector('#recorder'),
async onSend(recording) {
const body = new FormData();
body.append('audio', recording.blob);
body.append('peaks', JSON.stringify(recording.peaks));
const response = await fetch('/notes', { method: 'POST', body });
if (!response.ok) {
throw new Error('The note was not saved');
}
},
});
While onSend runs, the screen says it is
sending. A rejection keeps the recording and says it
could not be sent, so it can be sent again.
What the recording holds
| Field | What it is |
|---|---|
blob |
The sound. |
mimeType |
Its audio type: Opus in WebM in Chrome, Edge and Firefox, MP4 in Safari. |
duration |
Seconds recorded, pauses left out. A recorder's file often gives no length of its own, so keep this one. |
peaks |
Peaks from 0 to 1 (1000 unless
decode.peakCount says
otherwise), decoded from the sound,
ready for a player.
|
size |
In bytes. |
The stages and their parts
| Stage | Parts by default |
|---|---|
idle |
['record'] |
recording |
['discard', 'time', 'wave',
'pause', 'stop']
|
review |
['discard', 'player', 'send']
|
parts sets any stage's list, from
record, stop,
pause, discard,
send, time, wave,
player, rec and
spacer, and the names of your own
actions. What went wrong, or what is under
way, shows on a line under the parts.
The screen tells each move with the
statechange event, giving its state: one of
RECORDER_SCREEN_STATES (idle,
asking, recording,
paused, review,
sending, denied,
error), typed
RecorderScreenState.
createRecorder({
container,
theme: 'bubble',
live: 'fit',
parts: {
recording: ['wave', 'time', 'stop'],
review: ['player', 'spacer', 'discard', 'send'],
},
onSend,
});
When a recording stops
afterStop |
What comes next |
|---|---|
'review' (default) |
A player of the recording, to hear it, then delete or send it. |
'send' |
It is sent right away, as a chat app does when the button is let go. If the send fails, it waits in review. |
'none' |
No player and nothing sent: your app gets the recording and the screen starts over. |
Every recording that stops reaches
onRecorded and the
recorded event, whatever comes next. With
only a stop button while recording, the screen is a
single record button:
createRecorder({
container,
parts: { recording: ['stop'] },
afterStop: 'none',
// No box of its own: only the button.
look: { padding: 0, border: 0, surface: 'none', shadow: 'none' },
onRecorded(recording) {
attach(recording.blob);
},
});
Your own buttons
actions adds your buttons, by name; each
shows where its name is listed in parts.
Its press gets the recording in review (null before one)
and the screen. One marked main is filled
like the record button and takes the focus when it leads
the stage. Names are lowercase letters, digits and
dashes, and none of the screen's own parts or icons:
resume and cancel are refused.
createRecorder({
container,
parts: { review: ['discard', 'player', 'save'] },
actions: {
save: {
label: 'Save the recording',
icon: 'M5 3h11l3 3v15H5zM8 5v4h7V5zM8 13v6h8v-6z',
main: true,
press(recording, screen) {
keep(recording);
},
},
},
});
Sending to your server
Give upload your address and Send posts the
recording there, telling how far it got; nothing else is
needed. A status outside 200–299 keeps the recording to
send again, and the server's answer comes in the
uploaded event.
createRecorder({
container,
upload: {
url: '/notes',
field: 'audio',
fields: { chat: chatId },
headers: { Authorization: `Bearer ${token}` },
},
cancelSend: true,
});
upload |
Default | What it is |
|---|---|---|
url |
Your address: a web or relative one; any other sends nothing. | |
method |
'POST' |
Or 'PUT'. |
bodyType |
'form' |
A form, or the file alone with its type
('raw').
|
field |
'file' |
The form field of the file. |
filename |
recording.webm |
The file's name; the extension follows the audio type. |
fields |
More form fields, up to 50. | |
headers |
Request headers, up to 50, each on one line. | |
withCredentials |
false |
Send cookies to another host too. |
With your own onSend, its second argument
holds a signal that aborts when the send is
canceled or the screen is removed, and
progress(fraction), which shows "Sending,
40%".
uploadRecording(recording, upload, control)
does the upload above from there. With
cancelSend, the send button turns into
Cancel sending while sending; try it here:
createRecorder({
container,
cancelSend: true,
async onSend(recording, { signal, progress }) {
await uploadRecording(recording, { url: '/notes' }, { signal, progress });
await notify(chatId);
},
});
The record button
recordStyle draws it as a red button
('red', the default, as in the demos
above), the dot in the player's button colors
('dot'), a microphone ('mic')
or a retro REC mark ('rec'): a red border,
a red dot and red letters on a dark ground of its own,
so the red reads on any page.
recordColor sets the red, and your own
icons.record is drawn in any style. Screen
readers hear "Record" in every one.
The microphone is drawn as its outline on the red
button; with micStyle: 'filled', its body
is filled, and micColor: 'theme' puts it in
the player's colors, as in the second one:
recPlace |
Where REC shows while recording |
|---|---|
'badge' (default) |
A badge before the time, the third demo above. It is only seen: the live region already says "Recording". |
'stop' |
The stop button itself, as on a camera: press REC again to stop. |
'time' |
A badge holding the time, as in a viewfinder; the time is still heard. |
createRecorder({
container,
recordStyle: 'rec',
recPlace: 'time',
recBlink: true,
onSend,
});
recBlink blinks the REC dot once a second
while recording. It is off by default, never runs with
reduced motion, and holds still, lit, while paused,
while the pointer is over the screen or while the focus
is in it. The rec part goes in any stage's
list, in any style. When the live wave would be narrower
than 3 rem, as on a small phone, the REC letters give it
their room and only the red dot stays.
Drawing it your way
-
iconsdraws any button with your own SVG path on a 24 × 24 grid:record,stop,pause,resume,discard,sendandcancel. Path data with anything but path commands and numbers keeps the default. -
alignlines the buttons beside the player of the recording up on its bars ('bars', the default), or on its box's middle, top or bottom ('center','start','end'). -
reviewLookis the look of that player alone. Here the time keeps to the wave's left edge, and the buttons center on the whole player:
createRecorder({
container,
align: 'center',
reviewLook: { underStart: 'wave' },
icons: { send: 'M2 21 23 12 2 3v7l15 2-15 2z' },
onSend,
});
For screen readers
-
Every button has a name, yours too, and the focus
moves to the main button of each stage: stop, then
send, or your button marked
main. - While sending, the line under the parts shows how far it got; a canceled send says "Sending canceled", and the focus stays on the send button.
- The live region says "Recording", "Recording paused", "Recording stopped, 0:42", "Time limit reached" and why the microphone cannot be used.
- The live wave is hidden from screen readers; the time is text.
-
a11y.announceEvery: 30also says the time every 30 seconds while recording. Off by default. -
a11y.langanda11y.wordspick the language and your own words, as for the player.
Driving the screen from your code
createRecorder gives the screen, which a
page can drive and read as a person would use it:
| Member | What it does |
|---|---|
start() |
Asks for the microphone and records; a refusal is shown and said. Call it from a person's press. |
pause(),
resume()
|
Pauses and goes on recording. |
stop() |
Stops recording; what follows is
afterStop's.
|
discard() |
Drops the recording under way or in review. |
send() |
Sends the recording in review. |
cancelSend() |
Stops the send under way (its signal aborts); the recording stays in review, to send again. |
destroy() |
Takes the screen off the page, letting the microphone and the recording go. |
on(event, listener) |
Listens to statechange,
recorded,
send,
progress,
uploaded,
sent and
error; gives back a
function that stops listening.
|
state,
recording,
player,
recorder
|
Where the screen is, the recording in
review and its player (or
null), and the
Recorder under it.
|
A send through upload or
uploadRecording that fails rejects with an
UploadError: its status is the
server's (0 when it was never reached, or the address
was refused) and its body the start of the
server's answer. The uploaded event gives
the answer of a send that worked, as
{ status, body }.
Without a screen
import { Recorder, RecordError } from 'sonicframe/record';
const recorder = new Recorder({ maxSeconds: 60 });
recorder.on('level', (level, seconds) => meter.update(level));
try {
await recorder.start(); // from a press
} catch (error) {
if (error instanceof RecordError) {
show(error.reason); // 'denied', 'missing', 'insecure', 'unsupported' or 'failed'
}
}
const recording = await recorder.stop();
pause(), resume() and
cancel() do what they say;
levels holds the live levels, 20 a second
unless levelsPerSecond says otherwise, and
state says where it is, its
RecorderPhase: idle,
asking, recording or
paused. The recording stops on its own at
its limit (a limit event, then
stop). Midway, an error event
gives a RecordError whose reason is
'too-large' (past maxBytes) or
'failed' (the browser's recorder broke);
the microphone is let go.
On the tag
<sonic-recorder max-seconds="120" theme="bubble"></sonic-recorder>
<script type="module">
import { defineSonicRecorder } from 'sonicframe/record';
defineSonicRecorder();
document.querySelector('sonic-recorder').addEventListener('sonicframe:send', (event) => {
const [recording] = event.detail;
upload(recording);
});
</script>
| Attribute | Takes |
|---|---|
max-seconds |
Seconds before it stops on its own, from
1 to 3600 (300 by default). Longer, up
to 6 hours, is for your code
(maxSeconds).
|
live |
fit, or it scrolls. |
live-seconds |
Seconds the scrolling wave shows, from 2 to 60 (10 by default). |
theme,
palette,
wave
|
As on the player. |
font,
font-src,
font-stylesheet
|
A font family, with the address of its file or of its stylesheet, as on the player. |
hold |
Present: record while held. |
after-send |
reset (the default) or
keep: keep the recording
after Send.
|
idle-parts,
recording-parts,
review-parts
|
Part names, separated by spaces. |
actions |
Your buttons as
name:label, name:label; a
press dispatches
sonicframe:action with the
name and the recording.
|
after-stop |
review,
send or none.
|
align |
bars, center,
start or end.
|
icon-name
|
An SVG path for a button, yours too
(icon-record,
icon-save…).
|
upload-url,
upload-method,
upload-field
|
Send to your address. |
cancel-send |
Present: a send can be canceled. |
record-style,
record-color,
mic-style,
mic-color,
rec-place
|
The record button and its REC mark. |
rec-blink |
Present: the REC dot blinks. |
a11y-lang,
a11y-announce-every
|
The language, and the seconds between two times said. |
The events reach the element as
sonicframe:statechange,
sonicframe:recorded,
sonicframe:send,
sonicframe:progress,
sonicframe:uploaded,
sonicframe:sent,
sonicframe:action and
sonicframe:error. On the tag, Send counts
as sent, unless upload-url sends it first.
Changing an attribute, or the
icon-name of one of your buttons,
starts over.
Options
| Option | Default | What it does |
|---|---|---|
maxSeconds |
300 |
Seconds before it stops on its own, from 1 to 21,600 (6 hours). |
constraints |
echo, noise and gain control on | The microphone's settings. |
mimeTypes |
WebM Opus, MP4, Ogg Opus | The audio types to try, in order; the first the browser can record wins. |
audioBitsPerSecond |
the browser's | The bitrate. |
decode |
true |
Decode the sound for its peaks, with its
options (RecorderDecode);
off, or when decoding fails, the live
levels.
|
decode.peakCount |
1000 |
How many decoded peaks, from 1 to 100 000. |
levelsPerSecond |
20 |
Live levels a second, from 1 to 100. |
maxBytes |
100 MiB | The largest recording, up to 1 GiB. The browser keeps it in memory until it stops, and a phone has far less room than a desktop: keep long recordings for desktops, or send them in parts. |
parts |
see above | The parts of each stage. |
live |
'scroll' |
The live wave scrolls, or fits the whole
recording ('fit').
|
liveSeconds |
10 |
Seconds the scrolling wave shows, from 2 to 60. |
theme, look,
palette, wave,
bar,
font
|
the player's |
Dress the screen and the player of the
recording. The player's rows under the
wave start under its play button (underStart: 'line') unless the look says otherwise, and
the buttons beside it line up with its
bars unless align says
otherwise.
|
reviewLook |
The look of the player of the recording
alone, over look.
|
|
align |
'bars' |
How the buttons beside that player line
up: on its bars, or its box's
'center',
'start' or
'end'.
|
icons |
the screen's | Your own SVG path for each button. |
recordStyle |
'red' |
The record button: 'dot',
'mic' or
'rec'.
|
micStyle |
'outline' |
The microphone's body, or
'filled'.
|
micColor |
'red' |
The microphone's button, or the player's
colors ('theme').
|
recordColor |
'#f44336' |
The red of the red and REC styles. |
recPlace |
'badge' |
Where REC shows while recording:
'stop' or
'time'.
|
recBlink |
false |
The REC dot blinks while recording. |
actions |
Your own buttons, by name. | |
afterStop |
'review' |
What follows a stop:
'send' right away, or
'none'.
|
onRecorded |
Gets every recording that stops. | |
onSend |
Gets the recording when Send is pressed,
with a signal and
progress.
|
|
upload |
Your address, used when there is no
onSend.
|
|
cancelSend |
false |
The send button cancels the send under way. |
afterSend |
'reset' |
Start over, or keep the recording
('keep').
|
hold |
false |
Record while the button is held; a click still records. |
a11y |
lang,
words and
announceEvery.
|
Where it can record
-
Only on HTTPS pages (and
localhost); elsewhere the screen says so. -
In an iframe, only with
allow="microphone". -
The player of the recording plays a
blob:address: a strict Content-Security-Policy needsmedia-src blob:. -
Nothing leaves the page unless your
onSendoruploadsends it; a strict Content-Security-Policy lists your upload address inconnect-src.