brian/Cardinal
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Rename doc to folder docs

Browse source 
Signed-off-by: falkTX <falktx@falktx.com>
This commit is contained in:
falkTX 2022-02-11 14:46:21 +00:00
parent bc7999e2d2
commit 4a7921ee90
No known key found for this signature in database
GPG key ID: CDBAA37ABC74FBA0
14 changed files with 42 additions and 13 deletions
Download patch file Download diff file Expand all files Collapse all files

11
docs/.generate-plugin-licenses.sh Executable file
View file

@ -0,0 +1,11 @@
#!/bin/bash
set -e
cd $(dirname $0)
for p in ../plugins/*/plugin.json; do
name=$(jq -crM .name ${p})
license=$(jq -crM .license ${p})
echo "| ${name} | ${license} |"
done

181
docs/BUILDING.md Normal file
View file

@ -0,0 +1,181 @@
# Building
This document describes how to build Cardinal from source,
if you rather use Cardinal pre-built binaries please check [this wiki page](https://github.com/DISTRHO/Cardinal/wiki/Install) instead.
Before you begin, make sure you have the needed tools installed to build code, such as gcc or clang.
How to install those for your system is a bit outside the scope of this document.
It is expected you generally know how to build software by yourself.
Worth noting that, if cloning Cardinal from git, use of submodules is required.
So either clone with `--recursive` or use `git submodule update --init --recursive` after cloning.
If you are building from a release tarball you do not need to care about git.
## Build options
Cardinal uses [GNU Make](https://www.gnu.org/software/make/) as build system.
So you just got to run `make` within the Cardinal main directory in order to build.
There are a few useful options you can pass as arguments when building though.
Use them as `make SOMEOPTION=SOMEVALUE` syntax. You can specify as many options as you want.
Developer related options:
* `DEBUG=true` build non-stripped debug binaries (terrible performance, only useful for developers)
* `NOPLUGINS=true` build only the Cardinal Core plugins (not recommended, only useful for developers)
Packaging related options:
* `DESTDIR=/path` typical extra install target path (if you are used to packaging, this does what you expect)
* `PREFIX=/usr` prefix used for installation (note that it **must** be set during build time as well)
* `NOOPT=true` do not automatically set well-known optimization flags
* `SKIP_STRIPPING=true` do not automatically strip the binaries
* `SYSDEPS=true` use jansson, libarchive, samplerate and speexdsp system libraries, instead of vendored
* `WITH_LTO=true` enable Link-Time-Optimization, which has performance benefits but significantly increases the build time
Advanced options:
* `HEADLESS=true` build headless version (without gui), useful for embed systems
* `STATIC_BUILD=true` skip building Cardinal core plugins that use local resources (e.g. audio file and plugin host)
The commonly used build environment flags such as `CC`, `CXX`, `CFLAGS`, etc are respected and used.
## FreeBSD
The use of vendored libraries doesn't work on FreeBSD, as such the `SYSDEPS=true` build option is automatically set.
This means some dependencies that are optional in other systems are required under FreeBSD.
The use of `gmake` instead of `make` is also required.
Dependencies for using system libraries:
```
# common
sudo pkg install -A dbus libglvnd liblo libsndfile libX11 libXcursor libXext libXrandr python3
# system libraries
sudo pkg install -A libarchive libsamplerate jansson speexdsp
```
## Linux
There are a few differences between Linux distributions, this document covers the most common ones.
Adjust as needed if your distribution is not based on one of these.
### ArchLinux
Dependencies for using system libraries, that is, with `SYSDEPS=true`:
```
# common
sudo pacman -S dbus libgl liblo libsndfile libx11 libxcursor libxext libxrandr python3
# system libraries
sudo pacman -S libarchive libsamplerate jansson speexdsp
```
Dependencies for vendored libraries:
```
# common
sudo pacman -S dbus libgl liblo libsndfile libx11 libxcursor libxext libxrandr python3
# nedeed by vendored libraries
sudo pacman -S cmake wget
```
### Debian
Dependencies for using system libraries, that is, with `SYSDEPS=true`:
```
# common
sudo apt install libdbus-1-dev libgl1-mesa-dev liblo-dev libsndfile1-dev libx11-dev libxcursor-dev libxext-dev libxrandr-dev python3
# system libraries
sudo apt install libarchive-dev libjansson-dev libsamplerate0-dev libspeexdsp-dev
```
Dependencies for vendored libraries:
```
# common
sudo apt install libdbus-1-dev libgl1-mesa-dev liblo-dev libsndfile1-dev libx11-dev libxcursor-dev libxext-dev libxrandr-dev python3
# nedeed by vendored libraries
sudo apt install cmake wget
```
## macOS
Installing Xcode and the "Command-Line utilities" add-on is required.
Additionally you will need `python3` and `wget` from either Homebrew or MacPorts, whatever you prefer.
You can also install libsndfile in order to make Cardinal's audio file module work. (Otherwise it will support only mp3 files)
If you want to have universal builds similar to the ones officially published by Cardinal, simply setup the environment like this:
```
export CFLAGS="-DMAC_OS_X_VERSION_MAX_ALLOWED=MAC_OS_X_VERSION_10_12 -mmacosx-version-min=10.12 -arch x86_64 -arch arm64"
export CXXFLAGS="${CFLAGS}"
# make etc..
```
## Windows
Cardinal does not support msvc, using mingw is required.
You can either cross-compile Cardinal for Windows from Linux, or install and use msys2 natively on a Windows system.
### Cross-compile
For cross-compilation, first install the relevant mingw packages.
On Ubuntu these are `binutils-mingw-w64-x86-64 g++-mingw-w64-x86-64 mingw-w64`.
Then build with `CC` and `CXX` pointing to the mingw compiler, like so:
```
export CC=x86_64-w64-mingw32-gcc
export CXX=x86_64-w64-mingw32-g++
# make etc..
```
# Installing
After a successful build you will find the plugin binaries in the `bin/` directory.
You can either install them to your system using e.g. `make install PREFIX=/some/prefix` (not recommended for local source builds)
or preferably just create a symbolic link on the respective plugin format folders.
Cardinal plugin binaries expect to remain *within* their parent bundle/folder.
If you move them around make sure to keep their folder structure intact.
If you are a packager you pretty much already know what to do at this point, otherwise regular users might want to do something like:
```
mkdir -p ~/.lv2 ~/.vst ~/.vst3
ln -s $(pwd)/bin/*.lv2 ~/.lv2/
ln -s $(pwd)/bin/*.vst ~/.vst/
ln -s $(pwd)/bin/*.vst3 ~/.vst3/
```
## macOS
If running macOS, use this instead:
```
mkdir -p ~/Library/Audio/Plug-Ins/LV2 ~/Library/Audio/Plug-Ins/VST ~/Library/Audio/Plug-Ins/VST3
ln -s $(pwd)/bin/*.lv2 ~/Library/Audio/Plug-Ins/LV2/
ln -s $(pwd)/bin/*.vst ~/Library/Audio/Plug-Ins/VST/
ln -s $(pwd)/bin/*.vst3 ~/Library/Audio/Plug-Ins/VST3/
```
Note: Official macOS Cardinal builds install in the system-wide `/Library/Audio/Plug-Ins` location.
Watch out for conflicts if switching between the two builds.
## Windows
Symbolic links are not supported on Windows, so this approach doesn't work there.
On Windows you will have to copy or move the plugin bundles.
If you are building from source, it is expected you know where they should go.
# Keeping up to date
Things are evolving quickly in Cardinal! To keep your local copy up to date with the changes, simply do:
```
git pull
git submodule update --init --recursive
# make etc.. again
```

30
docs/DEBUGGING.md Normal file
View file

@ -0,0 +1,30 @@
# Building
This document describes a few possible ideas to help debug Cardinal issues.
It requires a recent build of Carla, that being >= v2.4.2, in order to work correctly.
Cardinal must be built from source with `make DEBUG=true` for any useful information to be available with these steps.
## Plugin scanning
We can use command-line carla-discovery tools together with valgrind to quickly check for memory errors and leaks.
By default carla-discovery will do 1 audio processing/run block for testing, which is handy for us here.
```
valgrind --leak-check=full --track-origins=yes --suppressions=./dpf/utils/valgrind-dpf.supp \
/usr/lib/carla/carla-discovery-native vst2 ./bin/CardinalFX.vst/CardinalFX.so
```
## Plugin usage
For regular plugin usage we can use carla-bridge tools, set as dummy mode so audio does not need to run in realtime.
We set dummy=30 in order to only trigger audio processing every 30s,
otherwise the audio thread would take all of valgrind's time and it would appear as if it was halted.
It is recommended to remove all modules from the Rack except for the strictly necessary ones for debug.
```
env CARLA_BRIDGE_DUMMY=30 \
valgrind --leak-check=full --track-origins=yes --suppressions=./dpf/utils/valgrind-dpf.supp \
/usr/lib/carla/carla-bridge-native vst2 ./bin/CardinalFX.vst/CardinalFX.so ""
```

58
docs/DIFFERENCES.md Normal file
View file

@ -0,0 +1,58 @@
# RACK PRO VS CARDINAL DIFFERENCES
This document describes the differences between Rack Pro plugin and Cardinal.
It is not possible to know all the internal details of the official plugin due to it not being open-source,
so more technical details are best-guesses based on its behaviour.
The obvious big difference is that the official plugin is a commercial, closed-source product while Cardinal is free and open-source.
Also, the official plugin works pretty much like the free standalone where you login and download modules.
This is intentionally not allowed/enabled in Cardinal, as the target is to make a self-contained plugin binary.
Online access is also not allowed.
Bellow follows a list of features comparing the official plugin to Cardinal.
| Feature | Rack Pro | Cardinal | Additional notes |
|--------------------------------|---------------------------|---------------------------------|------------------|
| Open-Source | No | Yes | |
| Free (of cost) | No | Yes | |
| Officially supported | Yes, if you pay | No, but you can fix it yourself | |
| Contains internal modules | Core only | Everything is internal | |
| Loads external modules | Yes | No | |
| Supports commercial modules | Yes | No | |
| Supports physical devices | Yes | No | Audio + MIDI only through the DAW/Host or via JACK in standalone |
| Plugin in LV2 format | No | Yes | |
| Plugin in VST2 format | Yes | Yes | |
| Plugin in VST3 format | No | WIP | |
| Plugin inside itself | No, will crash | Yes | Technical limitations prevent Rack Pro from loading inside itself |
| Multi-threaded engine | Yes | No, uses host audio thread | Intentional in Cardinal, for removing jitter |
| Supports ARM systems | No | Yes | This means Apple M1 too, yes |
| Supports BSD systems | No | Yes | Available as FreeBSD port |
| Synth plugin variant | 16 ins, 16 outs | 2 ins, 2 outs | |
| FX plugin variant | 16 ins, 16 outs | 2 ins, 2 outs | |
| Raw-CV plugin variant | Unsupported | 8 audio IO + 10 CV IO | Available in JACK, LV2 and VST3 formats, not possible in VST2 |
| Arbitrary parameter automation | Yes | No | Unsupported in Cardinal, tricky to do for many plugin formats at once |
| Integrated plugin host | No, Host payed separately | Yes, using Carla or Ildaeil | |
| Host sync/timing | Using MIDI signals | Using dedicated module | |
| Linux/X11 event handling | Runs on 2nd thread | Runs on main/GUI thread | |
| v1 module compatibility | No | No, but with less restrictions | Module widgets can load resources at any point |
| Online phone-home | Yes | No | Online access is strictly forbidden in Cardinal |
| Proper dark theme | No, only room brightness | Yes | CC-ND respected by leaving files intact, dark mode applied at runtime |
| Proper Linux headless mode | No, always requires X11 | Yes | |
Additionally, Cardinal contains the following built-in modules not present in the official plugin or standalone:
* Amalgamated Harmonics
* Aria Salvatrice modules (except Arcane related modules, due to their online requirement)
* Mog (never updated to v2)
* mscHack (never updated to v2)
* rackwindows
* repelzen
* Audio File
* Carla Plugin Host
* Ildaeil Host
* glBars (OpenGL bars visualization, as seen in XMMS and XBMC/Kodi)
* Text Editor (resizable and with syntax highlight)
* Host Parameters (24 host-exposed parameters as CV sources)
* Host Time (play, reset, bar, beat, tick, bar-phase and beat-phase CV sources)
* Host CV (for the Raw-CV plugin variant, allows direct CV access to/from the DAW)

25
docs/FAQ.md Normal file
View file

@ -0,0 +1,25 @@
# Frequently Asked Questions
This document contains a few frequently asked auestions (known as "FAQ") regarding the Cardinal project.
# Why does Cardinal exist?
Many reasons, most of them described on the [README](../README.md#why).
But basically we want an open-source plugin version of "Rack Pro",
where we are free to change things as we see fit, work on new features and fix bugs.
This is simply not possible with proprietary software, which is the case of "Rack Pro".
# Changes are lost on restart
This is intentional.
Cardinal is meant to be a self-contained plugin, and as such it does not save any files whatsoever.
This includes user preferences (like list of favourites) or last used project.
As a plugin, the state will be saved together with the host/DAW project.
# On FreeBSD and Linux the menu item "Save As/Export..." does nothing
The save-file dialogs in Cardinal requires a working [xdg-desktop-portal](https://github.com/flatpak/xdg-desktop-portal) DBus implementation from your desktop environment.
Typically your desktop already provides this, if not consider looking for a package to install with "desktop-portal" in the name.
The open-file dialogs in Cardinal do not have this restriction, with a fallback in case desktop portal is not available.

67
docs/LICENSE-PERMISSIONS.md Normal file
View file

@ -0,0 +1,67 @@
# LICENSE PERMISSIONS
A few panel graphics have uncertain license terms when it comes to redistribution and usage within Cardinal.
Cardinal authors have requested permission to the creators/owners of such graphics, for use and redistribution of the same.
This document gives details on such licenses where there is no online resource to directly link to (permission request happened via private chat or email).
Below follows a direct copy and paste of each individual request.
## Audible Instruments (Émilie Gillet @ Mutable Instruments)
*On Wednesday, January 26, 2022, 22:42:17 +0000, Filipe Coelho wrote:*
> Hello!
> My name is Filipe Coelho (or "falkTX" around the web, submitted a couple pull requests on GitHub recently).
> I am writing to you to explicitly ask permission.
>
> I have been working on a little opensource project that consolidates VCVRack and a few other 3rd party modules into a single application/binary.
> As you known, VCV has a software version of your modules for "VCV Rack", I would like to use them too.
> They mention in their README:
>
> > The panel graphics in the res/ folder are copyright © Emilie Gillet and are used and distributed with permission.
>
> It is unclear to me if this permission relates to only VCV itself, or anyone forking and reusing their project.
>
> My intent is simply to repackage what is already made but inverting the background panel color for a "dark mode" look, which in my opinion looks quite nice.
> The resource files (svgs) are actually unchanged, I apply a sorta post-processing filter to only invert specific colors on specific panels.
> The end result is this: https://i.imgur.com/sU5YJTy.jpg
>
> Let me know what you think, and if this is okay with you.
>
> Thank you and have a great day.
*On Thursday, January 27, 2022, 08:00:55 +0100, Émilie Gillet wrote:*
> Ok sure, I'm fine with that!
>
> Best,
> Émilie
## ESeries (Paul Schreiber @ SynthTech)
*On Wednesday, January 19, 2022, 04:53:44 AM CST, Filipe Coelho wrote:*
> Hello, my name is Filipe I am doing a little opensource project that consolidates VCVRack, some 3rd party modules and some modules of my own into a single application/binary.
>
> I am writing to you as a clarification request.
> VCV hosts a software version of one of your CV modules, where its license details specify:
>
> > The panel graphics in the res/ directory are copyright © Synthesis Technology and are used and distributed with permission.
>
> It is unclear to me if this permission relates to only VCV itself, or anyone forking and reusing the project.
>
> My intent is simply to repackage what is already made, so far as the ESeries project is concerned, with the only exception being color inversion of the background panel. The file itself is unchanged, I apply a sorta post-processing filter to invert specific colors on specific panels.
>
> The end result is this: https://i.imgur.com/GNiOrk5.png
>
>
> Let me know what you think, and if this is okay with you.
>
> Thank you and have a great day.
*On Wednesday, January 19, 2022, 12:37:22 +0000, Paul Schreiber wrote:*
> You have my permission to use this artwork as shown
>
> Regards,
> Paul S.

154
docs/LICENSES.md Normal file
View file

@ -0,0 +1,154 @@
# LICENSES
## CODE LICENSE / BINARY
While Cardinal itself is licensed under GPLv3+, some modules/plugins used by it are not.
And since Cardinal builds the entire Rack and modules as a static library,
the more restrictive of the **code licenses** will apply to the final binary.
Bellow follows a list of all code licenses used in Cardinal and linked submodules.
| Name | License(s) | Additional notes |
|-------------------------|-----------------------|------------------|
| Carla | GPL-2.0-or-later | Used as plugin host within Cardinal |
| DPF | ISC, GPL-2.0-or-later | Used as the plugin framework, VST2 binary GPLv2+ licensed |
| Rack | GPL-3.0-or-later | The actual Rack code, internal dependencies are compatible with GPLv3+ |
| 21kHz | MIT | |
| Amalgamated Harmonics | BSD-3-Clause | |
| Animated Circuits | GPL-3.0-or-later | |
| Aria Salvatrice | GPL-3.0-or-later | |
| Audible Instruments | GPL-3.0-or-later | |
| Autinn | GPL-3.0-or-later | |
| Bacon Music | GPL-3.0-or-later | |
| Bidoo | GPL-3.0-or-later | |
| Bogaudio | GPL-3.0-or-later | |
| cf | BSD-3-Clause | |
| ChowDSP | GPL-3.0-or-later | |
| DrumKit | CC0-1.0 | |
| E-Series | GPL-3.0-or-later | |
| ExpertSleepers Encoders | MIT | |
| Extratone | GPL-3.0-or-later | |
| Fehler Fabrik | GPL-3.0-or-later | |
| Glue the Giant | GPL-3.0-or-later | |
| Grande | GPL-3.0-or-later | |
| HetrickCV | CC0-1.0 | |
| ihtsyn | GPL-3.0-or-later | |
| Impromptu | GPL-3.0-or-later | |
| JW-Modules | BSD-3-Clause | |
| LifeFormModular | MIT | |
| Little Utils | EUPL-1.2 | |
| Lomas Modules | GPL-3.0-or-later | |
| Lyrae Modules | GPL-3.0-or-later | |
| MindMeld | GPL-3.0-or-later | |
| Mog | CC0-1.0 | |
| mscHack | BSD-3-Clause | |
| Prism | BSD-3-Clause | |
| Rackwindows | MIT | |
| repelzen | GPL-3.0-or-later | |
| Sonus Modular | GPL-3.0-or-later | |
| Valley | GPL-3.0-or-later | |
| ZetaCarinae | GPL-3.0-or-later | |
| ZZC | GPL-3.0-or-later | |
## ARTWORK / PANEL LICENSES
Bellow follows a list of all licenses related to **artwork and module panels**, sorted by file name.
Licenses were retrieved from the official project's LICENSE, README or related files.
When * is used, it is meant as wildcard of all files, with potential exceptions mentioned afterwards.
When a license is uncertain, ??? is used.
Note: The "final" version of Cardinal MUST NOT be released with unclear licenses!
So all uncertainties need to be resolved ASAP.
### Plugins
Below is a list of artwork licenses from plugins
| Name | License(s) | Additional notes |
|-----------------------------------------|------------------|------------------|
| 21kHz | MIT | No artwork specific license provided |
| AmalgamatedHarmonics/* | BSD-3-Clause | No artwork specific license provided |
| AmalgamatedHarmonics/DSEG*.ttf | OFL-1.1-RFN | |
| AmalgamatedHarmonics/Roboto*.ttf | Apache-2.0 | |
| AnimatedCircuits/* | CC-BY-NC-SA-4.0 | |
| AriaModules/* | CC-BY-SA-4.0 | |
| AriaModules/Arcane/* | CC-BY-NC-SA-3.0 | Unused in Cardinal |
| AriaModules/components/* | WTFPL | |
| AriaModules/dseg/* | OFL-1.1-RFN | |
| AriaModules/lcd/Fixed_v01/* | Custom | See [LICENSE.txt](../plugins/AriaModules/res/lcd/Fixed_v01/LICENSE.txt) |
| AriaModules/lcd/piano/* | WTFPL | |
| AriaModules/signature/* | Custom | Removal required if modifying other files without author's permission |
| AudibleInstruments/* | Custom | Copyright © Emilie Gillet, [used and distributed with permission](LICENSE-PERMISSIONS.md#audible-instruments-émilie-gillet--mutable-instruments) |
| Autinn/* | GPL-3.0-or-later | No artwork specific license provided |
| BaconPlugs/* | GPL-3.0-or-later | No artwork specific license provided |
| BaconPlugs/midi/* | CC-BY-SA-3.0-DE | |
| BaconPlugs/midi/beeth/* | ??? | Unused in Cardinal, taken from http://www.jsbach.net/ |
| BaconPlugs/1f953.svg | CC-BY-4.0 | |
| BaconPlugs/Keypunch029.json | OFL-1.1 | |
| Bidoo/* | CC-BY-NC-ND-4.0 | [Special permission granted for runtime dark mode](https://github.com/sebastien-bouffier/Bidoo/issues/191) |
| BogaudioModules/* | CC-BY-SA-4.0 | |
| BogaudioModules/fonts/audiowide.ttf | OFL-1.1-RFN | |
| BogaudioModules/fonts/inconsolata*.ttf | OFL-1.1-no-RFN | |
| Cardinal/* | CC0-1.0 | |
| Cardinal/Miku/Miku.png | CC-BY-NC-3.0 | https://piapro.net/intl/en_for_creators.html |
| cf/* | BSD-3-Clause | No artwork specific license provided |
| cf/DejaVuSansMono.ttf | Bitstream-Vera | |
| cf/Segment7Standard.ttf | OFL-1.1-RFN | |
| cf/VT323-Regular.ttf | OFL-1.1-no-RFN | |
| ChowDSP/* | GPL-3.0-or-later | Same license as source code |
| ChowDSP/fonts/RobotoCondensed-*.ttf | Apache-2.0 | |
| DrumKit/* | CC0-1.0 | |
| DrumKit/component/NovaMono.ttf | OFL-1.1-RFN | |
| E-Series/* | Custom | Copyright © Synthesis Technology, [used and distributed with permission](LICENSE-PERMISSIONS.md#eseries-paul-schreiber--synthtech) |
| ExpertSleepers-Encoders/* | MIT | [Same license as source code](https://github.com/expertsleepersltd/vcvrack-encoders/issues/3) |
| Extratone/* | GPL-3.0-or-later | [Same license as source code](https://github.com/EaterOfSheep/Extratone/issues/7) |
| FehlerFabrik/* | GPL-3.0-or-later | No artwork specific license provided, see [FehlerFabrik#17](https://github.com/RCameron93/FehlerFabrik/issues/17) |
| GlueTheGiant/* | GPL-3.0-or-later | Same license as source code |
| GlueTheGiant/fonts/DSEG7-* | OFL-1.1-RFN | |
| GrandeModular/* | CC-BY-NC-ND-4.0 | |
| HetrickCV/* | CC0-1.0 | |
| ihtsyn/* | GPL-3.0-or-later | [Same license as source code](https://github.com/nysthi/nysthi/issues/379#issuecomment-1027873902) |
| ImpromptuModular/* | CC-BY-NC-ND-4.0 | |
| ImpromptuModular/res/comp/complib/* | CC-BY-NC-4.0 | |
| JW-Modules/* | BSD-3-Clause | No artwork specific license provided |
| JW-Modules/DejaVuSansMono.ttf | Bitstream-Vera | Unused in Cardinal |
| LifeFormModular/* | MIT | No artwork specific license provided |
| LittleUtils/* | EUPL-1.2 | Same license as source code |
| LittleUtils/fonts/CooperHewitt-*.ttf | OFL-1.1-RFN | |
| LittleUtils/fonts/Overpass-*.ttf | OFL-1.1-RFN | |
| LittleUtils/fonts/RobotoMono-*.ttf | Apache-2.0 | |
| LomasModules/* | GPL-3.0-or-later | [Same license as source code](https://github.com/LomasModules/LomasModules/issues/26) |
| LomasModules/Fonts/FiraMono-Bold.ttf | OFL-1.1-RFN | |
| LyraeModules/* | CC-BY-NC-SA-4.0 | |
| MindMeld/* | CC-BY-NC-ND-4.0 | |
| MindMeld/fonts/RobotoCondensed-*.ttf | Apache-2.0 | |
| Mog/* | CC0-1.0 | |
| Mog/components/* | CC-BY-NC-4.0 | |
| Mog/Exo2-BoldItalic.ttf | OFL-1.1-RFN | |
| mscHack/* | BSD-3-Clause | No artwork specific license provided, see [mschack#108](https://github.com/mschack/VCV-Rack-Plugins/issues/108) |
| Prism/* | CC-BY-SA-4.0 | |
| Prism/RobotoCondensed-Regular.ttf | Apache-2.0 | |
| Rackwindows/* | MIT | [Same license as source code](https://github.com/n0jo/rackwindows/issues/15) |
| repelzen/* | CC-BY-SA-4.0 | |
| sonusmodular/* | GPL-3.0-or-later | [Same license as source code](https://gitlab.com/sonusdept/sonusmodular/-/issues/14) |
| ValleyAudio/* | GPL-3.0-or-later | [Same license as source code](https://github.com/ValleyAudio/ValleyRackFree/issues/73) |
| ValleyAudio/din1451alt.ttf | CC-BY-3.0-DE | |
| ValleyAudio/DSEG14Classic-*.ttf | OFL-1.1-RFN | |
| ValleyAudio/ShareTechMono-*.ttf | OFL-1.1-RFN | |
| ZetaCarinaeModules/* | GPL-3.0-or-later | [Same license as source code](https://github.com/mhampton/ZetaCarinaeModules/issues/8) |
| ZZC/* | CC-BY-NC-SA-4.0 | |
| ZZC/panels/* | CC-BY-NC-SA-4.0 | NOTE: The ZZC Logo is Copyright (c) 2019 Sergey Ukolov and cannot be used in derivative works; Cardinal's use does not officially constitute derivative work. |
| ZZC/fonts/DSEG/* | OFL-1.1-RFN | |
| ZZC/fonts/Nunito/* | OFL-1.1-RFN | |
### Rack
Below is a list of artwork licenses from Rack
| Name | License(s) |
|---------------------------------|------------------|
| ComponentLibrary/* | CC-BY-NC-4.0 |
| fonts/DejaVuSans.ttf | Bitstream-Vera |
| fonts/DSEG*.ttf | OFL-1.1-RFN |
| fonts/Nunito-Bold.ttf | OFL-1.1-RFN |
| fonts/ShareTechMono-Regular.ttf | OFL-1.1-RFN |

47
docs/MODDEVICES.md Normal file
View file

@ -0,0 +1,47 @@
---
mainfont: sans-serif
---
# Cardinal manual for MOD Devices
This document briefly describes how to use Cardinal with a [MOD device](https://www.moddevices.com/).
It is intended for this documentation to be part of the plugin bundle when installed from the
[MOD Plugin store](https://pedalboards.moddevices.com/plugins).
![Screenshot](../src/MOD/CardinalFX.lv2/modgui/screenshot.png "Screenshot")
## Plugin overview
Cardinal is a free and open-source virtual modular synthesizer plugin,.
It is based on the popular [VCV Rack](https://vcvrack.com/) but with a focus on being a fully self-contained plugin version.
If you already know Rack, Cardinal will be very familiar to you.
## Plugin usage
Currently Cardinal does not allow patch editing directly on the MOD units,
instead users need to run the "desktop" version of the plugin and connect it to the device.
This is easily done by the use of "File" -> "Connect to MOD" action.
After a successful connection, the same "File" menu will now show a "Deploy to MOD" option.
Clicking on it will push the current patch to the MOD unit, along with a screenshot of the current view.
You can also use the F7 shortcut key to do the same.
Additionally, enabling "Auto-deploy to MOD" will make Cardinal (the "desktop" plugin side)
automatically send the current patch to the MOD unit after 5 seconds of inactivity.
### Notes and caveats
This push-to-device workflow is very limited, it will improve in a future release.
For now it can already work to push existing or new patches to the unit.
After you push a patch, you can use MOD preset system to save a patch as plugin preset,
which will allow you to load it at a different time without the need for the "desktop" connection.
There are a few critical things to take into consideration for this release:
- Only one Cardinal instance is reachable in terms of desktop -> MOD connection,
you can and should use multiple instances when there is no desktop connection though
- The MOD unit must be connected over USB, so that the 192.168.51.1 IP is reachable
- The Audio File, Carla and Ildaeil modules are not available in MOD builds
- Lights and meters from the Cardinal MOD side are not transmitted back to the desktop side
- Compared to desktop, MOD builds are not as fast, so do not expect to load big patches

142
docs/OVERVIEW.md Normal file
View file

@ -0,0 +1,142 @@
# PROJECT OVERVIEW
This document describes how the DISTRHO Cardinal project is structured,
so developers and interested third-parties can have an easier time contributing code and resources.
On the root folder the following directories can be seen;
* [carla](#carla)
* [deps](#deps)
* [doc](#doc)
* [dpf](#dpf)
* [include](#include)
* [lv2export](#lv2export)
* [patches](#patches)
* [plugins](#plugins)
* [src](#src)
Going through one by one in alphebetical order we have...
## carla
This directory contains the source code for Carla, a modular plugin host created by falkTX, the same author of Cardinal, DPF and many other projects.
Cardinal uses Carla as the base for all internal plugin hosting.
Being GPLv2+ the code license is compatible with Cardinal's GPLv3+.
## deps
3rd-party libraries build setup.
No Cardinal specific code is hosted here, only external submodules and a Makefile with steps for fetching extra source code and build it.
The Makefile overrides Rack's `dep.mk` things for a proper static build, and supporting more platforms.
## doc
Here you find several files (like this one you are reading now) describing the Cardinal project.
It is intentionally not using something like GitHub Wiki so that rehosting does not lose any information.
Also allows for offline hosting and reading.
## dpf
This directory contains the source code for DPF, the plugin framework used by Cardinal that handles all the complex parts of plugin format support.
Implementing new plugin formats will be done here.
## include
This directory contains special header files needed to build the original Rack code as required by Cardinal.
These headers are included before the official Rack ones, allowing us to override some implementation details.
Additionally a few compatiblity headers are present, helping compile the code for more targets than officially supported in Rack.
## lv2export
An experiment for building individual Rack modules directly as LV2 plugins.
Only quick&dirty hacks so far, nothing interesting to see here yet.
## patches
Public domain or CC0 licensed Rack patches, suitable for use in Cardinal.
Must be stored as plain text files (not zstd compressed) so they play nicely with git.
## plugins
Module/Plugin related code and build setup.
Only Cardinal internal modules are hosted here, everything else uses a git submodule reference.
See https://github.com/DISTRHO/Cardinal/discussions/28 for how to add more modules yourself.
## src
The main code for Cardinal, where the magic happens.
There are quite a few files here, so let's describe them in detail.
### Cardinal / CardinalFX / CardinalSynth
Directories that contain the supported Cardinal plugin variants.
Everything is a symlink except `DistrhoPluginInfo.h` (setting plugin info) and `Makefile` (set the unique name).
The source code is the same for all the variants, with compiler macros used to tweak behaviour and IO count.
### extra
A few extra files for having access to a few utilities, code borrowed from Carla, which in turn borrowed it from JUCE.
The important one is `SharedResourcePointer`, as a way to easily manage a shared class lifecycle.
### custom
Here are files that are originally from Rack but fully reimplemented in Cardinal.
Some of them are just stubs to define function symbols but without an actual implementation, for example disabling network features.
### override
Here are files that are very close to the original from Rack but required tweaks for Cardinal.
Extra care is needed to ensure these are kept in sync with the originals.
### Rack
A git submodule reference to the official Rack source code repository.
### AsyncDialog.{cpp,hpp}
Custom Cardinal code for showing a dialog in async fashion, optionally with a callback for when the user clicks "Ok".
### CardinalPlugin.cpp
The DSP/plugin side of the plugin, and also where the global/shared class lifecycle is managed.
This file implements the DPF `Plugin` class.
### CardinalUI.cpp
The UI-specific side of the plugin, dealing with e.g. Window events.
This file implements the DPF `UI` class.
### Makefile
The file describing rules for building Rack's code as a rack.a static library.
### Makefile.cardinal.mk
A makefile imported by each of Cardinal's plugin variants, which will build the actual plugin.
This same file is used by all variants, changing behaviour based on the plugin variant name.
### PluginContext.hpp
And handy but perhaps somewhat hacky `rack::Context` class extension, so internal modules can have direct access to DAW provided data.
This also extends the base `Plugin` and `UI` classes from DPF, to provide methods needed for Rack Audio/MIDI drivers.
### PluginDriver.hpp
Code that glues Rack Audio/MIDI drivers to the DPF side of things.
### ResizeHandle.hpp
A DPF-related Widget that does what you think it does.
Handles all the resizing for us.
### template.vcv
The default template patch as used by Cardinal
### WindowParameters.hpp
Defines a few methods for saving and restoring Rack Window state, in order to allow many Cardinal/Rack UIs to be open at once even though Rack `settings` is a global.
Used by `CardinalUI.cpp` and `override/Window.cpp`.

BIN
docs/Screenshot1.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 1.3 MiB

BIN
docs/Screenshot2.png Normal file
View file

Binary file not shown.
Side by side

After

Width:  |  Height:  |  Size: 971 KiB