SonicFrame v1.3.2

Parts and layouts

The look says how a player is put together: which parts sit on its line, where the wave goes, the sizes and the finish. Sizes are in rem, so a player grows with the page's text.

The line and the small line

line lists the parts of the main line, in order. meta adds a small line right under the wave, like a voice note's duration.

createPlayer({
    container,
    src,
    look: { line: ['play', 'wave'], meta: ['elapsed', 'spacer', 'speed'] },
});

Each time keeps the room of the longest time the sound can show (2:03 keeps the room of 0:00), so the parts beside it never move as it counts. timeAlign says where the text sits in that room. The shown text is .sonicframe-time-text, inside the .sonicframe-time part.

The wave on top

wavePlace: 'top' puts the wave on its own line, above the controls, which wrap on narrow screens.

look: { wavePlace: 'top', line: ['back', 'play', 'forward', 'spacer', 'time'] }

The voice note on phones

A player narrower than narrowWidth (22 rem) with the wave in its line turns into a voice note: the play button stays beside the wave, centered on it; the time goes under the wave on the left, and the other controls go on the right of the time, wrapping only the ones that do not fit. The pieces are moved, never built again, so nothing flickers. This player is 20 rem wide:

Option Default What it does
narrowWidth 22 The width, in rem, under which the player turns into a voice note. 0 keeps one line at any width.
narrowLine ['play', 'wave', 'slot'] The parts that stay on the line.
narrowStart the four time parts The parts that go under the wave on the left. Every other part goes on the right.
narrowGap 0.5 The space, in rem, between the parts under the wave.
waveMinWidth 8 On a wider line with zoom buttons, the wave keeps this width (rem) and the buttons wrap under it.

While it lasts, the player has a data-narrow attribute and the row under the wave is .sonicframe-under, for your own CSS.

A precise clock

timePrecision adds tenths, hundredths or milliseconds to the time, rounded to the nearest, or the frame of a timecode, at timeFps frames a second. The default, 'seconds', keeps the time as it always was.

look: { timePrecision: 'hundredths', underStart: 'line' }

A frame comes after the hours even under an hour, as a timecode writes it (timeHours: 'auto'; 'needed' waits for the hour, and 'always' shows them with any precision). timeDigits gives each field its least digits, here two for the hours, as video tools write them:

look: {
    timePrecision: 'frames',
    timeFps: 25,
    timeDigits: { hours: 2 },
    underStart: 'line',
}

While the sound plays, the time changes as often as its last digit does, and no more. Whole seconds follow the sound's own reports, as always; tenths change ten times a second, at the moment they turn; hundredths, milliseconds and frames are read once a frame of the screen, and written only when they change. Paused, nothing runs. Each time keeps the room of its longest text at the precision chosen, so nothing beside it moves.

The time played and the time left always add up to the length shown. Screen readers keep hearing the position in whole seconds (see Screen readers). To write a time the same way on your own page, use formatClock, from sonicframe.

A mask of your own

timeFormat writes the time with a mask: each letter is a field, repeated for its least digits (up to 4), and everything else is written as it is. Letters you want as text go inside brackets. The mask wins over timePrecision, timeHours, timeDigits and timeDecimal; timeFps still counts the frames.

Letter Writes
h the hours
H the hours from one hour on; below an hour, the text after them goes with them
m the minutes
s the seconds (every mask has them)
S the decimals: S tenths, SS hundredths, SSS milliseconds
f the frame, at timeFps, with room for its largest number
[text] the text inside, letters and all

The fields go in that order, the minutes under the hours, the decimals or the frame last. A mask with no hours lets the minutes hold them, and one with no minutes lets the seconds hold everything. A mask the clock cannot read is left out, and the options above write the time.

Mask 1 hour, 2 minutes, 5.25 seconds
'hh:mm:ss.SSS' 01:02:05.250
'H:mm:ss' 1:02:05, and 02:05 under an hour
'hh[h]mm[m]ss[s]' 01h02m05s
'hh[h] mm[m] ss[s]' 01h 02m 05s
'hh[ hours, ]mm[ minutes, ]ss[ seconds]' 01 hours, 02 minutes, 05 seconds
'mmmm:ss' 0062:05
'hh:mm:ss;ff', 25 frames a second 01:02:05;06
look: { timeFormat: 'hh[h]mm[m]ss[s]', underStart: 'line' }
Keep a mask short The time keeps the room of the widest text its mask can write, beside the wave or under it. A long mask (words, many digits) can leave the wave too little room, or overflow the player, on a phone or in a narrow column. Try your mask at phone width before you ship it.

Every look option

Option Default What it does
line ['play', 'wave', 'time'] The parts of the main line.
meta [] A small line under the wave.
metaWrap false Short of room, the small line keeps one line and a chapter's name gives up its room. true breaks it in two instead, the parts after a spacer going together to the far side of the second.
nameOverflow 'ellipsis' How a chapter's name too long for its room ends: an ellipsis, 'fade' (it fades out, saying there is more) or 'clip' (cut where the room ends).
nameFade 1.5 How wide that fade is (rem, 0.25 to 6).
nameFadeStart true With the fade, a walking name fades at its start too while it is off its start; at rest the start stays sharp. false keeps a sharp cut there.
nameTooltip false A long name shows in full in a tooltip while the mouse is on it.
titleFromFile true The title part of a player without a name shows its file's name: little-elf.mp3 as "Little elf". false leaves it empty.
nameMaxWidth 12 The widest the title and artist parts grow (rem, 2 to 40). Each takes its text's width up to this and gives up its room before the wave; one without text leaves the line.
marquee false A long name walks across its room, as marqueeType says. Never when the system asks for less motion.
marqueeType 'loop' How the name goes round: an endless strip, its copy following it and coming to rest where it started; 'restart', back to its start once its end shows; or 'bounce', walking back.
marqueeGap 2.5 In a loop, the space between the name and its copy (rem, 0.5 to 10).
marqueePauseOnHover true The name stops walking while the mouse is on it and goes on when it leaves.
marqueeSpeed 2 How fast it walks (rem a second, 0.25 to 20).
marqueePauseSeconds 1.5 How long it rests before it walks; in 'restart' and 'bounce', at its end too (seconds, 0 to 10).
wavePlace 'inline' 'inline' or 'top'.
time 'both' 'elapsed', 'remaining', 'duration' or 'both'.
timeAlign 'auto' Where a time's text sits in the room it keeps: 'start', 'center' or 'end'. 'auto' keeps to the end after the wave or a spacer, and on the right under a voice note's wave; to the start everywhere else.
timePrecision 'seconds' What the time shows after the seconds: nothing, 'tenths', 'hundredths', 'milliseconds' or 'frames' (see A precise clock).
timeFps 30 With 'frames', the frames in a second (1 to 120); 29.97 counts 30 frames in each second.
timeHours 'auto' The hours: from one hour on, but always with a frame, as a timecode writes them; 'always' (0:01:05); or 'needed', from one hour on with a frame too.
timeDecimal '.' The mark before tenths, hundredths and milliseconds: '.', ',' or 'auto', the one of the player's language.
timeDigits { hours: 1, minutes: 1, seconds: 2, frames: 2 } The least digits of each field: hours and minutes 1 to 4, seconds and the frame 2 to 4. Give only the ones to change; minutes under hours keep two.
timeFormat null A mask that writes the time its own way, over the four options above (see A mask of your own).
underStart 'wave' Where the rows under a wave in the line start (the small line, a voice note's time, the chapters list): at the wave's left edge, or 'line', under the play button, so the button and the wave read as one block.
button { shape: 'circle', fill: 'solid', size: 36 } The play button. A number size is in CSS pixels (16 to 96). Written in rem ('2.5rem', 1 to 6), the button grows with the page's text.
waveHeight 2.5 Height of the wave (rem).
minimapHeight, minimapGap 1.5, 0.375 The minimap strip and its space from the wave (rem).
corner, padding, gap 0.75, 0.5, 0.625 Corner radius, inner space and space between parts (rem).
border 1 Border width in CSS pixels; 0 draws none.
shadow 'none' 'none', 'soft', 'hard' or 'glow'.
surface 'solid' 'solid', 'glass' or 'none'.
background, backgroundAnimation null A background of its own (a color, a gradient or an image, with effects) in the surface's place, and how it moves; see Backgrounds.
font, fontSize, fontWeight, uppercase 'system', 0.8125, 500, false The text; fontWeight from 100 to 900.
skip 10 Seconds moved by back and forward.
speeds [1, 1.5, 2] The speeds the speed button steps through.
volumeSlider 'hover' 'always' or 'hover': when the volume bar shows.

Unknown names fall back to the default and numbers are kept in range, so a look can come from anywhere (an attribute, a stored setting) without surprises.