Docs: noise guide (#267)

* feat: docs - components for guide about noise generation

* feat: noise description

Author: michalsek

packages/audiodocs/docs/guides/noise_generation.mdx

@@ -0,0 +1,120 @@
+---
+sidebar_position: 4
+---
+
+import InteractiveExample from '@site/src/components/InteractiveExample';
+
+# Noise generation
+
+Noise is one of the most basic and common tools in digital audio processing, in this guide, we will go through most common noise types and how to implement them using web audio api.
+
+## White noise
+
+The most used type of noise. White is a random signal having equal intensity at different frequencies, giving it a constant [power spectral density. (Wikipedia)](https://en.wikipedia.org/wiki/Spectral_density#Power_spectral_density).
+
+To produce white noise, we simply create an `AudioBuffer` containing random samples in range of `[-1; 1]` (in which audio api operates), which can be used by `AudioBufferSourceNode` for playback, further filtering or modification
+
+```tsx
+function createWhiteNoise() {
+  const aCtx = = new AudioContext();
+  const bufferSize = aCtx.sampleRate * 2;
+  const output = new Array<number>(bufferSize);
+
+  for (let i = 0; i < bufferSize; i += 1) {
+    output[i] = Math.random() * 2 - 1;
+  }
+
+  const noiseBuffer = aCtx.createBuffer(1, bufferSize, aCtx.sampleRate);
+  noiseBuffer.copyToChannel(output, 0, 0);
+
+  return noiseBuffer;
+}
+```
+
+Usually we want the noise to be able to be played constantly. To achieve this we are generating 2 seconds of the noise sound, which we will later loop using the `AudioBufferSourceNode` properties. In audio processing `sampleRate` means number of samples that will be played during one second, thus we simply multiply this value by `2` to achieve desired length of the buffer.
+
+import WhiteNoise from '@site/src/examples/NoiseGeneration/WhiteNoiseComponent';
+import WhiteNoiseSrc from '!!raw-loader!@site/src/examples/NoiseGeneration/WhiteNoiseSource';
+
+<InteractiveExample component={WhiteNoise} src={WhiteNoiseSrc} />
+
+## Pink noise
+
+Pink noise, also known as 1/f noise (where "f" stands for frequency), is a type of signal or sound that has equal energy per octave. This means that the power spectral density (PSD) decreases inversely with frequency. In simpler terms, pink noise has more energy at lower frequencies and less energy at higher frequencies, which makes it sound softer and more balanced to the human ear than white noise.
+
+To generate pink noise, we will use the effects of a $\dfrac{-3dB}{octave}$ filter using the [Paul Kellet's refined method](https://www.musicdsp.org/en/latest/Filters/76-pink-noise-filter.html)
+
+```tsx
+const createPinkNoise = () => {
+  const aCtx = new AudioContext();
+
+  const bufferSize = 2 * aCtx.sampleRate;
+  const output = new Array<number>(bufferSize);
+
+  let b0, b1, b2, b3, b4, b5, b6;
+  b0 = b1 = b2 = b3 = b4 = b5 = b6 = 0.0;
+
+  for (let i = 0; i < bufferSize; i += 1) {
+    const white = Math.random() * 2 - 1;
+
+    b0 = 0.99886 * b0 + white * 0.0555179;
+    b1 = 0.99332 * b1 + white * 0.0750759;
+    b2 = 0.969 * b2 + white * 0.153852;
+    b3 = 0.8665 * b3 + white * 0.3104856;
+    b4 = 0.55 * b4 + white * 0.5329522;
+    b5 = -0.7616 * b5 - white * 0.016898;
+
+    output[i] = 0.11 * (b0 + b1 + b2 + b3 + b4 + b5 + b6 + white * 0.5362);
+    b6 = white * 0.115926;
+  }
+
+  const noiseBuffer = aCtx.createBuffer(1, bufferSize, aCtx.sampleRate);
+  noiseBuffer.copyToChannel(output, 0, 0);
+
+  return noiseBuffer;
+}
+```
+
+You can find more information about pink noise generation here: [https://www.firstpr.com.au/dsp/pink-noise/](https://www.firstpr.com.au/dsp/pink-noise/)
+
+import PinkNoise from '@site/src/examples/NoiseGeneration/PinkNoiseComponent';
+import PinkNoiseSrc from '!!raw-loader!@site/src/examples/NoiseGeneration/PinkNoiseSource';
+
+<InteractiveExample component={PinkNoise} src={PinkNoiseSrc} />
+
+## Brownian noise
+
+The last noise type I would like to describe is brownian noise (also known as Brown or red noise). Brownian noise is named after the Brownian motion phenomenon, where particles inside a fluid move randomly due to collisions with other particles. It relates to its sonic counterpart in that Brownian noise is characterized by a significant presence of low frequencies, with energy decreasing as the frequency increases. Brownian noise is believed to sound like waterfall.
+
+Brownian noise, similarly to pink one, decreases in power by $\dfrac{12dB}{octave}$ and sounds similar to waterfall. The implementation is taken from article by Zach Denton, [How to Generate Noise with the Web Audio API](https://noisehack.com/generate-noise-web-audio-api/):
+
+```tsx
+  const createBrownianNoise = () => {
+    const aCtx = new AudioContext();
+
+    const bufferSize = 2 * aCtx.sampleRate;
+    const output = new Array<number>(bufferSize);
+    let lastOut = 0.0;
+
+    for (let i = 0; i < bufferSize; i += 1) {
+      const white = Math.random() * 2 - 1;
+      output[i] = (lastOut + 0.02 * white) / 1.02;
+      lastOut = output[i];
+      output[i] *= 3.5;
+    }
+
+    const noiseBuffer = aCtx.createBuffer(1, bufferSize, aCtx.sampleRate);
+    noiseBuffer.copyToChannel(output, 0, 0);
+
+    return noiseBuffer;
+  }
+```
+
+import BrownianNoise from '@site/src/examples/NoiseGeneration/BrownianNoiseComponent';
+import BrownianNoiseSrc from '!!raw-loader!@site/src/examples/NoiseGeneration/BrownianNoiseSource';
+
+<InteractiveExample component={BrownianNoise} src={BrownianNoiseSrc} />
+
+## What's next?
+
+[fill after merge :)]

packages/audiodocs/docusaurus.config.js

@@ -3,6 +3,8 @@
 
 const lightCodeTheme = require('./src/theme/CodeBlock/highlighting-light.js');
 const darkCodeTheme = require('./src/theme/CodeBlock/highlighting-dark.js');
+const math = require('remark-math');
+const katex = require('rehype-katex');
 // This runs in Node.js - Don't use client-side code here (browser APIs, JSX...)
 
 const webpack = require('webpack');
@@ -42,6 +44,8 @@ const config = {
           breadcrumbs: false,
           sidebarCollapsible: false,
           sidebarPath: require.resolve('./sidebars.js'),
+          remarkPlugins: [math],
+          rehypePlugins: [katex],
           editUrl:
             'https://github.com/software-mansion-labs/react-native-audio-api/edit/main/packages/audiodocs/docs',
         },
@@ -57,6 +61,16 @@ const config = {
     ],
   ],
 
+  stylesheets: [
+    {
+      href: 'https://cdn.jsdelivr.net/npm/katex@0.13.24/dist/katex.min.css',
+      type: 'text/css',
+      integrity:
+        'sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM',
+      crossorigin: 'anonymous',
+    },
+  ],
+
   markdown: {
     mermaid: true,
   },
@@ -65,6 +79,7 @@ const config = {
   themeConfig: {
     // Replace with your project's social card
     // image: 'img/docusaurus-social-card.jpg',
+
     navbar: {
       hideOnScroll: true,
       title: 'React Native Audio API',

packages/audiodocs/package.json

@@ -34,6 +34,7 @@
     "babel-polyfill": "^6.26.0",
     "babel-preset-expo": "^9.2.2",
     "clsx": "^1.2.1",
+    "hast-util-is-element": "1.1.0",
     "raf": "^3.4.1",
     "raw-loader": "^4.0.2",
     "react": "^17.0.2",
@@ -45,6 +46,8 @@
     "react-native-gesture-handler": "^2.16.0",
     "react-native-reanimated": "^3.8.1",
     "react-native-web": "^0.18.12",
+    "rehype-katex": "5",
+    "remark-math": "3",
     "source-map": "^0.7.4",
     "source-map-loader": "^4.0.1",
     "usehooks-ts": "^2.9.1"

packages/audiodocs/src/components/LandingPage/OscillatorSquare.module.css

@@ -10,6 +10,7 @@
   cursor: pointer;
   background: transparent;
   overflow: visible;
+  background-clip: content-box;
 }
 
 .oscillatorBorder {
@@ -73,7 +74,7 @@
     background-color: rgba(255, 255, 255, 0.3);
   }
 
-  .oscillatorPointerInner {
+  .oscillatorPointerInnerOut {
     background-color: rgba(255, 255, 255, 0.1);
   }
 }

packages/audiodocs/src/examples/NoiseGeneration/BrownianNoiseComponent.tsx

@@ -0,0 +1,97 @@
+import React, { FC, useEffect, useRef } from 'react';
+import { View, Pressable, StyleSheet } from 'react-native';
+import { AudioContext, AudioBuffer, GainNode, AudioBufferSourceNode } from 'react-native-audio-api';
+
+const WhiteNoise: FC = () => {
+  const aCtxRef = useRef<AudioContext | null>(null);
+  const bufferRef = useRef<AudioBuffer | null>(null);
+  const gainRef = useRef<GainNode | null>(null);
+  const bufferNodeRef = useRef<AudioBufferSourceNode | null>(null);
+
+  const createBrownianNoise = () => {
+    const aCtx = aCtxRef.current;
+
+    if (!aCtx) {
+      return undefined;
+    }
+
+    const bufferSize = 2 * aCtx.sampleRate;
+    const output = new Array<number>(bufferSize);
+    let lastOut = 0.0;
+
+    for (let i = 0; i < bufferSize; i += 1) {
+      const white = Math.random() * 2 - 1;
+      output[i] = (lastOut + 0.02 * white) / 1.02;
+      lastOut = output[i];
+      output[i] *= 3.5;
+    }
+
+
+    const noiseBuffer = aCtx.createBuffer(1, bufferSize, aCtx.sampleRate);
+    noiseBuffer.copyToChannel(output, 0, 0);
+    return noiseBuffer;
+  }
+
+  const onPressIn = () => {
+    if (!bufferNodeRef.current) {
+      bufferNodeRef.current = aCtxRef.current.createBufferSource();
+      bufferNodeRef.current.buffer = bufferRef.current;
+      bufferNodeRef.current.loop = true;
+      bufferNodeRef.current.connect(gainRef.current);
+
+      bufferNodeRef.current.start();
+    }
+  }
+
+  const onPressOut = () => {
+    if (bufferNodeRef.current) {
+      bufferNodeRef.current.stop();
+      bufferNodeRef.current = null;
+    }
+  }
+
+  useEffect(() => {
+    if (!aCtxRef.current) {
+      aCtxRef.current = new AudioContext();
+    }
+
+    if (!bufferRef.current) {
+      bufferRef.current = createBrownianNoise();
+    }
+
+    if (!gainRef.current) {
+      gainRef.current = aCtxRef.current.createGain();
+      gainRef.current.gain.value = 0.3;
+      gainRef.current.connect(aCtxRef.current.destination);
+    }
+  }, []);
+  return (
+    <View style={styles.container}>
+      <Pressable onPressIn={onPressIn} onPressOut={onPressOut}>
+        {({ pressed }) => (
+          <View style={[styles.button, pressed && styles.buttonPressed]} />
+        )}
+      </Pressable>
+    </View>
+  );
+}
+
+export default WhiteNoise;
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  button: {
+    width: 160,
+    height: 160,
+    backgroundColor: '#b07eff',
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  buttonPressed: {
+    transform: [{ scale: 1.1 }],
+  },
+});

packages/audiodocs/src/examples/NoiseGeneration/BrownianNoiseSource.tsx

@@ -0,0 +1,97 @@
+import React, { FC, useEffect, useRef } from 'react';
+import { View, Pressable, StyleSheet } from 'react-native';
+import { AudioContext, AudioBuffer, GainNode, AudioBufferSourceNode } from 'react-native-audio-api';
+
+const WhiteNoise: FC = () => {
+  const aCtxRef = useRef<AudioContext | null>(null);
+  const bufferRef = useRef<AudioBuffer | null>(null);
+  const gainRef = useRef<GainNode | null>(null);
+  const bufferNodeRef = useRef<AudioBufferSourceNode | null>(null);
+
+  const createBrownianNoise = () => {
+    const aCtx = aCtxRef.current;
+
+    if (!aCtx) {
+      return undefined;
+    }
+
+    const bufferSize = 2 * aCtx.sampleRate;
+    const output = new Array<number>(bufferSize);
+    let lastOut = 0.0;
+
+    for (let i = 0; i < bufferSize; i += 1) {
+      const white = Math.random() * 2 - 1;
+      output[i] = (lastOut + 0.02 * white) / 1.02;
+      lastOut = output[i];
+      output[i] *= 3.5;
+    }
+
+
+    const noiseBuffer = aCtx.createBuffer(1, bufferSize, aCtx.sampleRate);
+    noiseBuffer.copyToChannel(output, 0, 0);
+    return noiseBuffer;
+  }
+
+  const onPressIn = () => {
+    if (!bufferNodeRef.current) {
+      bufferNodeRef.current = aCtxRef.current.createBufferSource();
+      bufferNodeRef.current.buffer = bufferRef.current;
+      bufferNodeRef.current.loop = true;
+      bufferNodeRef.current.connect(gainRef.current);
+
+      bufferNodeRef.current.start();
+    }
+  }
+
+  const onPressOut = () => {
+    if (bufferNodeRef.current) {
+      bufferNodeRef.current.stop();
+      bufferNodeRef.current = null;
+    }
+  }
+
+  useEffect(() => {
+    if (!aCtxRef.current) {
+      aCtxRef.current = new AudioContext();
+    }
+
+    if (!bufferRef.current) {
+      bufferRef.current = createBrownianNoise();
+    }
+
+    if (!gainRef.current) {
+      gainRef.current = aCtxRef.current.createGain();
+      gainRef.current.gain.value = 0.3;
+      gainRef.current.connect(aCtxRef.current.destination);
+    }
+  }, []);
+  return (
+    <View style={styles.container}>
+      <Pressable onPressIn={onPressIn} onPressOut={onPressOut}>
+        {({ pressed }) => (
+          <View style={[styles.button, pressed && styles.buttonPressed]} />
+        )}
+      </Pressable>
+    </View>
+  );
+}
+
+export default WhiteNoise;
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  button: {
+    width: 160,
+    height: 160,
+    backgroundColor: '#b07eff',
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  buttonPressed: {
+    transform: [{ scale: 1.1 }],
+  },
+});