How ideoforms/signalflow works
Project type and purpose
• SignalFlow is an open-source sound synthesis framework. It exposes a Python API for interactive audio graph construction in Jupyter or scripts, with a high-performance C++11 core engine.
• The README makes clear it provides an AudioGraph of interconnected Nodes, a modular library of synthesis and processing units, Python bindings (pybind11), cross-platform audio I/O, and a pip-installable package.
File structure
• Top-level directories:
• source/ – C++ core engine, split into include/ (public headers) and src/ (implementation), with subtrees for core, node (analysis, buffer, envelope, FFT, IO, operators, oscillators, processors, sequencing, stochastic), patch, and python (pybind11 wrappers).
• auxiliary/ – build helpers, extra Python stub libs, CLI, examples.
• tests/ – Python unit tests exercising the Python API and graph behavior.
• examples/ – Python scripts and Jupyter notebooks for end users.
• docs/ and mkdocs.yml – documentation website content.
• Build/config: CMakeLists.txt for C++ build, setup.py/pyproject.toml/setup.cfg for Python packaging, GitHub Actions workflows in .github/workflows/.
README for additional insights
• The README describes the layered architecture: client scripts → Python API → C++ engine → audio device.
• It lists the Node class library categories, confirming the modular design of nodes (oscillators, filters, envelopes, etc.).
Key components
a. Frontend (Python layer):
• User scripts / Jupyter notebooks (examples/), installed Python package signalflow
• signalflow.python module (pybind11 wrappers)
b. Binding layer:
• pybind11 integration in source/src/python/ → exposes C++ classes and functions to Python
c. Core engine (C++):
• core subsystem: graph scheduler, config, renderer, utilities
• node subsystem: Node registry and each category (analysis, buffer, envelope, FFT, I/O, operators, oscillators, processors, sequencing, stochastic)
• patch subsystem: patch specification and execution
d. External libraries:
• pybind11 (embedded under source/lib/pybind11)
• json11 for JSON parsing (patches)
• miniaudio or dummy audio driver (source/include/signalflow/node/io/…) for cross-platform audio I/O
e. Build & packaging:
• CMake to generate native library (.so/.pyd/.dll)
• setup.py / pyproject.toml to wrap the native library into a Python wheel
• CI workflows for build and wheel publishing
f. Documentation & Examples
• mkdocs-driven docs site (docs/)
• examples/ and auxiliary scripts for generating wheels or examples
Relationships and interactions
• Within C++ engine, show compositional relationships:
• Graph scheduler calls NodeFactory/Registry → instantiates Node subclasses
• Nodes exchange audio buffers (shared memory objects in buffer/)
• I/O nodes interface with miniaudio layer → OS audio stack
• Patch subsystem serializes/deserializes graphs via JSON (json11)
• Build chain: CMake config → compiles C++ → links pybind11 → outputs native extension → Python packaging wraps it → pip wheel
Architectural patterns and principles
• Layered architecture (UI → binding → engine → hardware)
• Composite pattern for AudioGraph and Node tree
• Factory/Registry for dynamic Node instantiation
• Modular subsystem separation by functionality (analysis, oscillator, filter, etc.)
• Platform abstraction for I/O (abstract input/output interfaces with multiple backends)
• Clear separation of concerns:
• C++ core (performance)
• Python API (usability)
• Build/Packing (distribution)
• Documentation (user onboarding)
Detail level
• Essential architectural elements: Python CLI/UI, API binding, engine subsystems (core, node categories, patch), I/O abstraction, build & packaging, docs.
• Don’t attempt to illustrate every single node class; instead group them by category.
• Flow of control (calls) and data (audio buffers, JSON patches) distinctly.