waveform-panel
v1.2.0TypeScript
<img src="https://gist.githubusercontent.com/stephenwf/c8d727a69a2c5d958298c6621b95c4c9/raw/caa0d6c1e47f693a1fc1a9b2c14d9c38152688ab/waveform.svg" />
0/weekUpdated 2 years agoMITUnpacked: 596.3 KB
Published by stephenwf
npm install waveform-panelWaveform panel
A web component that can display simple waveforms or compositions and crops of multiple waveforms. It uses SVG to render
the waveforms, with CSS variables for customising styling. It is interactive when hovering by default with simple
events for scrubbing.
- Waveform panel
* Installation
* Web Component
- Using the src attribute
- Using the sequences attribute
- Multiple sequences
- Multiple sources
- Multiple sources + sequences
- Updating current time
* Events
* Buffering + component
* Styling
Installation
``
bash
npm i waveform-panel
`or yarn
bash
yarn add waveform-panel
`and import somewhere in your bundle:
js
import 'waveform-panel';
`or you can drop the script into any HTML page:
html
`
Web Component
You will first need a generated waveform to get started. You can read more about this at https://waveform.prototyping.bbc.co.uk/
> waveform-data.js is part of a BBC R&D Browser-based audio waveform visualisation software family:
>
> - audiowaveform: C++ program that generates waveform data files from MP3 or WAV format audio.
> - audio_waveform-ruby: A Ruby gem that can read and write waveform data files.
> - waveform-data.js: JavaScript library that provides access to precomputed waveform data files, or can generate waveform data using the Web Audio API.
> - peaks.js: JavaScript UI component for interacting with waveforms.
Extract from bbc/waveform-data.js.
Once you have hosted your
files from this process, and you have the JS bundle for waveform-panel, you can
use the web component in your application. (Examples provided by The British Library)#### Using the
src attribute
`html
`You can also provide a duration, although this will be extracted from the loaded waveform.
html
duration="3723.4"
>
`#### Using the
attributeThe sequence attribute allows you to add a Media Frag selector to a waveform.
`html
sequence="https://iiif-waveforms.s3.eu-west-2.amazonaws.com/vdc_100052359795.0x000018.dat#t=100,1300"
>
`When you provide a
you can also provide an identifier. This could be the Audio resource, or just an internal
identifier that you can use. By default, the URL of the waveform will be the identifier. This identifier should then
be used in the sequence="" attribute. This identifier will also available in events.`html
sequence="my-identifier#t=100,1300"
>
`Identifiers can also be URLs, like a IIIF Canvas - allowing for some basic interoperability with Media Frags used in IIIF Presentation 3 Manifests for AV content.
html
sequence="https://api.bl.uk/metadata/iiif/ark:/81055/vdc_100052359795.0x000004#t=100,1300"
>
`
For the rest of the demos - shorter identifiers will be used for clarity.
#### Multiple sequences
You can chain multiple sequences together by using
between them.
`html
sequence="first#t=100,200 | first#t=200,500"
>
`#### Multiple sources
In addition to
you can also provide multiple waveforms using the srcset="" property.Each source is structured as follows:
`
[waveform-url] [identifier], [waveform-url] [identifier]
With spaces to add an identifier after each, and a comma (or pipe |) separating sources.`html
https://iiif-waveforms.s3.eu-west-2.amazonaws.com/vdc_100052359795.0x000018.dat first,
https://iiif-waveforms.s3.eu-west-2.amazonaws.com/vdc_100052359795.0x00001a.dat second,
"
>
`
_Note: Line breaks are valid, and added for readability._You can also optionally have a single
made up of multiple waveforms. This will internally
split the sequence into two distinct sections - but might be closer to the original data modelled.If you are using targets, the structure changes to be:
`
[waveform-url] [identifier]#t=[start],[end] | [waveform-url] [identifier]#t=[start],[end]
With spaces to add an identifier with target and only pipes to separate sources.`html
https://iiif-waveforms.s3.eu-west-2.amazonaws.com/vdc_100052359795.0x000018.dat first#t=0,50 |
https://iiif-waveforms.s3.eu-west-2.amazonaws.com/vdc_100052359795.0x00001a.dat first#t=50,100 |
"
>
`_Note: you have to use a pipe
to split sequences if you include #t= selectors._ #### Multiple sources + sequences
You can also create a more complex sequence using
srcset="" and sequences="" together.
`html
https://iiif-waveforms.s3.eu-west-2.amazonaws.com/vdc_100052359795.0x000018.dat first,
https://iiif-waveforms.s3.eu-west-2.amazonaws.com/vdc_100052359795.0x00001a.dat second,
"
sequence="
first#t=0,100 |
first#t=100,200 |
second#t=0,400
"
>
`This will use the sequence to build a single waveform from multiple sources. Currently, the amplitude is calculated
independently for each input - so a quiet source and relatively loud source together will not clearly reflect this difference.
#### Updating current time
You can pass in a
initially to set the time of the component. You can also update this programmatically from javascript as an audio source is playing, for example.
`html
current-time="200"
>
`This will be reflected in the UI.
Events
There is currently only one event that you can listen to:
. This is dispatched when the waveform is clicked at a specific time.
`html
src="https://iiif-waveforms.s3.eu-west-2.amazonaws.com/vdc_100052359795.0x000018.dat"
current-time="200"
>
`It will return some information in the
property you can use to drive other UIs or elements. Annotated example below:
`js
const detail = {
// Details of the sequence clicked.
currentSequence: {
// The start and end times of that sequence.
startTime: 0,
endTime: 3723.4,
id: 'https://api.bl.uk/metadata/iiif/ark:/81055/vdc_100052359795.0x000004',
// Internal identifier.
source: 'https__//api__bl__uk/metadata/iiif/ark__/81055/vdc_100052359795__0x000004__t=0__3723__4__',
// The waveform data
waveform: {
atWidth: 884.5, // The width that the waveform is displayed at
data: {} // Omitted, but the full raw waveform (resampled down to the width)
startPixel: 0, // where across the waveform this starts.
}
},
// Time relative to the whole waveform.
time: 2635.215828151498,
// Percent through the whole waveform
percent: 0.35387224420576596,
// Time relative to the individual sequence.
sequenceTime: 2635.215828151498,
// Where on the waveform clicked.
target: {x: 626, y: 95},
};
`Buffering +
component
Note: this is currently still under development.`html
src="https://iiif-waveforms.s3.eu-west-2.amazonaws.com/vdc_100052359795.0x000018.dat my-audio"
current-time="200"
>
`Styling
You can control the following styles using CSS variables, and target like a normal HTML element
css
waveform-panel {
--waveform-background: #000;
--waveform-base: #8a9aa1;
--waveform-hover: #14a4c3;
--waveform-buffered: #fff;
--waveform-progress: rgba(255, 255, 255, .4);
}
`Example light theme:
css
waveform-panel.light-waveform {
--waveform-background: #eee;
--waveform-base: #8a9aa1;
--waveform-hover: #14a4c3;
--waveform-buffered: #bbd5de;
--waveform-progress: rgba(0, 0, 0, .2);
}
`Usage with class:
html
src="https://iiif-waveforms.s3.eu-west-2.amazonaws.com/vdc_100052359795.0x000018.dat"
>
``