Merge branch 'master' of github.com:ideoforms/signalflow into docs/ex…

…amples
ideoforms · Dec 5, 2023 · 4625381 · 4625381
2 parents 0063a00 + 0d4f101
commit 4625381
Show file tree

Hide file tree

Showing 318 changed files with 2,241 additions and 4,406 deletions.
diff --git a/.clang-format b/.clang-format
@@ -1,12 +1,5 @@
 #------------------------------------------------------------------------
-#
-#  clang-format.yml
-#
-#  Chirp house style for C code.
-#
-#  Copyright © 2011-2016, Asio Ltd.
-#  All rights reserved.
-#
+# Code formatting rules for SignalFlow
 #------------------------------------------------------------------------
 ---
 BasedOnStyle: WebKit

diff --git a/.gitattributes b/.gitattributes
@@ -1,5 +1,12 @@
-# To set up clang-format filter:
-# git config --global filter.clang-format.clean clang-format
-# git config --global filter.clang-format.smudge cat
+#--------------------------------------------------------------------------------
+# Configure clean and smudge filters to apply when checking code in and out
+# of git respectively.
+#
+# To use these rules, the clang-format filter must be first be set up adding 
+# to .gitconfig:
+#
+#   git config --global filter.clang-format.clean clang-format
+#   git config --global filter.clang-format.smudge cat
+#--------------------------------------------------------------------------------
 *.cpp filter=clang-format
 *.h filter=clang-format
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -12,11 +12,10 @@ jobs:
         sudo rm -rf /home/linuxbrew
         sudo apt-get update -y
         sudo apt-get install libasound2-dev libsoundio-dev libsndfile1-dev fftw3-dev -y
-        sudo apt-get install python3 python3-setuptools python3-pip python3-numpy 
-        # annoyingly seems like GitHub Actions as of 30 May 2023 will attempt to install
-        # numpy 1.25.0rc1 on Python 3.8, even though it requires Python 3.9+.
-        # specify particular version here as a workaround.
-        sudo pip3 install pytest numpy==1.22.0 scipy==1.10.0
+        sudo apt-get install python3 python3-setuptools python3-pip 
+        # Requires setuptools >= 62.1 for `python setup.py test`, as earlier versions
+        # used a different build path to the .so file as located in tests/__init__.py
+        sudo pip3 install -U pytest numpy scipy setuptools>=62.1.0
     - name: Configure
       run: mkdir build && cd build && cmake ..
     - name: Make

diff --git a/.github_changelog_generator b/.github_changelog_generator
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -1,30 +1,127 @@
 # Contributing
 
-## Creating a new Node
+- [Building from source](#building-from-source)
+- [Creating a new Node](#creating-a-new-node)
+- [Test](#test)
+- [Release](#release)
+- [Documentation](#documentation)
 
-- Create the .h header file in the appropriate subdirectory of `source/include/signal/node`
-- Create the .cpp source file in the appropriate subdirectory of `source/src/node`
-- Add the header file to `source/include/signalflow/signalflow.h`
-- Add the source file to `source/src/CMakeLists.txt`
-- Regenerate the auto-generated Python bindings: `auxiliary/scripts/generate-node-python-bindings.py > source/src/python/nodes.cpp`
-- Add unit tests to the appropriate test script in `tests`
-- Re-run the tests: `python3 setup.py test`
-- Update the stubs (see below)
+## Building from source
+
+Building from source assumes that you have a working installation of Python 3, ideally within a virtual environment.
+
+<details>
+<summary>Building from source: <b>macOS</b></summary>
+
+### macOS
+
+To build on macOS from source, install dependencies with Homebrew:
+```
+brew install cmake libsndfile libsoundio
+```
+
+Clone this repository, then build and install with `pip`:
+```
+pip3 install .
+```
+</details>
+
+<details>
+<summary>Building from source: <b>Linux, Raspberry Pi</b></summary>
+
+### Linux, Raspberry Pi
+
+SignalFlow supports Linux (verified on Ubuntu 20.04 and Raspberry Pi OS buster) with alsa and pulseaudio backends.
+
+#### Via pip
+
+Installation via pip is supported for Linux x86_64. To install:
+
+```
+pip3 install signalflow
+```
+
+That's it! To test that it is installed successfully, play a test tone by running: `signalflow test`.
 
-## Build: C++
+If installation does not succeed, follow the instructions for building from source below.
 
-To build with debug symbols:
+#### From source
+
+To build the Python library from source on Linux, install dependencies with apt:
 ```
-cmake -DCMAKE_BUILD_TYPE=Debug ..
+apt-get install -y git cmake g++ python3-pip libasound2-dev libsndfile1-dev libsoundio-dev fftw3-dev
 ```
 
-## Build: Python
+If you experience an error on Raspberry Pi `libf77blas.so.3: cannot open shared object file`:
+
+```
+sudo apt-get install -y libatlas-base-dev
+```
+
+Clone this repository, then build and install with `pip`:
+```
+pip3 install .
+```
+
+</details>
+
+<details>
+<summary>Building from source: <b>Windows</b></summary>
+
+### Windows
+
+This is work in progress.
+
+Currently, dependencies need to be downloaded and built by hand. These can be placed anywhere.
+
+- https://github.com/timmb/libsoundio - check out the `fix-msvc` branch.
+  - Use CMake GUI to build libsoundio with Visual Studio 2019 with binaries in a subfolder of that repo named `build`. (Configure, Generate, Open project, Batch build all configurations)
+- https://github.com/libsndfile/libsndfile
+  - Use CMake GUI to build libsndfile with Visual Studio 2019 with binaries in a subfolder of that repo named `build`. (Configure, Generate, Open project, Batch build all configurations)
+- Download Windows binaries of FFTW from http://fftw.org/install/windows.html.
+
+To build SignalFlow, use the CMake GUI. Press configure and you will see three empty fields to fill in with the path to the two build folders and the FFTW binaries folder (see above). Set these parameters then press Configure, then Generate then Open. Then build in Visual Studio 2019.
+
+As of 2021-03-03, only the signalflow project has been ported to build correctly on Windows. Only tested in x64 and for Debug builds. Tested using Visual Studio 2019.
+
+</details>
+
+<details>
+<summary>Building from source: <b>Debug symbols</b></summary>
+## Debug symbols
 
 To build the Python libraries with debug symbols:
 ```
 python3 setup.py build --debug install
-# TODO: How to do this with pip?
 ```
+</details>
+
+<details>
+<summary>Building from source: <b>C++ only</b> (no Python layer)</summary>
+
+To build and install the C++ core without the Python binding layer:
+```
+mkdir build
+cd build
+cmake ..
+make -j8
+```
+
+To build with debug symbols, include `-DCMAKE_BUILD_TYPE=Debug` when calling `cmake`.
+
+</details>
+
+
+## Creating a new Node
+
+- Create the .h header file in the appropriate subdirectory of `source/include/signal/node`
+- Create the .cpp source file in the appropriate subdirectory of `source/src/node`
+- Add the header file to `source/include/signalflow/signalflow.h`
+- Add the source file to `source/src/CMakeLists.txt`
+- Regenerate the auto-generated bindings and docs: `auxiliary/scripts/auto-generator.py --library --readme --bindings`
+- Add unit tests to the appropriate test script in `tests`
+- Re-run the tests: `python3 setup.py test`
+- Update the stubs (see below)
 
 ## Test
 
@@ -54,13 +151,17 @@ For each new release:
 To update autogenerated Node documentation:
 
 ```
-auxiliary/scripts/generate-node-python-bindings.py --markdown > docs/library/index.md
+auxiliary/scripts/auto-generator.py --library --readme
 ```
 
-To generate and serve the docs:
+For generating HTML documentation, install `mkdocs` and associated plugins:
 
 ```
 pip3 install mkdocs mkdocs-material mkdocs-include-markdown-plugin mkdocs-git-revision-date-localized-plugin
+```
+
+To serve the HTML documentation locally, on `http://localhost:8000`:
+```
 mkdocs serve
 ```
 

diff --git a/README.md b/README.md
@@ -44,114 +44,24 @@ graph.wait()
 
 SignalFlow requires Python 3.8 or above.
 
-<details>
-<summary>Installation: <b>macOS</b></summary>
+In brief, SignalFlow can be installed with pip: `pip3 install signalflow`.
 
-### macOS
+For complete per-platform instructions and setup guides, see [Installing SignalFlow](https://signalflow.dev/installation/).
 
-Install an up-to-date version of Python 3 using Homebrew ([guide](https://docs.python-guide.org/starting/install3/osx/)): `brew install python3`
-
-Install SignalFlow using `pip`:
-
-```
-pip3 install signalflow
-```
-
-That's it! To test that it is installed successfully, play a test tone by running: `signalflow test` 
-
-#### From source
-
-To build on macOS from source, install dependencies with Homebrew: 
-```
-brew install cmake python libsndfile libsoundio
-```
-
-Clone this repository, then build and install with `pip`:
-```
-pip3 install .
-```
-</details>
-
-<details>
-<summary>Installation: <b>Linux, Raspberry Pi</b></summary>
-
-### Linux, Raspberry Pi
-
-SignalFlow supports Linux (verified on Ubuntu 20.04 and Raspberry Pi OS buster) with alsa and pulseaudio backends.
-
-#### Via pip
-
-Installation via pip is supported for Linux x86_64. To install:
-
-```
-pip3 install signalflow
-```
-
-That's it! To test that it is installed successfully, play a test tone by running: `signalflow test`.
-
-If installation does not succeed, follow the instructions for building from source below. 
-
-#### From source
-
-To build the Python library from source on Linux, install dependencies with apt:
-```
-apt-get install -y git cmake g++ python3-pip libasound2-dev libsndfile1-dev libsoundio-dev fftw3-dev
-```
-
-If you experience an error on Raspberry Pi `libf77blas.so.3: cannot open shared object file`:
-
-```
-sudo apt-get install -y libatlas-base-dev
-```
-
-Clone this repository, then build and install with `pip`:
-```
-pip3 install .
-```
-
-</details>
-
-<details>
-<summary>Installation: <b>Windows</b></summary>
-
-### Windows
-
-This is work in progress.
-
-Currently, dependencies need to be downloaded and built by hand. These can be placed anywhere.
-
-- https://github.com/timmb/libsoundio - check out the `fix-msvc` branch.
-  - Use CMake GUI to build libsoundio with Visual Studio 2019 with binaries in a subfolder of that repo named `build`. (Configure, Generate, Open project, Batch build all configurations)
-- https://github.com/libsndfile/libsndfile
-  - Use CMake GUI to build libsndfile with Visual Studio 2019 with binaries in a subfolder of that repo named `build`. (Configure, Generate, Open project, Batch build all configurations)
-- Download Windows binaries of FFTW from http://fftw.org/install/windows.html.
-
-To build SignalFlow, use the CMake GUI. Press configure and you will see three empty fields to fill in with the path to the two build folders and the FFTW binaries folder (see above). Set these parameters then press Configure, then Generate then Open. Then build in Visual Studio 2019.
-
-As of 2021-03-03, only the signalflow project has been ported to build correctly on Windows. Only tested in x64 and for Debug builds. Tested using Visual Studio 2019.
+## Examples
 
-</details>
+Several example scripts are provided in [examples](examples).
 
-<details>
-<summary>Installation: <b>C++ only</b> (no Python layer)</summary>
+To download the `examples` folder:
 
-To build and install the C++ core without the Python binding layer:
-```
-mkdir build
-cd build
-cmake ..
-make -j8
+```python
+import signalflow_examples
+signalflow_examples.download_examples()
 ```
 
-</details>
-
-## Examples
-
-See [examples](examples) for a number of example scripts.
-
 ## Documentation
 
-More detailed documentation can be found at [signalflow.dev](https://signalflow.dev/). 
+In-depth documentation, including a reference guide to each of the Node classes, can be found at [signalflow.dev](https://signalflow.dev/). 
 
 ## Node classes
 
@@ -170,7 +80,7 @@ The following Node classes are currently included with the base distribution:
 | **Processors: Delays** | AllpassDelay, CombDelay, OneTapDelay, Stutter |
 | **Processors: Distortion** | Resample, SampleAndHold, Squiz, WaveShaper |
 | **Processors: Dynamics** | Compressor, Gate, Maximiser, RMS |
-| **Processors: Filters** | BiquadFilter, EQ, MoogVCF, SVFilter |
+| **Processors: Filters** | BiquadFilter, DCFilter, EQ, MoogVCF, SVFilter |
 | **Processors: Panning** | AzimuthPanner, ChannelPanner, SpatialPanner, StereoBalance, StereoPanner, StereoWidth |
 | **Sequencing** | ClockDivider, Counter, Euclidean, FlipFlop, ImpulseSequence, Index, Latch, Sequence |
 | **Stochastic** | Logistic, PinkNoise, RandomBrownian, RandomChoice, RandomCoin, RandomExponentialDist, RandomExponential, RandomGaussian, RandomImpulseSequence, RandomImpulse, RandomUniform, StochasticNode, WhiteNoise |

diff --git a/auxiliary/docs/HISTORY.md b/auxiliary/docs/HISTORY.md