Backgrounds
A player can wear its own background: a color, a gradient or an image, with filters, ready-made effects, transparency and an animation. All of it is off until the look asks for it.
A color or a gradient
look.background takes the place of the
player's surface. A gradient has two to five colors, an
angle in degrees and a kind:
'linear', 'radial' or
'conic'. Pick a palette whose bars and text
read on the background, as this one does, or lay
'dim' over it.
createPlayer({
container,
src,
palette: {
...PALETTES.dark,
text: '#ffffff',
wave: '#ffffff66',
progress: '#ffd27a',
accent: '#ffd27a',
onAccent: '#1b1f5e',
},
look: {
background: {
gradient: { colors: ['#1b1f5e', '#5b2f8a', '#a8406f'], angle: 120 },
},
},
});
An image
An image comes from a web, relative or
blob: address; any other address is left
out. It covers the player by default, centered.
look: {
background: {
image: { src: '/covers/dusk.jpg' },
effects: [{ type: 'dim', amount: 0.3 }, 'vignette'],
},
},
| Option | Default | What it does |
|---|---|---|
image.src |
A web, relative or blob:
address, without quotes or parentheses.
|
|
image.size |
'cover' |
'cover',
'contain',
'auto', or a width in rem
(0.5 to 50).
|
image.position |
centered |
Keywords ('top',
'bottom right'…) or
{ x, y } in percent from
the top left.
|
image.repeat |
false |
Tiles the image. |
color |
A color background, or the color behind an image or a gradient. |
Effects
Ready-made effects go in effects, by name
or with their own amount (0 to 1) and
colors. Each one is drawn by SonicFrame, with no image
file.
effects: ['duotone', { type: 'grain', amount: 0.15 }],
| Effect | Amount | What it does |
|---|---|---|
'dim' |
0.5 |
Lays the surface color over it, so the
text and buttons stay easy to read;
color changes it.
|
'vignette' |
0.5 |
Darkens the edges (black, or
color).
|
'frost' |
0.5 | Frosted glass: a blur and a light veil. |
'tint' |
0.6 |
Colors it in the played color, or
color.
|
'duotone' |
1 |
Two colors, dark and light: the surface
and played colors, or
colors.
|
'grain' |
0.15 | A fine grain, like film. |
Filters and transparency
filters change the picture itself:
blur (in pixels, up to 64),
brightness, contrast and
saturate (0 to 3, 1 leaves it),
grayscale and sepia (0 to 1).
opacity (0 to 1) lets the page show
through.
background: {
image: { src: '/covers/dusk.jpg' },
filters: { blur: 6, saturate: 1.4 },
effects: ['dim'],
opacity: 0.85,
},
Animation
look.backgroundAnimation moves the
background. By default it moves only while the sound
plays, so it is still whenever nobody is listening; it
never runs when the person asks for reduced motion.
Press play to see this one.
look: {
background: { gradient: { colors: ['#1b1f5e', '#7b3fa0', '#ef6f6c', '#ffc56b'], angle: 90 } },
backgroundAnimation: { type: 'flow', duration: 8 },
},
| Option | Default | What it does |
|---|---|---|
type |
'pan' |
'pan' glides it,
'zoom' swells it,
'pulse' breathes its
opacity, 'hue' turns its
colors round, 'flow' drifts
a gradient's colors.
|
duration |
20 |
Seconds for one way (2 to 600). |
strength |
0.5 |
How far it moves (0 to 1). |
while |
'playing' |
Moves while the sound plays, or
'always'.
|
pauseOnHover |
false |
Holds still while the mouse or the focus is on the player. |
In a theme and on the tag
The background is part of the look, so a theme can bring
one, and a player's own look changes only what it gives
(background: null turns it off).
registerTheme('dusk', {
extends: 'bubble',
look: { background: { image: { src: '/covers/dusk.jpg' }, effects: ['dim'] } },
});
<sonic-player
src="/episode.mp3"
background-image="/covers/dusk.jpg"
background-options="bottom"
background-effects="dim vignette"
background-animation="zoom hover-pause"
></sonic-player>
Every background- attribute is in
Tag attributes.
Safe by design
Colors are read as numbers before any style gets them, gradients are written from those numbers, and an image's address is checked first, so no text of the app ever reaches a style as it was given. The background is hidden from screen readers and sits behind the controls, never over them.