dsp-theory: digital signal processing taught as Jupyter notebooks

Sixteen lectures, and a deliberate dual purpose

The repository presents lectures on digital signal processing as Jupyter notebooks in Python, and it makes two claims about what they are for. You can treat them as a complete course on digital signal processing, or you can use them as notes on the theoretical aspects and the practical application of the subject to various problems.

That dual framing is the reason the repository is worth reading rather than running. A course has an order and an argument, and the sixteen notebooks build on each other: the Z-transform in the first lecture becomes the tool for filter design later, and the spectrum analysis in the ninth becomes the input to the filter banks in the eleventh. Reading them out of order gives you formulas; reading them in order gives you the way of thinking.

The primary language in the repository listing is Jupyter Notebook, which tells you where the content lives. The src/ directory holds the notebooks themselves, and the repository also has audio/ for sound samples, img/ for figures, pdf/ for exported versions, a convert.sh script and a Dockerfile.

The content is in Russian, and the README links the list of lectures in Russian, with each notebook linked to its nbviewer rendering. There is also an English README, and a Habr post about the course for readers who want a written version of the whole thing.

The licence is GNU GPL 3.0, and the first release is dated 2019/07/10.

The order: from signals to wavelets

The lecture list is the syllabus, and it is worth reading in order because the sequence is a coherent course in the subject.

Lecture 1 is signals, analog, discrete and digital, together with the Z-transform. Lecture 2 is the Fourier transform, the amplitude and phase spectrum of a signal, the DFT and the FFT. Lecture 3 covers convolution and correlation, with linear and circular convolution and fast convolution. Lecture 4 is random processes, white noise and the probability density function.

Lecture 5 moves to deterministic signals and modulation, with AM, FM and chirp, and manipulation. Lecture 6 is filtering, IIR and FIR. Lecture 7 is windowed filtering and the detection of weak signals using a window. Lecture 8 is resampling by decimation and interpolation, with CIC filters and moving average filters.

Lecture 9 is non-parametric spectral analysis, using Welch's method. Lecture 10 is polyphase Fourier transform schemes, averaging over frequency and over time. Lecture 11 is filter banks in audio coding tasks. Lecture 12 is Farrow filters. Lecture 13 is mel-spectrograms. Lecture 14 is the cepstrum and MFCC. Lecture 15 is the wavelet transform. Lecture 16 is the Goertzel algorithm.

The shape of that arc is worth noticing. The first ten lectures are the classical signal theory and estimation material, and the last six are the spectral tools that speech and audio work is actually built on. A reader who already knows the transforms and wants the practical spectral methods can jump to lecture 9, and a reader coming from audio will find the mel-spectrogram and MFCC lectures sit at the end where they make sense.

Where the material came from

The provenance is stated in the README, and it explains a lot about the character of the notebooks.

The main information comes from the author's own lectures, which he taught to students at the Moscow Power Engineering Institute, and the same material was used in training workshops at the Centre of Modern Electronics. The lectures contain translations of various articles, a compilation of materials from reliable sources and literature on digital signal processing, and the official documentation for the applied Python libraries.

That last item is the one to note. A notebook that teaches DSP through numpy, scipy, librosa, matplotlib and seaborn is partly a course in the libraries, and the project is candid that the official library documentation is one of its sources.

Some lectures were written with the author's good friends and colleagues, and they are thanked for it individually. The author list in the README names five people, Alexander Kapitanov as @hukenovs, Vladimir Fadeev as @kirlf, Karina Kvanchiani as @karinakvanchiani, Elizaveta Petrova as @kleinsbotle and Andrei Makhliarchuk as @anotherhelloworld, which is a fairly large team for a course repository and suggests the lectures are collaborative rather than the work of one person.

For a reader, this is the difference between a set of blog posts and a course with a syllabus, notes and exercises. The tags on the repository reflect the same breadth, with lectures, numpy, scipy, tutorial, fpga and the filter and transform names all present.

Pinned dependencies from 2022 are the real constraint

The requirements file is fully pinned, which is good practice for reproducible notebooks and a problem for anyone on a current Python.

The list is numpy 1.24.1, scipy 1.10.0, matplotlib 3.6.3, seaborn 0.12.2, jupyter 1.0.0, nbmerge 0.0.4, nbformat 5.7.3, nbconvert 7.2.9, librosa 0.9.2, opencv-python 4.8.1.78, PyWavelets 1.4.1, tabulate 0.9.0 and traitlets 5.1.1.

The scientific stack is coherent for the material. scipy and numpy do the filtering and transforms, librosa covers the audio analysis that lectures 11 to 14 need, PyWavelets backs the wavelet lecture, and opencv-python is there for image processing work. The Jupyter tooling, nbmerge, nbformat and nbconvert, is not there for the lectures at all, it is there for the export pipeline described later.

The versions matter. These releases are several years old, and several of them predate the Python versions most people have installed. numpy 1.24.1 and scipy 1.10.0 in particular do not build against the newest Python interpreters without friction, and librosa 0.9.2 is old enough that its dependency chain has moved underneath it. The Dockerfile makes the same choice, basing the image on python:3.9.

So the honest position is that this repository wants a Python 3.9 environment, which is exactly what the installation instructions create. Trying to run it on a modern interpreter is a fight you can have, but it is not what the project is set up for.

Setting up the environment, and the scaleogram exception

The installation instructions assume conda and a virtual environment, and the sequence is four commands.

# Create the environment and install the required libraries
conda create -n "dsp_venv" python=3.9 -y
conda activate dsp_venv
pip install -r requirements.txt
# Start the jupyter notebook server and follow the link from the console
jupyter notebook

The environment name, dsp_venv, and the pinned python=3.9 in the create command are the parts to copy exactly, for the version reasons just described. The rest of the documented setup is to install miniconda, create and activate a virtual environment, install the libraries from requirements.txt, and run the notebooks through a Jupyter server or through JetBrains DataSpell.

One lecture needs something extra. For lecture 15, the wavelet transform, the scaleogram library has to be installed separately, and it is not on PyPI in a modern form, so the documented route is to clone and install it locally:

# Clone the repository
git clone http://github.com/alsauve/scaleogram
cd scaleogram
# Install the library
python ./setup.py install --user

The setup.py install invocation is old style, but that is the procedure the project documents.

Running the notebooks through a Jupyter server rather than in an editor is the default path, and the notebooks are also linked to nbviewer, which means you can read any of them in the browser without installing anything at all if you only want to read.

A Docker image for the course, and exporting to HTML or PDF

The Dockerfile is a convenience for people who would rather not manage a conda environment, and it is written in the file as a comment block showing both the build and the run command.

The image is based on python:3.9 and installs the pinned requirements with pip install -r /tmp/requirements.txt -U, copies the repository into a work directory, exposes port 8888, and runs jupyter notebook with --port 8888 --no-browser --ip 0.0.0.0 --allow-root. The build command is docker build -t dsp-app . and the run command is docker run --rm --name my-app -it -p 8888:8888 dsp-app.

The --ip 0.0.0.0 and --allow-root combination is what makes the container reachable from outside the container, which is the point of mapping port 8888, but it is also worth noting for anyone running it on a shared machine. The image has a label recording the source repository, which is a small touch that makes an image like this identifiable later.

The export pipeline is separate and lives in convert.sh, the script for converting the notebooks to HTML format. It may need nbmerge, nbformat and nbconvert, which are the three Jupyter packages in the requirements file that are not used by the lectures themselves. For PDF conversion, pandoc may be required.

The pdf/ directory in the repository tree suggests the exported material is committed as well, so there is a static copy of the course for anyone who does not want to run a notebook server at all.

Maintenance state and what the notebooks are not

The repository is not archived, the last push was on 2026-04-21, and there are no GitHub releases. The README records the first release as 2019/07/10, so this is a project with a long history and a low recent cadence.

Nothing in the repository suggests that is a problem. A course in digital signal processing is not software with dependencies to chase; the mathematics does not change, and the notebooks are readable in the nbviewer links without any installation. The pinned dependency set is what would need attention if the maintainer returned to it, and the effort involved in moving numpy, scipy and librosa forward is a couple of hours of version churn rather than a redesign.

It is also worth being clear about what this repository is not. There is no importable Python package here, no API and nothing to add to a requirements file. The unit of value is the notebook, and the way to consume it is to read it or run it, not to depend on it.

The documentation for the course is distributed in three ways, which is a sensible structure for a teaching resource. The notebooks themselves are in the repository, the rendered versions are on nbviewer, and there is a Habr post that presents the course as a single written piece for readers who prefer prose to notebooks.

If you are picking this up as a self-study course, the ordering in the README is the plan, the pinned environment is the setup, and the exported PDF in the pdf/ directory is the fallback for when you want to read rather than run.

Editorial conclusion

Adopt dsp-theory if you want to learn DSP from worked notebooks that combine the derivation with the plotting, and if you are comfortable with a dependency set frozen in 2022 and a Python 3.9 environment. Do not adopt it as a dependency for a production pipeline, because the versions are pinned to releases that predate current Python and NumPy, and treat the notebooks as a course rather than a library, since there is no importable module here. Before you start, build the environment exactly as documented with Python 3.9, expect to install scaleogram separately for the wavelet lecture, and read the notebook outputs rather than only the code, since the commentary is where the derivations live.

Frequently asked questions

Official sources

1. hukenovs/dsp-theory on GitHub
2. Issues
3. License: GPL-3.0
4. README