Merge branch 'release/0.7.0'

.bumpversion.cfg

@@ -1,5 +1,5 @@
 [bumpversion]
-current_version = 0.6.3
+current_version = 0.7.0
 
 [bumpversion:file:setup.cfg]
 

.github/workflows/irc.yml

@@ -10,7 +10,7 @@ jobs:
       - name: Format message
         id: message
         run: |
-          message="${{ github.actor }} pushed $(echo '${{ github.event.commits[0].message }}' | head -n 1) ${{ github.event.commits[0].url }}"
+          message="${{ github.actor }} pushed $(echo ${{ toJSON(github.event.commits[0].message) }} | head -n 1) ${{ github.event.commits[0].url }}"
           echo ::set-output name=message::"${message}"
       - name: IRC notification
         uses: Gottox/irc-message-action@v2

CHANGELOG.md

@@ -1,6 +1,18 @@
 CHANGELOG
 =====
 
+0.7.0
+-----
+
+* improvements: add type annotations to all methods; run mypy over the whole library
+* DPF: basic UI generation using dpf-widgets (imgui + modgui)
+* DPF: basic port groups support
+* abstractions: use duplicate of delread4~.pd for vd~.pd
+* deprecated: internal Bela implementation (use downstream instead)
+* docs: add notes
+* docs: fix markdown syntax
+* bugfixes: issues #86, #87 and #93 
+
 0.6.3
 -----
 

README.md

@@ -1,31 +1,28 @@
-[![Build Status](https://github.com/Wasted-Audio/hvcc/actions/workflows/build.yml/badge.svg)](https://github.com/Wasted-Audio/hvcc/actions)
-
-This is an attempt to modernize `hvcc` to work with `python3` and add some additional targets.
-
-Not all functionality is being tested. Bugreports and feedback are appreciated.
-
 # Heavy Compiler Collection (hvcc)
 
+[![Build Status](https://github.com/Wasted-Audio/hvcc/actions/workflows/build.yml/badge.svg)](https://github.com/Wasted-Audio/hvcc/actions)
+
 `hvcc` is a python-based dataflow audio programming language compiler that generates C/C++ code and a variety of specific framework wrappers.
 
 ## Background
 
-The original need for `hvcc` arose from running against performance limitations while creating interactive music and sound products for the iPhone. [Pure Data](https://puredata.info) (libpd) was the only real choice for a design tool as it was embeddable and provided a high enough abstraction level that musicians or sound designers could be creative.
+Originaly created by Enzien Audio, the need for `hvcc` arose from running against performance limitations while creating interactive music and sound products for the iPhone. [Pure Data](https://puredata.info) (libpd) was the only real choice for a design tool as it was embeddable and provided a high enough abstraction level that musicians or sound designers could be creative.
 
 The goal was to leverage Pure Data as a design interface and statically interpret the resultant patches to generate a low-level, portable and optimised C/C++ program that would be structured to take advantage of modern hardware whilst still generating the same behaviour and audio output as Pure Data.
 
-It has since then been expanded to provide further support for many different platforms and frameworks, targeting game audio design, daw plugins and embedded production tools.
+It has since then been expanded to provide further support for many different platforms and frameworks, targeting game audio design, daw plugins and embedded production tools. In 2021 Wasted Audio took over maintenance of the project.
 
 ## Requirements
 
 * python 3.7 or higher
-    - `jinja2` (for generator templating)
-    - `importlib_resources` (for reading static resources)
-    - `json2daisy` (for daisy integration)
-    - `tox` (for tests, optional)
-    - `clang/clang++` (for building tests, optional)
+  * `jinja2` (for generator templating)
+  * `importlib_resources` (for reading static resources)
+  * `json2daisy` (for daisy integration)
+  * `tox` (for tests, optional)
+  * `clang/clang++` (for building tests, optional)
 
 ## Installation
+
 hvcc is available from pypi.org and can be installed using python3 pip:
 
 `$ pip3 install hvcc`
@@ -90,13 +87,14 @@ A list of available generator options can be found [here](/docs/03.generators.md
 
 `hvcc` will iterate through various directories when resolving patch objects and abstractions. The `-p` or `--search_paths` argument can be used to add additional folders for `hvcc` to look in. Note that this argument is not needed for abstractions in the same folder as the top-level patch.
 
-This can be handy when using a third-party patch library for example https://github.com/Wasted-Audio/heavylib.
+This can be handy when using a third-party patch library like [heavylib](https://github.com/Wasted-Audio/heavylib) for example.
 
 Simply append any folder paths after the `-p` flag like so:
 
 `$ hvcc ~/myProject/_main.pd -o ~/Desktop/somewhere/else/ -n mySynth -p ~/Workspace/Projects/Enzien/heavylib/ ~/Desktop/myLib/`
 
 ### `-m` Meta Data
+
 `hvcc` can take extra meta-data via a supplied json file. It depends on the generator which fields are supported.
 
 ### `--copyright` User Copyright
@@ -116,11 +114,11 @@ Displays all the available parameters and options for hvcc.
 ## Documentation
 
 * [Introduction](/docs/01.introduction.md)
-  - [What is heavy?](/docs/01.introduction.md#what-is-heavy)
-  - [Supported patch formats](/docs/01.introduction.md#supported-patch-formats)
-  - [Supported platforms](/docs/01.introduction.md#supported-platforms)
-  - [Supported frameworks](/docs/01.introduction.md#supported-frameworks)
-  - [Licensing](/docs/01.introduction.md#licensing)
+  * [What is heavy?](/docs/01.introduction.md#what-is-heavy)
+  * [Supported patch formats](/docs/01.introduction.md#supported-patch-formats)
+  * [Supported platforms](/docs/01.introduction.md#supported-platforms)
+  * [Supported frameworks](/docs/01.introduction.md#supported-frameworks)
+  * [Licensing](/docs/01.introduction.md#licensing)
 * [Getting Started](/docs/02.getting_started.md)
 * [Generators](/docs/03.generators.md)
 * [MIDI](/docs/04.midi.md)
@@ -132,13 +130,15 @@ Displays all the available parameters and options for hvcc.
 * [Unsupported vanilla objects](/docs/10.unsupported_vanilla_objects.md)
 
 ## Contact
+
 There are several places where heavy/hvcc conversation is happening:
+
 * [Discord](https://discord.gg/fmxJveg)
 * [IRC](https://web.libera.chat/#hvcc)
 * A number of forums:
   * [Bela](https://forum.bela.io/?q=hvcc)
   * [Rebel Technology](https://community.rebeltech.org/tags/puredata)
-  * [Daisy](https://forum.electro-smith.com/t/pure-data/110)
+  * [Daisy](https://forum.electro-smith.com/c/integrations/pure-data/32)
   * [MOD](https://forum.moddevices.com/c/developers/pure-data/56)
 
 Or you can use the [discussions](https://github.com/Wasted-Audio/hvcc/discussions) tab of this repository

docs/01.introduction.md

@@ -1,6 +1,7 @@
 # Introduction
 
 ## What is Heavy?
+
 Heavy is a framework for easily generating audio plugins for use in interactive sound and music applications such games, instruments or installations.
 
 It aims to reduce the dependency on low-level programming from a creative standpoint and bridge the gap from idea to production-ready implementation.
@@ -14,6 +15,7 @@ Currently Heavy supports compiling Pure Data (.pd) patch files.
 However it's important to note that Pd is merely used as a front-end authoring editor, Heavy does not make use of any Pure Data code, and it is entirely unrelated to the embeddable Pd engine, [libpd](https://github.com/libpd/libpd).
 
 ## What is Pure Data?
+
 [Pure Data](http://msp.ucsd.edu/software.html) (Pd) is an open source visual programming environment for real-time time audio and music creation.
 
 Heavy can interpret and convert a subset of features from Pure Data patches:
@@ -22,6 +24,7 @@ Heavy can interpret and convert a subset of features from Pure Data patches:
 * [Unsupported Pd objects](10.unsupported_vanilla_objects.md)
 
 ## Supported Platforms
+
 * Windows 8, 10 and WSA
 * Mac OSX
 * Linux
@@ -36,18 +39,20 @@ Heavy can interpret and convert a subset of features from Pure Data patches:
 * Web (Javascript)
 
 ## Supported Frameworks
+
 * [Fabric](http://www.tazman-audio.co.uk)
 * [Unity 5](https://unity3d.com)
 * [Distrho Plugin Framework](https://distrho.github.io/DPF)
-    * [LV2](https://lv2plug.in)
-    * [VST2](https://www.steinberg.net/technology/)
-    * [VST3](https://www.steinberg.net/technology/)
-    * [CLAP](https://cleveraudio.org/)
-    * [JACK](https://jackaudio.org)
+  * [LV2](https://lv2plug.in)
+  * [VST2](https://www.steinberg.net/technology/)
+  * [VST3](https://www.steinberg.net/technology/)
+  * [CLAP](https://cleveraudio.org/)
+  * [JACK](https://jackaudio.org)
 * [Wwise](https://www.audiokinetic.com)
 * [Web Audio API (AudioWorkletProcessor)](https://developer.mozilla.org/en-US/docs/Web/API/AudioWorkletProcessor)
 
 ## Optimisations
+
 Heavy-generated code comes pre-optimised for architectures that can take advantage of AVX, SSE or NEON instructions. For more bespoke platforms, Heavy also provides a basic implementation supporting single sample block sizes.
 
 ## Licensing

docs/02.getting_started.md

@@ -1,6 +1,7 @@
 # Getting Started
 
 ## Audio Input/Output
+
 To receive audio input into your patch add an `[adc~]` object.
 
 To send audio output add a `[dac~]` The number of channels can be configured by providing arguments to object. For example `[dac~ 1 2 3]` will generate three output channels. `[adc~ 1]` will make a single channel of audio input.
@@ -38,6 +39,7 @@ Messages passed to these send objects can be forwarded on to other parts of the
 See the specific framework details for more information on output parameter support and integration details.
 
 ## Exposing Events
+
 All (control) `[receive]` and `[r]` objects annotated with `@hv_event` will be exposed as events in the Unity target only.
 
 ![events](img/docs_exposed_events.png)
@@ -49,8 +51,8 @@ For example, `[r bang @hv_event]` will show up as a button called "bang" in the
 See the [Unity docs](03.gen.unity.md#exposing-and-sending-events) for more information on exposing events and controlling them.
 
 ## Metadata
-Some generators, like Daisy and DPF, enable support for extra configuration metadata.json file using the `-m`. It depends on the generator what is supported. See the [DPF docs](03.gen.dpf.md#metadata) for more information on setting meta data for plugins.
 
+Some generators, like Daisy and DPF, enable support for extra configuration metadata.json file using the `-m`. It depends on the generator what is supported. See the [DPF docs](03.gen.dpf.md#metadata) for more information on setting meta data for plugins.
 
 Simple Daisy example that selects the desired board to build for:
 
@@ -63,15 +65,23 @@ Simple Daisy example that selects the desired board to build for:
 ```
 
 ## Errors
+
 If there's an incompatibility within the patch, Heavy will generate an error message.
 
 ![errors](img/docs_errors.png)
 
 ## Warnings
+
 Heavy will also perform patch analysis to look for common mistakes and inconsitencies between Pd and heavy behaviour. The targets will still be generated correctly but it might be useful information for example when cleaning up the patch.
 
 ![warnings](img/docs_warnings.png)
 
 ## Reporting Issues
 
 If you experience any problems or have some thoughts on how to improve heavy make sure to browse and contribute to our [public issue tracker](https://github.com/Wasted-Audio/hvcc/issues).
+
+## Known Limitations
+
+* Heavy does not support numbers in `[unpack]`, e.g. `[unpack 0 0]` gives `Heavy only supports arguments 'f' and 's' to unpack.` Workaround is to use `f` instead, e.g. `[unpack f f]`, and if necessary prime the default values with a `[loadbang]` and `[0 0(`.
+* Heavy does not accept arguments and control connections to: `[rzero~]`, `[rzero_rev~]`, `[czero~]`, `[czero_rev~]`. In Heavy, these objects accept only signal inputs. Arguments and control connections are ignored.
+* Certain filters are sensitive to ‘blowing up’ at very low or very high cutoff frequencies and/or resonances, due to the filter coefficients not being perfectly represented with a finite number of bits. While Pure data natively uses 64 bits, platforms like `OWL` and `Daisy`  that use 32 bit float are more sensitive to this. For example, the Pure data `[lp~]`, `[bp~]` and `[hp~]` filters are implemented with biquads which are prone to fail or distort with cutoff frequencies less than around 200 Hz (at 48kHz sample rate).

docs/03.gen.daisy.md

@@ -22,4 +22,4 @@ Which can be configured using the `-m` metadata.json `daisy.board` setting:
 }
 ```
 
-However one can also create custom board layouts. See the pd2dsy documentation for more information.
+However one can also create custom board layouts. See the pd2dsy documentation for more information.

docs/03.gen.dpf.md

@@ -5,16 +5,19 @@ Heavy can generate LV2, VST2, VST3, and CLAP plugins from your patch using the [
 Some [examples](https://github.com/Wasted-Audio/hvcc-examples-dpf) are built for the major operating systems (Linux/Windows/MacOS) in various formats (LV2/VST2/VST3/CLAP).
 
 ## Defining Parameters
+
 Each [exposed parameter](02.getting_started.md#exposing-parameters) will automatically generate a slider in the plugin interface.
 
 ## MIDI Control
+
 In order to receive MIDI note on and off events, as well as control change messages, the `[notein]` and `[ctlin]` objects should be used, respectively.
 
 DPF supports all note/ctl/pgm/touch/bend I/O events. The implementation is further discussed in the [midi docs](04.midi.md)
 
 ![notein](img/docs_notein.png)
 
 ## Parameter Types
+
 In DPF a parameter can get an optional type configured. The default type is `float`. Other assignable types are `bool` - for toggling a value - and `trig` - for momentary signals.
 
 ![dpf](img/docs_param_type.png)
@@ -35,7 +38,6 @@ The `project` flag creates a `README.md` and `Makefile` in the root of the proje
 
 Each of these are optional and have either a default value or are entirely optional (description and homepage). Midi i/o ports are on by default, but can be set to `0` and they will be disabled - currently `midi_input` always has to be on!.
 
-
 ```json
 {
     "dpf": {
@@ -59,7 +61,21 @@ Each of these are optional and have either a default value or are entirely optio
 }
 ```
 
+Other fields that the DPF metadata supports are:
+
+* `port_groups` - If your plugin has more audio i/o that need to be grouped together.
+* `enable_ui` - Boolean that creates a generic GUI. Requires `dpf-widgets` on the same level as `dpf`.
+* `enable_modgui` - Boolean for use in MOD audio based systems.
+* `ui_size` - Dict of width & height that sets the size of the UI.
+* `plugin_clap_id` - A URI for use with CLAP format.
+* `lv2_info` - String describing the LV2 plugin type.
+* `vst3_info` - String describing the VST3 plugin type.
+* `clap_info` - List of strings describing the CLAP plugin type.
+
+An example plugin that uses these extended metadata is [WSTD 3Q](https://github.com/Wasted-Audio/wstd-3q).
+
 ## Notes
+
 * The `[notein]` object is the only supported means of receiving MIDI note events (i.e. Note On and Note Off). Arguments to the object (e.g. to specify the channel number) will be ignored. Velocity of `0` will be assumed to mean Note Off
 * The `[ctlin]` object is the only supported means of receiving MIDI control change events. Arguments to the object (e.g. to filter which CC event is delivered) will be ignored.
 * If you are compiling from source, make sure to read the included `README.md` file in the root directory.