04_Compressors.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### How to use this notebook (for anyone not familiar with jupyter)\n",
    "\n",
    "Before we get started, I'd like to note that while reading this notebook on github is fine, there are several interactive elements used to demonstrate several ideas that only render when the notebook is ran in a live kernel. This also allows you to play with the code samples inline with the rest of the notebook.\n",
    "\n",
    "For the best experience I'd recommend installing [jupyter](https://jupyter.org/install) on your machine and cloning this repository so that you can run the notebooks locally. \n",
    "\n",
    "If however you'd prefer not to install anything, you can also run this notebook on Google's Colab [here](https://colab.research.google.com/github/jd-13/dsp-math-for-audio/blob/master/04_Compressors.ipynb).\n",
    "\n",
    "Once running click `Kernel` -> `Restart & Run All` (or `Runtime` -> `Run all` if you're using Colab) to render all of the interactive examples, and you are then free to edit the code and run individual cells as you wish.\n",
    "\n",
    "Other notebooks in this series are available to view over on the [github repo](https://github.com/jd-13/dsp-math-for-audio)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "\"\"\"\n",
    "This code cell contains a few imports and functions that we'll need later but aren't of much interest.\n",
    "The main content starts immediately after.\n",
    "\"\"\"\n",
    "\n",
    "from ipywidgets import interact\n",
    "import matplotlib.pylab as plt\n",
    "import math\n",
    "import numpy as np\n",
    "import scipy.signal\n",
    "%matplotlib inline\n",
    "\n",
    "# We'll use this to define the x-axis of any graphs we plot\n",
    "NUM_SAMPLES = 200\n",
    "SAMPLE_RANGE = np.linspace(0, NUM_SAMPLES, NUM_SAMPLES)\n",
    "\n",
    "# Run at a lower than usual sample rate to keep the interactive examples from\n",
    "# needing too much compute\n",
    "SAMPLE_RATE = 10000\n",
    "\n",
    "Y_LIMIT = 0.8\n",
    "\n",
    "def sineWaveDecay(frequencyHz):\n",
    "    \"\"\"\n",
    "    Returns a np array of length numSamples containing a sine wave impulse\n",
    "    which decays linearly.\n",
    "    \"\"\"    \n",
    "    # Create a square impulse\n",
    "    amplitudeMap = np.zeros((NUM_SAMPLES))\n",
    "    amplitudeMap[70:75] = 1\n",
    "    \n",
    "    # Smooth the amplitude map\n",
    "    b, a = scipy.signal.butter(4, 0.1, btype=\"lowpass\", analog=False)\n",
    "    amplitudeMap = scipy.signal.lfilter(b, a, amplitudeMap)\n",
    "    \n",
    "    return amplitudeMap\n",
    "\n",
    "MINUS_INF_DB = -100\n",
    "\n",
    "def convertTodB(inputBuffer):\n",
    "    outputBuffer = np.zeros(inputBuffer.shape)\n",
    "    \n",
    "    for index in range(len(inputBuffer)):\n",
    "        if inputBuffer[index] > 0:\n",
    "            outputBuffer[index] = max(20 * math.log(inputBuffer[index], 10), MINUS_INF_DB)\n",
    "        else:\n",
    "            outputBuffer[index] = MINUS_INF_DB\n",
    "    \n",
    "    return outputBuffer\n",
    "\n",
    "def convertToLinear(inputBuffer):\n",
    "    outputBuffer = np.zeros(inputBuffer.shape)\n",
    "\n",
    "    for index in range(len(inputBuffer)):\n",
    "        if inputBuffer[index] > MINUS_INF_DB:\n",
    "            outputBuffer[index] = pow(10, inputBuffer[index] / 20.0)\n",
    "        else:\n",
    "            outputBuffer[index] = 0\n",
    "\n",
    "    return outputBuffer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Intro\n",
    "\n",
    "Dynamic range compression is an important concept within music production, and is used extensively throughout the production and mixing process. Compression can be used to subtlely maintain a consistent level on a recording, or at its extremes squash a signal until it produces noticeable distortion and artefacts, among many other more creative uses.\n",
    "\n",
    "In this notebook we'll dicuss:\n",
    "- how and why a compressor might used\n",
    "- the characteristics that are important to the design of a compressor and that differentiate one compressor from another\n",
    "- how a compressor works (with some interactive graphics!)\n",
    "- how to implement a basic compressor (with working and complete code examples)\n",
    "\n",
    "Note that many of the code examples in this notebook are intended to be readable rather than performant, so you may wish to make changes before attempting to use these examples in your own projects.\n",
    "\n",
    "## Overview of compressors\n",
    "\n",
    "In the simplest case, the main goal of a compressor is to reduce the dynamic range of the audio it is processing. In other words, a compressor reduces the volume difference between the loudest parts of an audio signal and the quietest.\n",
    "\n",
    "This is an important technique particularly for recordings such as vocals and bass guitar, which typically have a large variance in volume (the dynamic range) which from one moment to the next may be a little too loud for the mix or a little too quiet. This is where compression can be used to level out the peaks and troughs in the volume of the signal, so that it sits nicely and consistently with other elements of a mix.\n",
    "\n",
    "There are two main ways to approach the problem of dynamic range compression:\n",
    "- **Downward compression**: Reduce the volume of everything that *exceeds* a threshold\n",
    "- **Upward compression**: Increase the volume of everything that falls *below* a threshold\n",
    "\n",
    "Typically both types of compressor will then apply a \"makeup\" gain to the entire signal which controls the output level of the compressor.\n",
    "\n",
    "The amount of compression that is applied to a signal above (in the case of a downward compressor) or below (in the case of an upward compressor) the threshold is determined by a *ratio* parameter.\n",
    "\n",
    "That said, most popular compressors you are likely to see in use fall into the downward compression category, with upward compression being used very rarely.\n",
    "\n",
    "The way a compressor applies its volume reduction can be visualised by plotting a graph of input amplitude on the x-axis and output amplitude on the y-axis as below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "428c673cc73d4e4eabe8dade76caeff8",
       "version_major": 2,
       "version_minor": 0
      },
      "text/html": [
       "<p>Failed to display Jupyter Widget of type <code>interactive</code>.</p>\n",
       "<p>\n",
       "  If you're reading this message in the Jupyter Notebook or JupyterLab Notebook, it may mean\n",
       "  that the widgets JavaScript is still loading. If this message persists, it\n",
       "  likely means that the widgets JavaScript library is either not installed or\n",
       "  not enabled. See the <a href=\"https://ipywidgets.readthedocs.io/en/stable/user_install.html\">Jupyter\n",
       "  Widgets Documentation</a> for setup instructions.\n",
       "</p>\n",
       "<p>\n",
       "  If you're reading this message in another frontend (for example, a static\n",
       "  rendering on GitHub or <a href=\"https://nbviewer.jupyter.org/\">NBViewer</a>),\n",
       "  it may mean that your frontend doesn't currently support widgets.\n",
       "</p>\n"
      ],
      "text/plain": [
       "interactive(children=(FloatSlider(value=0.55, description='threshold', max=0.9, min=0.2, step=0.05), IntSlider(value=5, description='ratio', max=10, min=1), FloatSlider(value=0.0, description='inputAmp', max=1.0, step=0.05), Output()), _dom_classes=('widget-interact',))"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "def compressDown(threshold, ratio, inputAmp):\n",
    "    if inputAmp > threshold:\n",
    "        return threshold + (inputAmp - threshold) / ratio\n",
    "    else:\n",
    "        return inputAmp\n",
    "\n",
    "def compressUp(threshold, ratio, inputAmp):\n",
    "    if inputAmp > threshold:\n",
    "        return inputAmp\n",
    "    else:\n",
    "        return threshold - (threshold - inputAmp) / ratio\n",
    "\n",
    "@interact(threshold=(0.2, 0.9, 0.05), ratio=(1, 10, 1), inputAmp=(0, 1, 0.05))\n",
    "def plotCompression(threshold, ratio, inputAmp):\n",
    "    plt.figure(figsize=(8, 4))\n",
    "    xcoords = [0, threshold, 1]\n",
    "        \n",
    "    # Plot downward\n",
    "    ycoords = [0, threshold, compressDown(threshold, ratio, 1)]\n",
    "    outputAmp = compressDown(threshold, ratio, inputAmp)\n",
    "\n",
    "    plt.subplot(1, 2, 1)\n",
    "    plt.plot(xcoords, ycoords)\n",
    "    plt.plot([inputAmp, inputAmp], [0, outputAmp])\n",
    "    plt.plot([0, inputAmp], [outputAmp, outputAmp])\n",
    "\n",
    "    plt.xlim(left=0, right=1)\n",
    "    plt.ylim(bottom=0, top=1)\n",
    "    plt.xlabel(\"Input amplitude\")\n",
    "    plt.ylabel(\"Output amplitude\")\n",
    "    plt.title(\"Downward compression\")\n",
    "    \n",
    "    # Plot upward\n",
    "    ycoords = [compressUp(threshold, ratio, 0), threshold, 1]\n",
    "    outputAmp = compressUp(threshold, ratio, inputAmp)\n",
    "\n",
    "    plt.subplot(1, 2, 2)\n",
    "    plt.plot(xcoords, ycoords)\n",
    "    plt.plot([inputAmp, inputAmp], [0, outputAmp])\n",
    "    plt.plot([0, inputAmp], [outputAmp, outputAmp])\n",
    "\n",
    "    plt.xlim(left=0, right=1)\n",
    "    plt.ylim(bottom=0, top=1)\n",
    "    plt.xlabel(\"Input amplitude\")\n",
    "    plt.ylabel(\"Output amplitude\")\n",
    "    plt.title(\"Upward compression\")\n",
    "\n",
    "    \n",
    "    plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In the case of the downward compressor, at input volumes below a **threshold** no compression is applied, therefore the output amplitude equals the input amplitude. But at input amplitudes above the **threshold** the gain reduction is applied. The amount of gain reduction is described as a **ratio**, such as 2:1, 4:1, etc. This means that when the input amplitude exceeds the threshold, the output amplitude will be equal to everything below the threshold, *plus* everything above the threshold divided by the ratio.\n",
    "\n",
    "For the upward compressor you can see the opposite is true, with the signal being *multiplied* by the ratio when below the threshold, but passed through unchanged when above the threshold.\n",
    "\n",
    "But this simple dynamic range adjustment is not all that compressors are used for, with many models of analogue compressor becaming famous because of their imperfections which lead them to do a little more to a signal than just reduce its dynamic range. These imperfections may cause the compressor to affect different frequency ranges differently or introduce a small level or distortion, in turn changing the frequency content of a signal by a small amount.\n",
    "\n",
    "Another important feature of a compressor which we've not yet mentioned is the **attack** and **release** time. These parameters control how quickly the compressor applies the volume reduction after the input amplitude has exceeded the threshold, and for how long it continues to apply the volume reduction after the input amplitude has dropped back below the threshold (or vice versa for an upwards compressor).\n",
    "\n",
    "These controls are very important to controlling the behaviour of the compressor, for example a slower attack allows more of the initial transient of a sound to pass through before triggering the compressor, and slower release will cause the compressor to hang on to a sound for longer.\n",
    "\n",
    "## Types of compressor\n",
    "\n",
    "\n",
    "### Analogue\n",
    "\n",
    "Until recent years, all compressors were what we would consider to be analogue compressors. This means the compressor would be a physical piece of hardware (often rackmounted), and would use an electrical circuit to apply the compression. This type of compressor is still in widespread use today, and several models of analogue compressor have become sought-after enough to warrant software emulations of them.\n",
    "\n",
    "One of the main areas that these compressors differentiated themselves from the competition was in the implementation of their compression circuits, the most popular of which can roughly be grouped as follows:\n",
    "\n",
    "|                | Optical                                                        | FET                                  | VCA                                                 |\n",
    "| :------------: | :------------------------------------------------------------: | :----------------------------------: | :-------------------------------------------------: |\n",
    "| Character      | Often described as \"warm\" or \"colourful\", noticable distortion | Less colourful, less distortion      | Usually very clean, minimal colouration             |\n",
    "| Attack/Release | Typically slowest                                              | Faster                               | Often equally capable at slow and fast times        |\n",
    "| Application    | Popular for vocals, melodic instruments                        | Often used on vocals, guitars, drums | Bus compressors                                     |\n",
    "| As seen in     | Teletronicx LA-2A and LA-3A                                    | UREI 1176                            | Focusrite Red, dbx 160, SSL G master bus compressor |\n",
    "\n",
    "*Some of the statements above are broad generalisations of each design, and you are likely to find examples of each which contradict these*\n",
    "\n",
    "### Digital\n",
    "\n",
    "In recent years digital compressors have become much more popular, due to lower cost, new design possibilties, and multiple possible form factors. One of the key advantages of a digital compressor is the it can be built not only as a rack unit, but also a VST plugin, standalone software, or integrated into a digital effects unit or pedalboard alongside dozens of other effects.\n",
    "\n",
    "Digital compression also opens up many possibilities in terms of how a compressor can sound, since the design is no longer limited by the components which makeup the circuit but rather how much can be computed while keeping the latency low.\n",
    "\n",
    "Because of this, in recent years all kinds of software based compressors have been created, with some aiming to be super accurate models of the previously mentioned analogue compressors (often with a few added improvements), some aiming to be the cleanest, fastest, and most transparent compressor, and others going in their own direction to reimagine what a compressor can sound like.\n",
    "\n",
    "## Other compressor based devices\n",
    "\n",
    "Before we go any further and start looking into the implementation of a basic compression algorithm, you may come across a few other devices that perform a similar function to a compressor which are worth briefly mentioning. This isn't an exhaustive list, but contains the most common of these devices.\n",
    "\n",
    "### Limiters\n",
    "\n",
    "A limiter is typically a specialised version of a downward compressor, usually with a very high ratio. These devices are often used where an audio signal needs to be prevented from significantly exceeding the threshold, and are a staple of most mastering processes.\n",
    "\n",
    "### Multiband compressors\n",
    "\n",
    "A multiband compressor works by first using several crossover filters to split a signal into two or more frequency bands and then passing the resulting signals to separate compressors. For example in a 3 band multiband compressor, you would have one compressor for the lowest frequencies, one compressor for those in the middle, and another for the highest.\n",
    "\n",
    "In most implementations the compressors of each band can function independently, with their own controls for threshold, ratio, etc. The frequency range which each compressor is responsible for is often also controllable by the user.\n",
    "\n",
    "### De-essers\n",
    "\n",
    "Usually used to reduce sibilance in vocal recordings, a de-esser is often implemented as a compressor which only operates on a particular frequency range. In this way it can limit the amplitude of the frequencies in the range within which the sibilence is occurring by applying compression to only those frequncies.\n",
    "\n",
    "### Expanders\n",
    "\n",
    "An expander is effectively a device which does the opposite of a compressor, and increases the dynamic range of an audio signal rather than trying to reduce it.\n",
    "\n",
    "## Implementation\n",
    "\n",
    "*(Much of this section is based on the paper [Digital Dynamic Range Compressor Design - A Tutorial and Analysis](https://www.researchgate.net/publication/277772168_Digital_Dynamic_Range_Compressor_Design-A_Tutorial_and_Analysis), which I recommend reading for additional details)*\n",
    "\n",
    "Now that we know a little about what compressors do and how they're used, we can start looking at how to actually build one. In most compressors there are two key components: the level detector, and the gain computer.\n",
    "\n",
    "Between these two the gain reduction applied to the signal is calculated, and we'll look at how these work exactly very soon. First though we need a higher level view of how these components can be arranged, in either feedforward or feedback designs.\n",
    "\n",
    "### Feedforward vs feedback\n",
    "\n",
    "Both analogue and digital compressors can be implemented using feedforward or feedback designs. Below you can see a simplified diagram of the signal chain of a feedforward design:\n",
    "\n",
    "![](https://raw.githubusercontent.com/jd-13/dsp-math-for-audio/master/assets/compressors/simpleFeedforward.png)\n",
    "\n",
    "The process can be summarised as the following steps:\n",
    "1. Input is split between being routed to the output and the level detector\n",
    "2. Level detector generates a signal representing the amplitude of the input\n",
    "3. Gain computer takes the output of the level detector, and checks it against the parameters (threshold, ratio, etc) and decides how much gain reduction should be applied\n",
    "4. Gain is applied to the original signal before it reaches the output\n",
    "\n",
    "A feedback design uses the same components as a feedforward design, but as you can see below it does the steps in a slightly different order:\n",
    "\n",
    "![](https://raw.githubusercontent.com/jd-13/dsp-math-for-audio/master/assets/compressors/simpleFeedback.png)\n",
    "\n",
    "Here the same process has occured as in the feedforward design, but this time we're using the signal after it has already been compressed to drive the level detector.\n",
    "\n",
    "Most modern compressors are based on a feedforward design as it allows for the implementation of lookahead, and perfect limiting.\n",
    "\n",
    "Feedback designs were often used in early analogue compressors as they reduce the dynamic range which the level detector and gain computer must be able to operate effectively on, since they only see the input signal after its dynamic range has already been reduced.\n",
    "\n",
    "In digital compressors this is no longer a concern, so for the remainder of this notebook we will be focusing on feedforward designs.\n",
    "\n",
    "### Level detection\n",
    "\n",
    "Since the level detector is the start of the chain, this is where we'll start with our implementaion\n",
    "\n",
    "If you've read the previous notebooks on envelope followers (part 1 [here](https://colab.research.google.com/github/jd-13/dsp-math-for-audio/blob/master/02_Envelope-Followers.ipynb), and part 2 [here](https://colab.research.google.com/github/jd-13/dsp-math-for-audio/blob/master/03_Envelope-Followers-Part-2.ipynb)) then this section may seem familiar. The process of performing level detection is conceptually very similar to that of an envelope follower - an input signal is provided, and from it another signal describing how it's amplitude changes is produced.\n",
    "\n",
    "Also like envelope followers they provide attack and release times which can be controlled by the user, which controls how quickly the produced signal rises and falls while tracking the amplitude of the input signal.\n",
    "\n",
    "There are two common methods of level detection used in compressors: root-mean-squared (RMS) and peak.\n",
    "\n",
    "* __RMS__: Provides a smoothed average of the signal that more closely represents the perceived loudness, but introduces a latency in order to calculate the average\n",
    "* __Peak__: Follows the amplitude of the signal without any averaging, this is the most commonly used method in compressors\n",
    "\n",
    "Now we'll look at two possible implementations, and plot their outputs to compare their performance. Let's first look at a simple implementation of a peak level detector:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [],
   "source": [
    "def simplePeakLevelDetector(inputSignal, attack, release):\n",
    "    \"\"\"\n",
    "    Example implementation of a basic peak level detection algorithm with\n",
    "    separate attack and release controls.\n",
    "    \n",
    "    Based on equation 12 of the previously linked paper.\n",
    "    \"\"\"\n",
    "    \n",
    "    outputBuffer = np.zeros(inputSignal.shape)\n",
    "    \n",
    "    for index in range(len(inputSignal)):\n",
    "\n",
    "        outputBuffer[index] = release * outputBuffer[index - 1] \\\n",
    "                              + (1 - attack) * max(inputSignal[index] - outputBuffer[index - 1], 0)\n",
    "        \n",
    "    return outputBuffer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The above design is one of the simplest but is still used often. The code is fairly simple, it first creates an empty output buffer of the correct size and runs the following loop for each sample:\n",
    "\n",
    "1. Multiply the release coefficient by the previously processed sample - a greater release coefficient means this value will be greater and hang around longer, a smaller release coefficient will cause this value to decay faster\n",
    "\n",
    "2. If the signal is rising, max() will return the difference between the previously processed sample and the current sample, which is then multiplied by the term (1 - attack coefficient) and added to our output, else max() returns 0 and this entire attack term is ignored\n",
    "\n",
    "This works reasonably well for many applications, but unfortunately it couples the effect of the attack and release coefficents such that they don't operate independently. For example, in this implementation a shorter release effectively also causes the attack to be shorter.\n",
    "\n",
    "This can be addressed by breaking the attack and release phases into separate branches of an if statement, which brings us to the next implementation:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [],
   "source": [
    "def decoupledPeakLevelDetector(inputSignal, attack, release):\n",
    "    \"\"\"\n",
    "    Example implementation of a peak level detection algorithm with decoupled\n",
    "    attack and release constants.\n",
    "    \n",
    "    Based on equation 16 of the previously linked paper.\n",
    "    \"\"\"\n",
    "\n",
    "    outputBuffer = np.zeros(inputSignal.shape)\n",
    "    \n",
    "    for index in range(len(inputSignal)):\n",
    "        \n",
    "        if inputSignal[index] > outputBuffer[index - 1]:\n",
    "            # Attack phase\n",
    "            outputBuffer[index] = attack * outputBuffer[index - 1] + (1 - attack) * inputSignal[index]\n",
    "        else:\n",
    "            # Release phase\n",
    "            outputBuffer[index] = release * outputBuffer[index - 1] + (1 - release) * inputSignal[index]\n",
    "    \n",
    "    return outputBuffer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As before the first thing is to create our output buffer, but in the for loop we now check if the current input sample is greater than the last processed sample.\n",
    "\n",
    "If the input is greater, then the signal must be rising and the level detector should treat this as the attack phase. If the input is smaller (or the same), then the signal must be falling (or staying the same) and the level detector should treat this as the release phase.\n",
    "\n",
    "You can see that the equations in both the attack and release phase are the same, but just using their respective attack and release coefficients.\n",
    "\n",
    "For the attack phase, we do the following two things:\n",
    "1. Multiply the attack coefficient by the previously processed sample - a greater attack coefficient means this value will be greater and therefore the previously processed samples have more influence on the processed output for this sample and future ones\n",
    "2. Multiply (1 - attack coefficient) by the current input sample and add it to the output - here a greater attack coefficient means this value will be smaller and the current input sample has less influence on the current output sample\n",
    "\n",
    "The release phase works in exactly the same way, just using the release coefficient.\n",
    "\n",
    "The two steps described above mean that at high attack/release coefficients the level detector will lag behind the input because previous samples have more influence on the output than current ones, and at smaller attack/release coefficients the level detector will track the input more closely as the current input sample becomes the dominating influence on the output.\n",
    "\n",
    "One last thing to note is that both of these implementations expect the signal to have been rectified before being passed to them. This means that the signal will contain only positive values, and we need to do this because a level detector only cares about the absolute magnitude of the signal, not whether it is positive or negative.\n",
    "\n",
    "Now that we've seen both implementations, let's see how they compare when processing a simple signal:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "899e0670faa243c0855cd20581d0d1d3",
       "version_major": 2,
       "version_minor": 0
      },
      "text/html": [
       "<p>Failed to display Jupyter Widget of type <code>interactive</code>.</p>\n",
       "<p>\n",
       "  If you're reading this message in the Jupyter Notebook or JupyterLab Notebook, it may mean\n",
       "  that the widgets JavaScript is still loading. If this message persists, it\n",
       "  likely means that the widgets JavaScript library is either not installed or\n",
       "  not enabled. See the <a href=\"https://ipywidgets.readthedocs.io/en/stable/user_install.html\">Jupyter\n",
       "  Widgets Documentation</a> for setup instructions.\n",
       "</p>\n",
       "<p>\n",
       "  If you're reading this message in another frontend (for example, a static\n",
       "  rendering on GitHub or <a href=\"https://nbviewer.jupyter.org/\">NBViewer</a>),\n",
       "  it may mean that your frontend doesn't currently support widgets.\n",
       "</p>\n"
      ],
      "text/plain": [
       "interactive(children=(FloatSlider(value=0.55, description='attack', max=1.0, min=0.1, step=0.05), FloatSlider(value=0.75, description='release', max=1.0, min=0.5, step=0.05), Output()), _dom_classes=('widget-interact',))"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "@interact(attack=(0.1, 1, 0.05), release=(0.5, 1, 0.05))\n",
    "def plotLevelDetector(attack, release):\n",
    "    \"\"\"\n",
    "    Feeds a sine wave impluse to the level detectors and plots the outputs.\n",
    "    \"\"\"\n",
    "    \n",
    "    # Generate the input signal\n",
    "    signalBuffer = sineWaveDecay(3000)\n",
    "\n",
    "    # Plot the input signal\n",
    "    plt.figure(figsize=(15, 4))\n",
    "    plt.plot(SAMPLE_RANGE, signalBuffer, label=\"Input\")\n",
    "    \n",
    "    # Rectify the signal using abs()\n",
    "    absBuffer = abs(signalBuffer)\n",
    "    \n",
    "    # Plot the simple level detector\n",
    "    simpleLevelBuffer = simplePeakLevelDetector(absBuffer, attack, release)\n",
    "    plt.plot(SAMPLE_RANGE, simpleLevelBuffer, label=f\"Simple Peak Detector\")\n",
    "\n",
    "    # Plot the decoupled level detector\n",
    "    decoupledLevelBuffer = decoupledPeakLevelDetector(absBuffer, attack, release)\n",
    "    plt.plot(SAMPLE_RANGE, decoupledLevelBuffer, label=f\"Decoupled Peak Detector\")\n",
    "\n",
    "    # Configure the plot\n",
    "    plt.ylim(bottom=-Y_LIMIT, top=Y_LIMIT)\n",
    "    plt.xlabel(\"Samples\")\n",
    "    plt.ylabel(\"Displacement\")\n",
    "    plt.legend(loc='upper left')\n",
    "\n",
    "    plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The most noticable difference is in how the simple detector produces a much smaller output than the decoupled detector except for at the fastest attack and slowest release, whereas the decoupled detector tracks the input much more closely.\n",
    "\n",
    "Also notice how when changing the release, the attack of the simple detector changes but the attack of the decoupled detector does not. This demonstrates that the decoupled detector does indeed decouple the effects of its attack and release coeffcients.\n",
    "\n",
    "### Gain computer\n",
    "\n",
    "The gain computer is the component which takes the output signal from the level detector, and uses the threshold, ratio, and knee parameters to decide how much gain (reduction) to apply to the original input signal.\n",
    "\n",
    "The **knee** parameter softens the transition when the signal starts to approach the threshold and compression is applied. This might be a little hard to imagine but we'll see an example shortly.\n",
    "\n",
    "Now that we know what the gain computer is supposed to do, we can look at an example implementation and see how it works:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "metadata": {},
   "outputs": [],
   "source": [
    "def gainComputer(inputBuffer, thresholddB, ratio, kneeWidth):\n",
    "    \"\"\"\n",
    "    Simple gain computer with adjustable knee width based on equations 4 and 20 of the linked paper.\n",
    "    \"\"\"\n",
    "\n",
    "    outputBuffer = np.zeros(inputBuffer.shape)\n",
    "\n",
    "    for index in range(len(inputBuffer)):\n",
    "        if inputBuffer[index] - thresholddB < -kneeWidth / 2:\n",
    "            # Level is sufficiently far below the threshold to be unaffected by the knee\n",
    "            # No compression applied, so output equals input\n",
    "            outputBuffer[index] = inputBuffer[index]\n",
    "            \n",
    "        elif abs(inputBuffer[index] - thresholddB) <= kneeWidth / 2:\n",
    "            # Level is close enough to the threshold to be affected by the knee\n",
    "            # Some compression is applied but at a lower ratio\n",
    "            outputBuffer[index] = inputBuffer[index] + (1 / ratio - 1) \\\n",
    "                                  * pow(inputBuffer[index] - thresholddB + kneeWidth / 2, 2) / (2 * kneeWidth)\n",
    "\n",
    "        else:\n",
    "            # Level is sufficiently far above the threshold to be unaffected by the knee\n",
    "            # Compress the signal above the threshold by the ratio\n",
    "            outputBuffer[index] = thresholddB + (inputBuffer[index] - thresholddB) / ratio\n",
    "\n",
    "    return outputBuffer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As in the level detector we first create an output buffer, then we go through our input buffer, sample by sample. This input buffer contains the output from our level detector, after it has been converted to decibels. When we convert the values from the level detector from it's linear scale between 0 and 1 to the logarithmic decibel scale, 0 becomes -infinity dB, and 1 becomes 0dB.\n",
    "\n",
    "Since negative infinity isn't very useful to actually do maths with, we set a lower bound at -100dB. We also use the threshold value in decibels, since this will be subtracted from the input so needs to be in the same units.\n",
    "\n",
    "After the output of the gain computer we'll later add another stage to convert from decibels back to a linear value between 0 and 1, which we can multiply by our input signal to apply the compression.\n",
    "\n",
    "All the important processing here happens inside the for loop, which you can see contains an if-else with three branches:\n",
    "\n",
    "#### Level is below threshold\n",
    "\n",
    "This is pretty simple, no compression is applied, so output equals input.\n",
    "\n",
    "Since the compressor has a knee we need to make sure that the level is sufficiently low that it doesn't enter this transitional region, so we first get the distance between the threshold and the level, and compare this to half of the knee width.\n",
    "\n",
    "We only use half of the knee width since the knee width extends either side of the threshold, so when comparing to a distance from the threshold we only need to use half of it.\n",
    "\n",
    "#### Level is near threshold\n",
    "\n",
    "When the level gets near to the threshold we need to start applying *some* compression but not the full amount. At this point the level could be above or below the threshold, but as long as it is in the transitional region the same math can be applied either way. This is why we use abs() when checking the distance from the threshold, and again why we divide the knee width by 2.\n",
    "\n",
    "The maths in this branch might look a little more complex, but it will make sense after some thought. Let's start by considering what will happen when the input level is only *just* high enough to be affected by the knee, so sits at the lower boundary of the knee. In this case the following is true:\n",
    "\n",
    "$ input level = threshold - \\frac{knee width}{2} $\n",
    "\n",
    "If we substitute that into the equation used by this branch of the if statement, we see that it cancels out with other terms and leaves only the input level term:\n",
    "\n",
    "$ output = input level + (\\frac{1}{ratio} - 1)(input level - threshold + \\frac{knee width}{2})^2\\frac{1}{2 * knee width} $\n",
    "\n",
    "$ output = input level + (\\frac{1}{ratio} - 1)((threshold - \\frac{knee width}{2}) - threshold + \\frac{knee width}{2})^2\\frac{1}{2 * knee width} $\n",
    "\n",
    "$ output = input level + (\\frac{1}{ratio} - 1)(0)^2\\frac{1}{2 * knee width} $\n",
    "\n",
    "$ output = input level $\n",
    "\n",
    "This makes sense, because at the lower boundary of the knee we would expect it to meet smoothly with the equation for the region below the threshold and knee, which is simply output equals input.\n",
    "\n",
    "Now for the other end of this equation, when the input level is not *quite* high enough to escape the knee, so sits at the upper boundary of the knee. In this case the following is true:\n",
    "\n",
    "$ input level = threshold + \\frac{knee width}{2} $\n",
    "\n",
    "Now let's substitute this into the equation for this branch as we did before:\n",
    "\n",
    "$ output = input level + (\\frac{1}{ratio} - 1)(input level - threshold + \\frac{knee width}{2})^2\\frac{1}{2 * knee width} $\n",
    "\n",
    "$ output = input level + (\\frac{1}{ratio} - 1)((threshold + \\frac{knee width}{2}) - threshold + \\frac{knee width}{2})^2\\frac{1}{2 * knee width} $\n",
    "\n",
    "$ output = input level + (\\frac{1}{ratio} - 1)knee width^2\\frac{1}{2 * knee width} $\n",
    "\n",
    "$ output = input level + (\\frac{1}{ratio} - 1)\\frac{knee width}{2} $\n",
    "\n",
    "Now at this point it's not exactly clear how to simplify this such that it matches the equation for the branch above the knee, so we'll substitute the same value of input level into that equation for the upper branch and attempt to meet in the middle:\n",
    "\n",
    "$ output = threshold + \\frac{input level - threshold}{ratio} $\n",
    "\n",
    "$ output = input level - \\frac{knee width}{2} + \\frac{(threshold + \\frac{knee width}{2}) - threshold}{ratio} $\n",
    "\n",
    "$ output = input level - \\frac{knee width}{2} + \\frac{\\frac{knee width}{2}}{ratio} $\n",
    "\n",
    "$ output = input level + (\\frac{1}{ratio} - 1)\\frac{knee width}{2} $\n",
    "\n",
    "As we can see, the equation for the middle branch does simplify to match the equation for the upper branch when at an input level that sits a their boundary.\n",
    "\n",
    "So now we know that this middle branch in the code meets both the lower and the upper branches of the code at exactly the same values at its boundaries, and in between them the use of the $ x^2 $ term (`pow()` in the code) provides a curve which transitions between the two.\n",
    "\n",
    "#### Level is above threshold\n",
    "\n",
    "If the level isn't way below the threshold, and isn't in the transition covered by the knee, then it must be far enough above the threshold to have the full compression ratio applied.\n",
    "\n",
    "The maths here is relatively simple, we know the level is above the threshold so we get that much for free, then we add to that everything above the threshold after it has been divided by the ratio.\n",
    "\n",
    "#### Plotting the gain computer\n",
    "\n",
    "Now that we know how the gain computer works, lets plot it's output to get a better intuition for how it works in practice."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "1ea18e84d6f146aea8e2e338bc506037",
       "version_major": 2,
       "version_minor": 0
      },
      "text/html": [
       "<p>Failed to display Jupyter Widget of type <code>interactive</code>.</p>\n",
       "<p>\n",
       "  If you're reading this message in the Jupyter Notebook or JupyterLab Notebook, it may mean\n",
       "  that the widgets JavaScript is still loading. If this message persists, it\n",
       "  likely means that the widgets JavaScript library is either not installed or\n",
       "  not enabled. See the <a href=\"https://ipywidgets.readthedocs.io/en/stable/user_install.html\">Jupyter\n",
       "  Widgets Documentation</a> for setup instructions.\n",
       "</p>\n",
       "<p>\n",
       "  If you're reading this message in another frontend (for example, a static\n",
       "  rendering on GitHub or <a href=\"https://nbviewer.jupyter.org/\">NBViewer</a>),\n",
       "  it may mean that your frontend doesn't currently support widgets.\n",
       "</p>\n"
      ],
      "text/plain": [
       "interactive(children=(IntSlider(value=-10, description='thresholddB', max=0, min=-20, step=2), IntSlider(value=4, description='ratio', max=8, min=1), IntSlider(value=5, description='kneeWidth', max=10, min=1), Output()), _dom_classes=('widget-interact',))"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "@interact(thresholddB=(-20, 0, 2), ratio=(1, 8, 1), kneeWidth=(1, 10, 1))\n",
    "def plotGainComputer(thresholddB, ratio, kneeWidth):\n",
    "    \"\"\"\n",
    "    Feeds a range of values from -100dB to 0dB to the gain computer and plots the output.\n",
    "    \"\"\"\n",
    "    \n",
    "    # Generate the input values\n",
    "    inputValues = np.linspace(0, 1, 50)\n",
    "    \n",
    "    # Plot the input values\n",
    "    plt.figure(figsize=(6, 4))\n",
    "    plt.plot(inputValues, inputValues, label=\"Input\")\n",
    "    \n",
    "    # Process the input\n",
    "    inputValuesdB = convertTodB(inputValues)\n",
    "    gainValuesdB = gainComputer(inputValuesdB, thresholddB, ratio, kneeWidth)\n",
    "    gainValues = convertToLinear(gainValuesdB)\n",
    "\n",
    "    # Plot the gain values\n",
    "    plt.plot(inputValues, gainValues, label=\"Gain\")\n",
    "\n",
    "    # Configure the plot\n",
    "    plt.xlim(left=0, right=1)\n",
    "    plt.ylim(bottom=0, top=1)\n",
    "    plt.xlabel(\"Input level\")\n",
    "    plt.ylabel(\"Output level\")\n",
    "    plt.legend(loc='upper left')\n",
    "\n",
    "    plt.show()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As expected we can see that for input levels far below the threshold the output matches the input exactly, at input levels far above the threshold the full compression ratio is applied, and the knee provides a smooth transition between the two.\n",
    "\n",
    "### Putting it together\n",
    "\n",
    "We've now seen all the major components of a compressor individually, so it's time to look at how they are connected and work together. Below we can see a simple implemenation which runs through the feedforward architecture we described before:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "metadata": {},
   "outputs": [],
   "source": [
    "def simpleCompressor(inputSignal, attack, release, thresholddB, ratio, kneeWidth):\n",
    "    # Rectify the signal using abs()\n",
    "    absBuffer = abs(inputSignal)\n",
    "    \n",
    "    # Level detector\n",
    "    detectorOutput = decoupledPeakLevelDetector(absBuffer, attack, release)\n",
    "    \n",
    "    # Convert to dB\n",
    "    dbOutput = convertTodB(detectorOutput)\n",
    "    \n",
    "    # Gain computer\n",
    "    gainComputerOutput = gainComputer(dbOutput, thresholddB, ratio, kneeWidth)\n",
    "    \n",
    "    # Subtract gain computer input from its output\n",
    "    differenceOutput = gainComputerOutput - dbOutput\n",
    "    \n",
    "    # Convert back to linear\n",
    "    linearOutput = convertToLinear(differenceOutput)\n",
    "    \n",
    "    # Apply the gain\n",
    "    outputBuffer = inputSignal * linearOutput\n",
    "    \n",
    "    return linearOutput, outputBuffer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Most of this should make sense from the comments labelling each step, but one noteworthy step is that which subtracts the input to the gain computer from its output.\n",
    "\n",
    "This is an important step which, after converting back to a linear value, actually provides us with a number smaller than or equal to one by which we can multiply the original input signal. If it's not clear why this works, remember that the gain computer outputs a value which will be smaller than or equal to the output from the level detector.\n",
    "\n",
    "It doesn't actually matter what this value is in absolute terms, but rather how much smaller it is than the original input to the gain computer. Also note that when the input and output of the gain computer is the same, this subtraction will cancel out and give us a value of 0dB, which when converted to linear is 1 - this should make sense because if the input and output is the same then there has been no gain reduction.\n",
    "\n",
    "There is however a small problem with this design - when in the release phase, rather than falling smoothly back to a lower level, the release falls rather sharply and then stops when it reaches the level of the input signal.\n",
    "\n",
    "This can be resolved by rearranging some of the components, such that the level detector is after both the conversion to decibels, and also the gain computer:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "metadata": {},
   "outputs": [],
   "source": [
    "def logDomainCompressor(inputSignal, attack, release, thresholddB, ratio, kneeWidth):\n",
    "    # Rectify the signal using abs()\n",
    "    absBuffer = abs(inputSignal)\n",
    "    \n",
    "    # Convert to dB\n",
    "    dbOutput = convertTodB(absBuffer)\n",
    "    \n",
    "    # Gain computer\n",
    "    gainComputerOutput = gainComputer(dbOutput, thresholddB, ratio, kneeWidth)\n",
    "    \n",
    "    # Subtract the gain computer output\n",
    "    differenceOutput = dbOutput - gainComputerOutput\n",
    "    \n",
    "    # Level detector\n",
    "    detectorOutput = decoupledPeakLevelDetector(differenceOutput, attack, release)\n",
    "    \n",
    "    # Convert back to linear\n",
    "    linearOutput = convertToLinear(-detectorOutput)\n",
    "    \n",
    "    # Apply the gain\n",
    "    outputBuffer = inputSignal * linearOutput\n",
    "    \n",
    "    return linearOutput, outputBuffer"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This is our final compressor design for this notebook. To summarise all the pieces we've put together: this design provides decoupled attack and release parameters, a knee parameter, and smooth transitions from attack to release.\n",
    "\n",
    "Now let's compare it to the previous design by plotting their outputs after processing a simple test signal:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "metadata": {},
   "outputs": [
    {
     "data": {
      "application/vnd.jupyter.widget-view+json": {
       "model_id": "53209633d579451aab4883c06cd45459",
       "version_major": 2,
       "version_minor": 0
      },
      "text/html": [
       "<p>Failed to display Jupyter Widget of type <code>interactive</code>.</p>\n",
       "<p>\n",
       "  If you're reading this message in the Jupyter Notebook or JupyterLab Notebook, it may mean\n",
       "  that the widgets JavaScript is still loading. If this message persists, it\n",
       "  likely means that the widgets JavaScript library is either not installed or\n",
       "  not enabled. See the <a href=\"https://ipywidgets.readthedocs.io/en/stable/user_install.html\">Jupyter\n",
       "  Widgets Documentation</a> for setup instructions.\n",
       "</p>\n",
       "<p>\n",
       "  If you're reading this message in another frontend (for example, a static\n",
       "  rendering on GitHub or <a href=\"https://nbviewer.jupyter.org/\">NBViewer</a>),\n",
       "  it may mean that your frontend doesn't currently support widgets.\n",
       "</p>\n"
      ],
      "text/plain": [
       "interactive(children=(FloatSlider(value=0.55, description='attack', max=1.0, min=0.1, step=0.05), FloatSlider(value=0.75, description='release', max=1.0, min=0.5, step=0.05), IntSlider(value=-30, description='thresholddB', max=0, min=-60, step=5), IntSlider(value=4, description='ratio', max=8, min=1), IntSlider(value=5, description='kneeWidth', max=10), Checkbox(value=True, description='showSimpleGain'), Checkbox(value=True, description='showSimpleOutput'), Checkbox(value=True, description='showLogGain'), Checkbox(value=True, description='showLogOutput'), Output()), _dom_classes=('widget-interact',))"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "@interact(attack=(0.1, 1, 0.05), release=(0.5, 1, 0.05), thresholddB=(-60, 0, 5), ratio=(1, 8, 1), kneeWidth=(0, 10, 1), showSimpleGain=True, showSimpleOutput=True, showLogGain=True, showLogOutput=True)\n",
    "def plotCompressor(attack, release, thresholddB, ratio, kneeWidth, showSimpleGain, showSimpleOutput, showLogGain, showLogOutput):\n",
    "    \"\"\"\n",
    "    Feeds a sine wave impluse to both compressor designs and plots the outputs.\n",
    "    \"\"\"\n",
    "    \n",
    "    # Generate the input signal\n",
    "    signalBuffer = sineWaveDecay(3000)\n",
    "\n",
    "    # Plot the input signal\n",
    "    plt.figure(figsize=(15, 4))\n",
    "    plt.plot(SAMPLE_RANGE, signalBuffer, label=\"Input\")\n",
    "    \n",
    "    # Plot the simple compressor\n",
    "    simpleCompGain, simpleCompOutput = simpleCompressor(signalBuffer, attack, release, thresholddB, ratio, kneeWidth)\n",
    "    \n",
    "    if showSimpleGain:\n",
    "        plt.plot(SAMPLE_RANGE, simpleCompGain, label=f\"Simple Compressor Gain\")\n",
    "    \n",
    "    if showSimpleOutput:\n",
    "        plt.plot(SAMPLE_RANGE, simpleCompOutput, label=f\"Simple Compressor Output\")\n",
    "    \n",
    "    # Plot the log domain compressor \n",
    "    logCompGain, logCompOutput = logDomainCompressor(signalBuffer, attack, release, thresholddB, ratio, kneeWidth)\n",
    "    \n",
    "    if showLogGain:\n",
    "        plt.plot(SAMPLE_RANGE, logCompGain, label=f\"Log Compressor Gain\")\n",
    "    \n",
    "    if showLogOutput:\n",
    "        plt.plot(SAMPLE_RANGE, logCompOutput, label=f\"Log Compressor Output\")\n",
    "\n",
    "    # Configure the plot\n",
    "    plt.xlabel(\"Samples\")\n",
    "    plt.ylabel(\"Displacement\")\n",
    "    plt.legend(loc='upper left')\n",
    "\n",
    "    plt.show()\n",
    "    "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "As you can see, the gain reduction applied by the log domain compressor starts its attack slightly ahead of the simple compressor, and its release is initially a little faster but has a much smoother tail. This gives it a more natural sound with less distortion of the input signal.\n",
    "\n",
    "Now that we've reached the end of the notebook I really recommend adjusting some of the parameters and watching how the shape of the gain reduction curves change, this should provide a better intuition of how these two algorithms are performing.\n",
    "\n",
    "You may also wish to make some of your own adjustments to the code and run the cells again to see how the behaviour changes, or add a few extra plot() or print() statements to learn more about particular parts of the code.\n",
    "\n",
    "## Conclusion\n",
    "\n",
    "In this notebook we have seen how compressors are used and how they can be implemented using a few mathematical concepts that I hope now make sense. The reasoning behind a few of the common design desisions and their impacts on the performance of a compressor should also now be a little clearer.\n",
    "\n",
    "The log domain compressor implementation demonstrated here is not necessarily the best design, as there are plenty of other approaches which have their own performance characteristics that may suit your use case better. It does however provide a reasonable starting point for a first implementation, and may do just fine depending on the goals of your project.\n",
    "\n",
    "If you are looking for further ideas to study in this domain I would recommend looking into a few of the other compressor based devices that were mentioned earlier in this notebook, and also having a look through some of the further reading resources listed below. There is also a whole world of analogue modelling which is often applied to digital compressors which maybe of interest.\n",
    "\n",
    "## Further Reading\n",
    "\n",
    "Below are several resources that I found useful while researching this notebook. If you wish to read more about this topic, these may be good places to start.\n",
    "\n",
    "### Texts\n",
    "\n",
    "[Dynamic Range Compression](https://en.wikipedia.org/wiki/Dynamic_range_compression)  \n",
    "[Teletronix LA2A - History and How it Works](https://recording.org/threads/teletronix-la2a-history-and-how-it-works.58172)  \n",
    "[Digital Dynamic Range Compressor Design—A Tutorial and Analysis](https://www.researchgate.net/publication/277772168_Digital_Dynamic_Range_Compressor_Design-A_Tutorial_and_Analysis)  \n",
    "\n",
    "### Videos\n",
    "\n",
    "[How To Use A Compressor Pedal](https://www.youtube.com/watch?v=j4NrWQljyso)  "
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.6.2"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}