From ae4a9a1e7e3ddc47874562b26f501233c54903bb Mon Sep 17 00:00:00 2001 From: Weird Constructor Date: Tue, 18 May 2021 05:39:21 +0200 Subject: [PATCH] add documentation link --- README.md | 5 ++ src/lib.rs | 232 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 237 insertions(+) diff --git a/README.md b/README.md index dcacffe..97caa31 100644 --- a/README.md +++ b/README.md @@ -23,6 +23,11 @@ Here a short list of features: ## API Examples +### Documentation + +The development documentation can be found separately hosted: +[HexoDSP API Documentation](http://m8geil.de/hexodsp_doc/hexodsp/). + ### Raw `NodeConfigurator` API This API is the most low level API provided by HexoDSP. diff --git a/src/lib.rs b/src/lib.rs index a455b25..b7320d5 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -2,6 +2,238 @@ // This is a part of HexoDSP. Released under (A)GPLv3 or any later. // See README.md and COPYING for details. +/*! + +# HexoDSP - Comprehensive DSP graph and synthesis library for developing a modular synthesizer in Rust, such as HexoSynth. + +This project contains the complete DSP backend of the modular +synthesizer [HexoSynth](https://github.com/WeirdConstructor/HexoSynth). + +It's aimed to provide a toolkit for everyone who wants to develop +a synthesizer in Rust. You can use it to quickly define a DSP graph +that you can change at runtime. It comes with a large collection +of already developed DSP modules/nodes, such as oscillators, filters, +amplifiers, envelopes and sequencers. + +The DSP graph API also provides multiple kinds of feedback to track what the +signals in the DSP threads look like. From monitoring the inputs and outputs of +single nodes to get the current output value of all nodes. + +Here a short list of features: + +* Runtime changeable DSP graph +* Full monitoring and feedback introspection into the running DSP graph +* Provides a wide variety of modules +* Extensible framework for quickly developing new nodes at compile time +* A comprehensive automated test suite + +## API Examples + +### Raw `NodeConfigurator` API + +This API is the most low level API provided by HexoDSP. +It shows how to create nodes and connect them. +The execution of the nodes in the audio thread is +controlled by a `NodeProg`, which defines the order +the nodes are executed in. + +This only showcases the non-realtime generation of audio +samples. For a real time application of this library please +refer to the examples that come with this library. + +```rust +use hexodsp::*; + +let (mut node_conf, mut node_exec) = new_node_engine(); + +node_conf.create_node(NodeId::Sin(0)); +node_conf.create_node(NodeId::Amp(0)); + +let mut prog = node_conf.rebuild_node_ports(); + +node_conf.add_prog_node(&mut prog, &NodeId::Sin(0)); +node_conf.add_prog_node(&mut prog, &NodeId::Amp(0)); + +node_conf.set_prog_node_exec_connection( + &mut prog, + (NodeId::Amp(0), NodeId::Amp(0).inp("inp").unwrap()), + (NodeId::Sin(0), NodeId::Sin(0).out("sig").unwrap())); + +node_conf.upload_prog(prog, true); + +let (out_l, out_r) = node_exec.test_run(0.1, false); +``` + +### Hexagonal Matrix API + +This is a short overview of the API provided by the +hexagonal Matrix API, which is the primary API used +inside [HexoSynth](https://github.com/WeirdConstructor/HexoSynth). + +This only showcases the non-realtime generation of audio +samples. For a real time application of this library please +refer to the examples that come with this library. + +```rust +use hexodsp::*; + +let (node_conf, mut node_exec) = new_node_engine(); +let mut matrix = Matrix::new(node_conf, 3, 3); + + +let sin = NodeId::Sin(0); +let amp = NodeId::Amp(0); +matrix.place(0, 0, Cell::empty(sin) + .out(None, None, sin.out("sig"))); +matrix.place(0, 1, Cell::empty(amp) + .input(amp.inp("inp"), None, None)); +matrix.sync().unwrap(); + +let gain_p = amp.inp_param("gain").unwrap(); +matrix.set_param(gain_p, SAtom::param(0.25)); + +let (out_l, out_r) = node_exec.test_run(0.11, true); +// out_l and out_r contain two channels of audio +// samples now. +``` + +## State of Development + +As of 2021-05-18: The architecture and it's functionality have been mostly +feature complete by now. The only part that is still lacking is the collection +of modules/nodes, this is the area of current development. Adding lots of +nodes. + +Make sure to follow [Weird Constructors Mastodon +account](https://mastodon.online/@weirdconstructor) or the releases of this +project to be notified of updates. + +### Road Map / TODO List + +I have a pretty detailed TODO list in my private notebook. + +## Running the Jack Example: + +You need nightly rust: + + rustup toolchain install nightly + +To run the example: + + cargo +nightly run --release --example jack_demo + +You might need following dependencies (Ubuntu Linux): + + sudo apt install libjack0 libjack-jackd2-dev qjackctl + +These might work on Debian too: + + sudo apt install libjack0 libjack-dev + +## Running the Automated Testsuite: + +There exists an automate test suite for the DSP and backend code: + + cargo test + +## Known Bugs + +* The ones you encounter and create as issues on GitHub. + +## Contributions + +I currently have a quite precise vision of what I want to achieve and my goal +is to make music with this project eventually. + +The projects is still young, and I currently don't have that much time to +devote for project coordination. So please don't be offended if your issue rots +in the GitHub issue tracker, or your pull requests is left dangling around +for ages. + +I might merge pull requests if I find the time and think that the contributions +are in line with my vision. + +Please bear in mind, that I can only accept contributions under the License +of this project (AGPLv3 or later). + +## Contact the Author + +You can reach me via Discord or Mastodon. I'm joined most public Rust Discord +servers, especially the "Rust Audio" Discord server. I am also sometimes on +freenode.net, for instance in the `#lad` channel (nick `weirdctr`). + +## Support Development + +You can support me (and the development of this project) via Liberapay: + +Donate using Liberapay + +## License + +This project is licensed under the GNU Affero General Public License Version 3 or +later. + +### Why (A)GPL? + +The obivious reason is that this project copied and translated code from many +other free software / open source synthesis projects. The sources +will show the origin and license of the individual parts. + +#### My Reasons + +Picking a license for my code bothered me for a long time. I read many +discussions about this topic. Read the license explanations. And discussed +this matter with other developers. + +First about _why I write code for free_ at all, the reasons are: + +- It's my passion to write computer programs. In my free time I can +write the code I want, when I want and the way I want. I can freely +allocate my time and freely choose the projects I want to work on. +- To help a friend or member of my family. +- To solve a problem I have. +- To learn something new. + +Those are the reasons why I write code for free. Now the reasons +_why I publish the code_, when I could as well keep it to myself: + +- So that it may bring value to users and the free software community. +- Show my work as an artist. +- To get into contact with other developers. +- To exchange knowledge and help other developers. +- And it's a nice change to put some more polish on my private projects. + +Most of those reasons don't yet justify (A)GPL. The main point of the (A)GPL, as far +as I understand: The (A)GPL makes sure the software stays free software until +eternity. That the _end user_ of the software always stays in control. That the users +have the means to adapt the software to new platforms or use cases. +Even if the original authors don't maintain the software anymore. +It ultimately prevents _"vendor lock in"_. I really dislike vendor lock in, +especially as developer. Especially as developer I want and need to stay +in control of the computers and software I use. + +Another point is, that my work (and the work of any other developer) has a +value. If I give away my work without _any_ strings attached, I effectively +work for free. This compromises the price I (and potentially other developers) +can demand for the skill, workforce and time. + +This makes two reasons for me to choose the (A)GPL: + +1. I do not want to support vendor lock in scenarios for free. + I want to prevent those when I have a choice, when I invest my private + time to bring value to the end users. +2. I don't want to low ball my own (and other developer's) wage and prices + by giving away the work I spent my scarce private time on with no strings + attached. I do not want companies to be able to use it in closed source + projects to drive a vendor lock in scenario. + +We can discuss relicensing of my code or project if you are interested in using +it in a closed source project. Bear in mind, that I can only relicense the +parts of the project I wrote. If the project contains GPL code from other +projects and authors, I can't relicense it. + +*/ + pub mod nodes; #[allow(unused_macros)] pub mod dsp;