SonicFrame v1.3.2

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

  • icons draws any button with your own SVG path on a 24 × 24 grid: record, stop, pause, resume, discard, send and cancel. Path data with anything but path commands and numbers keeps the default.
  • align lines 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').
  • reviewLook is 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: 30 also says the time every 30 seconds while recording. Off by default.
  • a11y.lang and a11y.words pick 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 needs media-src blob:.
  • Nothing leaves the page unless your onSend or upload sends it; a strict Content-Security-Policy lists your upload address in connect-src.