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' }
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.