{ "cells": [ { "cell_type": "markdown", "metadata": {}, "source": [ "# Generating Simple Audio Signals\n", "\n", "[back to main page](index.ipynb)\n", "\n", "We create a simple sine wave as an introductory example using Python and NumPy, using a Jupyter/IPython notebook.\n", "\n", "Let's start very simple. We create ~~three~~ four numbers and give each of them a name.\n", "\n", "> Sometimes these are called *variables*, but that is actually misleading.\n", "> Think about objects and names. An object is created (in our case a number) and we specify a name by which we want to access this object." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "dur = 1.5 # duration in seconds\n", "amp = 0.3 # amplitude (full scale: +-1.0)\n", "freq = 440. # frequency in Hertz\n", "fs = 44100 # sampling frequency in Hertz" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Everything following a `#` sign is a comment.\n", "You don't have to comment everything, but sometimes it helps other people (and future you) to understand what you did in your code.\n", "\n", "There is no output. If you want to see which object a certain name refers to, just type the name:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "dur" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "In Python, *everything* is an object. And every object has a *type*. Let's see ..." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "type(dur), type(amp), type(freq), type(fs)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Note that we didn't specify any types explicitly, we just got Python's default types. Numbers with a comma are by default of type `float`, numbers without comma are of type `int`.\n", "\n", "There are many more built-in types in Python (strings, tuples, lists, dictionaries, ...), but let's ignore them for now.\n", "If you *really* want to know more, you can have a look at my [Introduction to Python](intro-python.ipynb).\n", "\n", "If you want an overview about all the objects you have defined up to now, use `%who` or its more verbose cousin `%whos`." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "%whos" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now, let's bring NumPy into the game. The canonical way to do that is" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import numpy as np" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "With this, we'll have to prepend \"`np.`\" to all NumPy functions, types etc.\n", "\n", "Now let's create the most basic signal, a sine. This is kind of the \"Hello, world!\" of signals.\n", "\n", "In order to create a sine tone, we need first a series of time instances to represent our sampling times. The distance between those instances is the *sampling interval* $\\tau = \\frac{1}{f_s}$, where $f_s$ is the *sampling frequency*.\n", "\n", "To create a series of regularly ascending (or descending) values, NumPy provides the function [numpy.arange()](http://docs.scipy.org/doc/numpy/reference/generated/numpy.arange.html). Let's use that." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "t = np.arange(np.ceil(dur * fs)) / fs\n", "t" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As you can see, this creates an array of numbers from 0 to just below the value specified in `dur`. These are a lot of numbers, so to avoid flooding us with heaps of useless output, IPython just shows the first and last few values. Very handy.\n", "\n", "> Note that in Python 2 and before, the division operator works a little differently then in Python 3. Here we assume we're using the latter, where the division of two `int`s returns a `float` value (and not an `int` with the truncated result!).\n", "> To make sure this also works as expected in Python 2, you can convert one operand to `float` before the division or use a special `import` statement:\n", ">\n", "> ```python\n", "> 1. / fs\n", "> ```\n", ">\n", "> or\n", ">\n", "> ```python\n", "> 1 / float(fs)\n", "> ```\n", ">\n", "> or\n", ">\n", "> ```python\n", "> from __future__ import division\n", "> 1 / fs\n", "> ```\n", "\n", "If you want to get help about `np.arange()` (or any other function/object), just write its name (without the parentheses) followed (or preceded) by a question mark:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "np.arange?" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This will open a help screen at the bottom of your browser window with an explanation of all parameters and with a few usage examples.\n", "\n", "Now let's check the type of `t`." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "type(t)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The `ndarray` is the single most important type of NumPy. It can handle arrays with an arbitrary number of dimensions. All values stored in an `ndarray` have the same data type. This makes most operations on them faster then on Python's built-in `list`s.\n", "\n", "Let's get some information about our brand new array named `t`." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "len(t), t.dtype, t.ndim" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "By default, NumPy stores floating point numbers as `float64`, i.e. each number using 64 bits. This is sometimes called *double precision*. If you want *single precision*, you can use `float32`. The length of our array can be obtained with the built-in `len()` function and `t.ndim` shows how many dimensions the array has. This one has only one. Boring.\n", "\n", "Now that we have our time instances, we can compute the sine for each of them, according to the equation\n", "\n", "$$x(t) = A\\sin(\\omega t),$$\n", "\n", "where $A$ is the amplitude, $\\omega = 2\\pi f$ and $f$ is the desired frequency of the resulting sine tone." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "sig = amp * np.sin(2 * np.pi * freq * t)\n", "sig" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Note that we didn't have to explicitly loop over the array elements. Most NumPy functions - including `np.sin()` - work element-wise. If an array is multiplied by a scalar, the multiplication is also applied element-wise.\n", "\n", "> This is called \"broadcasting\", but more about that later ...\n", "\n", "To check if this actually worked, we plot the signal, but first we'll set up inline plotting." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "%matplotlib inline\n", "import matplotlib.pyplot as plt" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "plt.plot(sig)\n", "plt.ylim(-1.1, 1.1);" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Hmmm ... maybe we recognize something if we only plot the first 200 values." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "plt.plot(sig[:200])\n", "plt.xlabel(\"time / samples\")\n", "plt.ylim(-1.1, 1.1);" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Better.\n", "\n", "If we want to show the time in milliseconds instead of samples, we have to specify the time instances:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "plt.plot(t[:200] * 1000, sig[:200])\n", "plt.title(\"sine tone\")\n", "plt.xlabel(\"time / milliseconds\")\n", "plt.ylim(-1.1, 1.1);" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Now that we can *see* our signal, wouldn't it also be nice to hear it?\n", "\n", "There are several 3rd-party libraries for Python that allow audio playback, let's try one of them: the [sounddevice](http://python-sounddevice.rtfd.org/) module.\n", "\n", "Follow the [installation instructions](http://python-sounddevice.rtfd.org/#Installation), then re-start the IPython kernel and re-evaluate this notebook (with the menu commands \"Kernel\" $\\to$ \"Restart\" and \"Cell\" $\\to$ \"Run All Above\") and continue here:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "import sounddevice as sd" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "sd.play(sig, fs)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Did it work? No?\n", "\n", "Don't despair, if you can't play the signal directly, you can save it to a sound file and play that in an external sound file player.\n", "I've written a separate [description how to read and write audio files in Python](audio-files/index.ipynb), have a look there.\n", "\n", "OK, now we know how to create a *mono* signal, but what about *stereo*?\n", "\n", "For now, we were using one-dimensional arrays, but for stereo signals we need two-dimensional arrays.\n", "The 2 channels can be either stored as rows or as columns of such a two-dimensional array.\n", "Both ways are possible, but it's more common to store the channels as columns.\n", "\n", "Let's create two sine signals with different frequencies, one on the left channel and one on the right.\n", "\n", "There are several possibilities:\n", "\n", "1. Create two separate mono signals like above, and combine them with [numpy.column_stack()](http://docs.scipy.org/doc/numpy/reference/generated/numpy.column_stack.html)\n", "\n", "1. Duplicate the time array `t` and the array with the two frequencies with [numpy.tile()](http://docs.scipy.org/doc/numpy/reference/generated/numpy.tile.html) and use those larger two-dimensional arrays in the calculations (this is not recommended)\n", "\n", "1. Use [broadcasting](http://docs.scipy.org/doc/numpy/user/basics.broadcasting.html) and do everything at once\n", "\n", "1. For sure, there are more ways to do this ...\n", "\n", "In this case, let's use *broadcasting*!\n", "\n", "This means that we use arrays of different (but compatible) shapes in our calculations and the singular dimensions are internally repeated.\n", "This sounds complicated, let's just see it in an example.\n", "\n", "Remember our time array `t`?" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "t" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "This array is one-dimensional (note that there is only one pair of brackets).\n", "\n", "To be completely obvious, we could also check the number of dimensions explicitly:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "t.ndim" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "But we can re-shape it, for example into a two-dimensional array with one column.\n", "We can specify the concrete shape, or we can set one component to `-1`, which means this dimension is determined automatically, based on the given data." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "t.reshape(-1, 1)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "The result is two-dimensional (note the two levels of brackets!).\n", "\n", "Let's now create an array for our two frequencies." ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "freq = np.array([500, 600])\n", "freq" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "As you can see, this two-element array is one-dimensional.\n", "\n", "The interesting part comes when we multiply those two arrays:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "freq * t.reshape(-1, 1)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Wow, the result is a two-dimensional array with two columns!\n", "The left column holds the time array element-wise multiplied with the left frequency, the right column used the right frequency value for multiplication.\n", "\n", "Isn't this great?\n", "Now we can use this for creating our *stereo* sine signal:" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "sig = amp * np.sin(2 * np.pi * freq * t.reshape(-1, 1))\n", "sig" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Again, we have an array with two columns, one for each channel.\n", "\n", "The plt.plot() function can handle two-dimensional arrays and just plots each column with a new color. How convenient!" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "plt.plot(sig[:200])\n", "plt.ylim(-1.1, 1.1);" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "Of course we can again plot the time in milliseconds.\n", "And let's add a legend in order to distinguish the two signals!" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "plt.plot(t[:200] * 1000, sig[:200])\n", "plt.title(\"stereo sine\")\n", "plt.xlabel(\"time / milliseconds\")\n", "plt.legend([\"left\", \"right\"])\n", "plt.ylim(-1.1, 1.1);" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "If you want to know more about plotting, have a look at my [pages about plotting](plotting/index.ipynb), especially the [matplotlib intro](plotting/matplotlib.ipynb).\n", "\n", "Like before, you can play back the signal, but this time in stereo, hooray!" ] }, { "cell_type": "code", "execution_count": null, "metadata": {}, "outputs": [], "source": [ "sd.play(sig, fs)" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "That's it for this little example, if you want to know more, go back to the [main page](index.ipynb) and dive in!\n", "\n", "Have fun!" ] }, { "cell_type": "markdown", "metadata": {}, "source": [ "

\n", " \n", " \"CC0\"\n", " \n", "
\n", " To the extent possible under law,\n", " the person who associated CC0\n", " with this work has waived all copyright and related or neighboring\n", " rights to this work.\n", "

" ] } ], "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.5.1+" } }, "nbformat": 4, "nbformat_minor": 0 }