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.
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.
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>
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
- Quickstart: a working player in five steps.
- The frame: what SonicFrame draws and how it follows the sound.
- Browser support: what runs where.
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.