SonicFrame v1.3.2

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.