SonicFrame v1.3.2

Installation

One package, no dependencies, three entry points. Install it with your package manager, load it straight from a CDN, or build it from its source code.

With a package manager

SonicFrame is published on npm as sonicframe. Use whichever manager your project already uses:

npm install sonicframe
pnpm add sonicframe
yarn add sonicframe
bun add sonicframe

It brings nothing else along: the published package has no runtime dependencies and no install scripts. Types come in the package, so TypeScript needs nothing extra.

Three entry points

Import only what the page needs. An app that draws waves never loads the ready-made player, and a server that reads peaks never loads anything that touches the DOM.

Import What is in it Use it for
sonicframe The frame (SonicFrame), every plugin, the play button, the volume control, the peaks readers and the analysis functions. Building your own player, or drawing waves with your own controls.
sonicframe/player createPlayer, the themes and palettes, and the <sonic-player> tag. A complete player in one call or one tag.
sonicframe/analysis Pure functions: levels, silences, the wave in words, and the waveform file writer. Servers, workers and build scripts (Node, Deno, Bun).
sonicframe/record createRecorder, the Recorder without a screen, and the <sonic-recorder> tag. Recording from the microphone: record, hear, send.
import { SonicFrame, loadPeaks } from 'sonicframe';
import { createPlayer } from 'sonicframe/player';
import { writeWaveform } from 'sonicframe/analysis';

From a CDN

No build step? An npm CDN serves the package as plain modules. This address always brings the latest version:

<script type="module">
    import { createPlayer } from 'https://unpkg.com/sonicframe/dist/player.js';

    createPlayer({
        container: document.querySelector('#player'),
        src: '/voice.mp3',
    });
</script>

unpkg sends an address without a version on to the latest version's own address, so the entry file and the pieces it imports always come from the same version.

Tip A strict Content-Security-Policy keeps working: add the CDN to script-src, and nothing else is needed. SonicFrame sets no inline styles, runs no eval and starts no blob workers.

Want a specific version?

Put it in the address, after an @:

import { createPlayer } from 'https://unpkg.com/sonicframe@x.y.z/dist/player.js';

Replace x.y.z with the numbers of the version you want. The changelog lists every version. On a live site, a fixed version is the steadiest choice; any 1.x works with code written for 1.0, as Versions and support explains.

Smaller files, for pages without a bundler

Every entry also comes minified, beside the readable one: dist/player.min.js brings the same player in about half the bytes, without the comments.

import { createPlayer } from 'https://unpkg.com/sonicframe@x.y.z/dist/player.min.js';

From npm they are sonicframe/min, sonicframe/min/player, sonicframe/min/record, sonicframe/min/playlist and sonicframe/min/analysis, with the same types. A bundler minifies on its own, so with one, keep the readable entries.

Pick one set per page The minified files and the readable ones are separate copies. Loading player.js and player.min.js on the same page runs two SonicFrames that know nothing of each other: the second cannot register the tags the first did, and the now-playing bar follows one set only.

From the source code

Rather not use a package manager in your project? Build SonicFrame from its source once and copy the result into your site. Your site then loads plain files of its own, and nothing from npm goes into it.

To build, you need Node.js 22 (22.18 or later), 24 (24.11 or later) or 26 and up. Git is optional. Node brings npm along, which only fetches the build tools into the source folder.

1. Get the code

Clone the repository. Its main branch always holds the latest version:

git clone https://github.com/ediejohnny/sonicframe.git
cd sonicframe

No Git? Download the latest version as a zip and unzip it; the folder is named sonicframe-main.

2. Build it

npm ci
npm run build

npm ci installs the exact build tools the project pins, inside its folder. npm run build writes the library to dist/. To see the tests pass first, run npm test.

3. Copy the files into your site

Copy the whole dist/ folder into your site, with the LICENSE file next to it (the MIT license asks to keep its notice with the code); for example, as vendor/sonicframe/. Keep the folder whole: the entry files import shared pieces whose names change with every build.

4. Import it

Import the files by their path:

<div id="player"></div>

<script type="module">
    import { createPlayer } from './vendor/sonicframe/player.js';

    createPlayer({
        container: document.querySelector('#player'),
        src: '/voice.mp3',
    });
</script>

To keep the imports these docs use, such as 'sonicframe/player', add an import map before your first module:

<script type="importmap">
{
    "imports": {
        "sonicframe": "/vendor/sonicframe/index.js",
        "sonicframe/player": "/vendor/sonicframe/player.js",
        "sonicframe/analysis": "/vendor/sonicframe/analysis.js",
        "sonicframe/record": "/vendor/sonicframe/record.js"
    }
}
</script>
With a strict Content-Security-Policy An import map is an inline script, so script-src needs its hash ('sha256-…'). Imports by path, from your own module files, need nothing more.

With TypeScript, point the names at the types in the folder:

{
    "compilerOptions": {
        "paths": {
            "sonicframe": ["./vendor/sonicframe/index.d.ts"],
            "sonicframe/player": ["./vendor/sonicframe/player.d.ts"],
            "sonicframe/analysis": ["./vendor/sonicframe/analysis.d.ts"],
            "sonicframe/record": ["./vendor/sonicframe/record.d.ts"]
        }
    }
}

Updating

Inside the folder you cloned, get the latest code and build again:

git pull
npm ci
npm run build

Without Git, download the zip again. Then replace the whole folder in your site. The changelog says what changed.

Want a specific version?

Clone it by its tag:

git clone --branch vx.y.z https://github.com/ediejohnny/sonicframe.git
cd sonicframe

Replace x.y.z with the numbers of the version you want, and keep the v in front of them. The tags on GitHub list every version. Git then says the folder is in a "detached HEAD" state: that is expected, and only means it holds that one version.

Without Git, download the zip of the version, with the same numbers in place of the letters:

https://github.com/ediejohnny/sonicframe/archive/refs/tags/vx.y.z.zip

Then build, copy and import it as in steps 2 to 4. To move to another version, clone or download that one the same way.

Module format

SonicFrame is shipped as standard ES modules ("type": "module"), compiled for ES2022. Every current bundler (Vite, webpack, Rollup, esbuild, Parcel) and every current browser loads it as is. There is no CommonJS build; in Node, use import (or a dynamic import() from CommonJS).

The package is marked free of side effects, so a bundler drops every plugin and function you do not import.

Next steps

If it saves you time

SonicFrame is free and built by one person. Supporting it pays for the next releases and for accessibility in audio.