# How I built the SiriWaveJS library: a look at the math and the code

Oct 26, 2018 · 10 min read

It was 4 years ago when I had the idea to replicate the Apple® Siri wave-form (introduced with the iPhone 4S) in the browser using pure Javascript.

During the last month, I updated this library by doing a lot of refactoring using ES6 features and reviewed the build process using RollupJS. Now I’ve decided to share what I've learned during this process and the math behind this library.

To get an idea what the output will be, visit the live example; the whole codebase is here.

# The classic wave style

Initially, this library only had the classic wave-form style that all of you remember using in iOS 7 and iOS 8.

It’s no hard task to replicate this simple wave-form, only a bit of math and basic concepts of the Canvas API.

You’re probably thinking that the wave-form is a modification of the Sine math equation, and you're right…well, almost right.

Before starting to code, we’ve got to find our linear equation that will be simply applied afterwards. My favourite plot editor is Grapher; you can find it in any OSX installation under Applications > Utilities > Grapher.app.

We start by drawing the well known:

Perfecto! Now, let’s add some parameters (Amplitude [A], Time coordinate[t] and Spatial frequency [k]) that will be useful later (Read more here: https://en.wikipedia.org/wiki/Wave).

Now we have to “attenuate” this function on plot boundaries, so that for |x| > 2, the y values tends to 0. Let’s draw separately an equation g(x) that has these characteristics.

This seems to be a good equation to start with. Let’s add some parameters here too to smooth the curve for our purposes:

Now, by multiplying our f(x, …) and g(x, …), and by setting precise parameters to the other static values, we obtain something like this.

• A = 0.9 set the amplitude of the wave to max Y = A
• k = 8 set the spatial frequency and we obtain “more peaks” in the range [-2, 2]
• t = -π/2 set the phase translation so that f(0, …) = 1
• K = 4 set the factor for the “attenuation equation” so that the final equation is y = 0 when |x| ≥ 2

It looks good! 😍

Now, if you notice on the original wave we have other sub-waves that will give a lower value for the amplitude. Let’s draw them for A = {0.8, 0.6, 0.4, 0.2, -0.2, -0.4, -0.6, -0.8}

In the final canvas composition the sub-waves will be drawn with a decreasing opacity tending to 0.

## Basic code concepts

We use the equation to obtain the Y value for an input X.

Basically, by using a simple for loop from -2 to 2, (the plot boundaries in this case), we have to draw point by point the equation on the canvas using the beginPath and lineTo API.

`const ctx = canvas.getContext('2d');ctx.beginPath();ctx.strokeStyle = 'white';for (let i = -2; i <= 2; i += 0.01) {   const x = _xpos(i);   const y = _ypos(i);   ctx.lineTo(x, y);}ctx.stroke();`

Probably this pseudo-code will clear up these ideas. We still have to implement our _xpos and _ypos functions.

But… hey, what is 0.01⁉️ That value represents how many pixels you move forward in each iteration before reaching the right plot boundary… but what is the correct value?

If you use a really small value (<0.01), you’ll get an insanely precise rendering of the graph but your performance will decrease because you’ll get too many iterations.

Instead, if you use a really big value (> 0.1) your graph will lose precision and you’ll notice this instantly.

You can see that the final code is actually similar to the pseudo-code: https://github.com/kopiro/siriwave/blob/master/src/curve.js#L25

## Implement _xpos(i)

This is almost correct, but our plot is always drawn from -B to B (B = Boundary = 2).

So, to draw on the canvas via pixel coordinates, we must translate -B to 0, and B to 1 (simple transposition of [-B, B] to [0,1]); then multiply [0,1] and the canvas width (w).

_xpos(i) = w * [ (i + B) / 2B ]

https://github.com/kopiro/siriwave/blob/master/src/curve.js#L19

## Implement _ypos

`const K = 4;const FREQ = 6;function _attFn(x) {   return Math.pow(K / (K + Math.pow(x, K)), K);}function _ypos(i) {   return Math.sin(FREQ * i - phase) *       _attFn(i) *       canvasHeight *      globalAmplitude *       (1 / attenuation);}`

Let’s clarify some parameters.

• canvasHeight is Canvas height expressed in PX
• i is our input value (the x)
• phase is the most important parameter, let’s discuss it later
• globalAmplitude is a static parameter that represents the amplitude of the total wave (composed by sub-waves)
• attenuation is a static parameter that changes for each line and represents the amplitude of a wave

https://github.com/kopiro/siriwave/blob/master/src/curve.js#L24

## Phase

What does it mean? It means that for each animation frame, our base controller should increment this value. But to avoid this value throwing a buffer overflow, let’s modulo it with 2π (since Math.sin dominio is already modulo 2π).

`phase = (phase + (Math.PI / 2) * speed) % (2 * Math.PI);`

We multiply speed and Math.PI so that with speed = 1 we have the maximum speed (why? because sin(0) = 0, sin(π/2) = 1, sin(π) = 0, … 🤪)

## Finalizing

`return [   { attenuation: -2, lineWidth: 1.0, opacity: 0.1 },   { attenuation: -6, lineWidth: 1.0, opacity: 0.2 },   { attenuation: 4, lineWidth: 1.0, opacity: 0.4 },   { attenuation: 2, lineWidth: 1.0, opacity: 0.6},   // basic line   { attenuation: 1, lineWidth: 1.5, opacity: 1.0},];`

https://github.com/kopiro/siriwave/blob/master/src/siriwave.js#L190

# The iOS 9+ style

Now things start to get complicated. The style introduced with iOS 9 is really complex and the reverse engineering to simulate it it’s not easy at all! I’m not fully satisfied of the final result, but I’ll continue to improve it until I get the desired result.

As previously done, let’s start to obtain the linear equations of the waves.

As you can notice:

• we have three different specular equations with different colours (green, blue, red)
• a single wave seems to be a sum of sine equations with different parameters
• all other colours are a composition of these three base colours
• there is a straight line at the plot boundaries

By picking again our previous equations, let’s define a more complex equation that involves translation. We start by defining again our attenuation equation:

Now, define h(x, A, k, t) function, that is the sine function multiplied for attenuation function, in its absolute value:

We now have a powerful tool.

With h(x), we can now create the final wave-form by summing different h(x) with different parameters involving different amplitudes, frequency and translations. For example, let’s define the red curve by putting random values.

If we do the same with a green and blue curve, this is the result:

This is not quite perfect, but it could work.

To obtain the specular version, just multiply everything by -1.

In the coding side, the approach is the same, we have only a more complex equation for _ypos.

`const K = 4;const NO_OF_CURVES = 3;// This parameters should be generated randomlyconst widths = [ 0.4, 0.6, 0.3 ];const offsets = [ 1, 4, -3 ];const amplitudes = [ 0.5, 0.7, 0.2 ];const phases = [ 0, 0, 0 ];function _globalAttFn(x) {   return Math.pow(K / (K + Math.pow(x, 2)), K);}function _ypos(i) {   let y = 0;   for (let ci = 0; ci < NO_OF_CURVES; ci++) {      const t = offsets[ci];      const k = 1 / widths[ci];      const x = (i * k) - t;            y += Math.abs(         amplitudes[ci] *          Math.sin(x - phases[ci]) *          _globalAttFn(x)      );   }   y = y / NO_OF_CURVES;   return canvasHeightMax * globalAmplitude * y;}`

There’s nothing complex here. The only thing that changed is that we cycle NO_OF_CURVES times over all pseudo-random parameters and we sum all y values.

Before multiplying it for canvasHeightMax and globalAmplitude that give us the absolute PX coordinate of the canvas, we divide it for NO_OF_CURVES so that y is always ≤ 1.

https://github.com/kopiro/siriwave/blob/master/src/ios9curve.js#L103

## Composite operation

The default is set to source-over, but the result is poor, even with an opacity set.

You can see all examples of vary globalCompositeOperation here: https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D/globalCompositeOperation

By setting globalCompositeOperation to “ligther”, you notice that the intersection of the colours is nearest to the original.

# Build with RollupJS

Using the new ES6 feature like native classes, spread operators and lambda functions, I was able to clean everything, split files, and decrease lines of unnecessary code.

Furthermore, I used RollupJS to create a transpiled and minified build in various formats.

Since this is a browser-only library, I decided to create two builds: an UMD (Universal Module Definition) build that you can use directly by importing the script or by using CDN, and another one as an ESM module.

The UMD module is built with this configuration:

`{   input: 'src/siriwave.js',   output: {      file: pkg.unpkg,      name: pkg.amdName,      format: 'umd'    },    plugins: [       resolve(),       commonjs(),       babel({ exclude: 'node_modules/**' }),    ]}`

An additional minified UMD module is built with this configuration:

`{   input: 'src/siriwave.js',   output: {      file: pkg.unpkg.replace('.js', '.min.js'),      name: pkg.amdName,      format: 'umd'    },    plugins: [       resolve(),       commonjs(),       babel({ exclude: 'node_modules/**' }),       uglify()]}`

Benefiting of UnPKG service, you can find the final build on this URL served by a CDN: https://unpkg.com/siriwave/dist/siriwave.min.js

This is the “old style Javascript way” — you can just import your script and then refer in your code by using SiriWave global object.

To provide a more elegant and modern way, I also built an ESM module with this configuration:

`{    input: ‘src/siriwave.js’,   output: {       file: pkg.module,       format: ‘esm’   },    plugins: [       babel({ exclude: ‘node_modules/**’ })   ]}`

We clearly don’t want the resolve or commonjs RollupJS plugins because the developer transplier will resolve dependencies for us.

You can find the final RollupJS configuration here: https://github.com/kopiro/siriwave/blob/master/rollup.config.js

## Watch and Hot code reload

Basically, you just add these plugins when you’re in “developer” mode:

`import livereload from 'rollup-plugin-livereload';import serve from 'rollup-plugin-serve';if (process.env.NODE_ENV !== 'production') { additional_plugins.push(  serve({   open: true,   contentBase: '.'  }) ); additional_plugins.push(  livereload({   watch: 'dist'  }) );}`

We finish by adding these lines into the package.json:

`"module": "dist/siriwave.m.js","jsnext:main": "dist/siriwave.m.js","unpkg": "dist/siriwave.js","amdName": "SiriWave","scripts": {   "build": "NODE_ENV=production rollup -c",   "dev": "rollup -c -w"},`

Let’s clarify some parameters:

• module / jsnext:main: path of dist ESM module
• unpkg: path of dist UMD module
• amdName: name of the global object in UMD module

Thanks a lot RollupJS!

Written by

## More From Medium

Oct 25, 2018 · 21 min read

#### 1.2K

Aug 7, 2019 · 7 min read