siriwave
Version:
The Siri wave replicated in a JS library.
188 lines (125 loc) • 6.41 kB
Markdown
# SiriWave
The "Apple Siri" wave replicated in pure Javascript using the Canvas API. To learn more about the project, [read the blog post here](https://dev.to/kopiro/how-i-built-the-siriwavejs-library-a-look-at-the-math-and-the-code-l0o), [check the demo](http://kopiro.github.io/siriwave) or [codepen](https://codepen.io/kopiro/pen/oNYepEb).
[](https://badge.fury.io/js/siriwave)
### iOS (classic) style
The classic, pre-iOS9 style.
<img src="etc/classic.gif" />
### iOS9 style
The new fluorescent wave introduced in iOS9.
<img src="etc/ios9.gif" />
### iOS13 style
_work in progress_
The wave reinvented as a bubble.
## Usage
### Browser (via CDN) usage
Import the UMD package via the unpkg CDN and it's ready to use.
```html
<script src="https://unpkg.com/siriwave/dist/siriwave.umd.min.js"></script>
```
### ES module
Install it through `npm install siriwave` or `npm add siriwave` first:
```js
import SiriWave from "siriwave";
```
## Initialize
Create a div container and instantiate a new SiriWave object:
```html
<div id="siri-container"></div>
<script>
var siriWave = new SiriWave({
container: document.getElementById("siri-container"),
width: 640,
height: 200,
});
</script>
```
## Constructor options
| Key | Type | Description | Default | Required |
| -------------------------- | ------------------------ | ---------------------------------------------------------------------- | ---------- | -------- |
| `container` | DOMElement | The DOM container where the DOM canvas element will be added. | null | yes |
| `style` | "ios", "ios9" | The style of the wave. | "ios" | no |
| `ratio` | Number | Ratio of the display to use. Calculated by default. | calculated | no |
| `speed` | Number | The speed of the animation. | 0.2 | no |
| `amplitude` | Number | The amplitude of the complete wave-form. | 1 | no |
| `frequency` | Number | The frequency of the complete wave-form. Only available in style "ios" | 6 | no |
| `color` | String | Color of the wave. Only available in style "ios" | "#fff" | no |
| `cover` | Bool | The `canvas` covers the entire width or height of the container | false | no |
| `autostart` | Bool | Decide wether start the animation on boot. | false | no |
| `pixelDepth` | Number | Number of step (in pixels) used when drawed on canvas. | 0.02 | no |
| `lerpSpeed` | Number | Lerp speed to interpolate properties. | 0.01 | no |
| `curveDefinition` | ICurveDefinition[] | Override definition of the curves, check above for more details. | null | no |
| `ranges` | IiOS9Ranges | Override the default random ranges of the curves. | null | no |
| `globalCompositeOperation` | GlobalCompositeOperation | globalCompositeOperation of the canvas, controls wave overlap design. | "lighter" | no |
### Ranges
Each wave chooses a random parameter for each of these ranges that factors into their creation. You can override these ranges by passing a `ranges` object to the constructor.
Here is the type of the ranges object:
```ts
export type IiOS9Ranges = {
noOfCurves?: [number, number];
amplitude?: [number, number];
offset?: [number, number];
width?: [number, number];
speed?: [number, number];
despawnTimeout?: [number, number];
};
```
## API
#### `new SiriWave`
#### `curveDefinition`
By passing this argument, you're overriding the default curve definition resulting in a completely different style.
The default definition for the `ios` classic style is:
```js
[
{ attenuation: -2, lineWidth: 1, opacity: 0.1 },
{ attenuation: -6, lineWidth: 1, opacity: 0.2 },
{ attenuation: 4, lineWidth: 1, opacity: 0.4 },
{ attenuation: 2, lineWidth: 1, opacity: 0.6 },
{ attenuation: 1, lineWidth: 1.5, opacity: 1 },
];
```
and it results in 5 different sin-waves with different parameters and amplitude.
You can set 4 attributes for each curve:
- `attenuation`: the power factor determining the attenuation
- `lineWidth`: the line width
- `opacity`: the opacity
- `color`: the color, default to `SiriWave.color`; optional
The `ios9` style definition is instead:
```js
[
{ color: "255,255,255", supportLine: true },
{ color: "15, 82, 169" }, // blue
{ color: "173, 57, 76" }, // red
{ color: "48, 220, 155" }, // green
];
```
and it results in 3 different colored waves + 1 support wave that needs to be there.
Here you set:
- `supportLine`: only one of these curves must have this to `true`, it will be used to draw the support line
- `color`: the color of the wave
#### `start()`
Start the animation
#### `stop()`
Stop the animation.
#### `setSpeed(newValue)`
Set the new value of speed (animated)
#### `setAmplitude(value)`
Set the new value of amplitude (animated)
#### `dispose()`
Stop the animation and destroy the canvas, by removing it from the DOM.
Subsequent `start()` calls on this SiriWave instance will fail with an exception.
## Grapher plots
- [GCX default](etc/gcx/default.gcx)
- [GCX iOS 9](etc/gcx/ios9.gcx)
## Build and development
If you wanna make some modifications in your local environment, use:
```sh
npm dev
```
this will create a watchable build with RollupJS and automatically create a server to see your changes in the browser.
To finally build all targets:
```sh
npm build
```
## QA
#### How do I integrate this library with a microphone user input?
You can find an excellent demo [here](https://jsitor.com/PPQtOp9Yp) by @semmel