A ton of bug fixes
This commit is contained in:
18
docs/about.md
Normal file
18
docs/about.md
Normal file
@@ -0,0 +1,18 @@
|
||||
# About
|
||||
|
||||
Cagire is an experimental step sequencer built by BuboBubo (Raphaël Maurice Forment). It is a free and open-source project licensed under the AGPL-3.0 License. Cagire has been developed as a side project. I wanted to learn more about using Forth and needed a playground for experimentating with this audio engine! You are free to contribute to the project by making direct contributions to the codebase or by providing feedback and suggestions.
|
||||
|
||||
## Credits
|
||||
|
||||
- **Doux** (audio engine) is a Rust port of Dough, originally written in C by Felix Roos.
|
||||
- **mi-plaits-dsp-rs** is a Rust port of the code used by the Mutable Instruments Plaits.
|
||||
* _Author_: Oliver Rockstedt [info@sourcebox.de](info@sourcebox.de).
|
||||
* _Original author_: Emilie Gillet [emilie.o.gillet@gmail.com](emilie.o.gillet@gmail.com).
|
||||
|
||||
## About live coding
|
||||
|
||||
Live coding is a technique where a programmer writes code in real-time in front of an audience. It is a way to experiment with code, to share things and thoughts openly, to express yourself through code. It can be technical, poetical, weird, preferably all at once. Live coding can be used to create music, visual art, and other forms of media. Learn more about live coding on [https://toplap.org](https://toplap.org) or [https://livecoding.fr](https://livecoding.fr). Live coding is an autotelic activity: it is an activity that is intrinsically rewarding, and the act of doing it is its own reward. There are no errors, only fun to be found by playing music.
|
||||
|
||||
## About the tool
|
||||
|
||||
I do not want to pair it with a DAW, I do not want to make it fit with other commercial software. I'm not interested in VSTs or other proprietary workstations. Please, try to think of Cagire as an alternative to other tools.
|
||||
73
docs/audio_engine.md
Normal file
73
docs/audio_engine.md
Normal file
@@ -0,0 +1,73 @@
|
||||
# Audio Engine
|
||||
|
||||
Cagire uses **Doux** as its audio engine ([https://doux.livecoding.fr](https://doux.livecoding.fr)). Doux is a standalone synthesis and sampling engine that receives commands as strings and turns them into sound. Doux is a fixed graph synthesizer, which means that the structure of the sound is defined by a fixed set of nodes and connections, and the parameters of these nodes can be adjusted to create different sounds. Doux is extremely versatile and you are likely to find it useful for a wide range of musical styles and genres.
|
||||
|
||||
## How Sound is Produced
|
||||
|
||||
When the sequencer hits an active step, the Forth script is compiled and executed. Each emit operation (`.`) generates a command string that is sent to Doux. The command encodes the sound name and all accumulated parameters. The following example script:
|
||||
|
||||
```
|
||||
"saw" sound c4 note 0.5 gain 2000 lpf .
|
||||
```
|
||||
|
||||
will produce a command string that Doux interprets to _play a saw wave at C4 with gain 0.5 and a 2kHz lowpass filter_.
|
||||
|
||||
## Sound sources
|
||||
|
||||
Each sound needs a source. Sources are defined by typing their name followed by the `sound` keyword. Sources are raw waveforms or samples. They are shaped by passing additional parameters that will modify the characteristics of the sound: envelopes, effects, synthesis options, etc. The following example defines a source named `saw` with a frequency of 440 Hz, a gain of 0.5 and some reverb:
|
||||
|
||||
```
|
||||
"saw" source 440 freq 0.5 gain 0.5 verb .
|
||||
```
|
||||
|
||||
The audio engine offers a vast array (~20+) of sources including oscillators, noises, live input, and more.
|
||||
|
||||
## Settings
|
||||
|
||||
- **Channels**: Output channel count (1-64)
|
||||
- **Buffer Size**: Audio buffer in samples (64-4096). Lower values reduce latency but increase CPU load.
|
||||
- **Voices**: Maximum polyphony (1-128, default 32). When the limit is reached, the oldest voice is stolen.
|
||||
|
||||
Settings are persisted across sessions.
|
||||
|
||||
## Samples
|
||||
|
||||
Cagire scans sample directories recursively and indexes all audio files. Add sample paths on the Engine page with **a**, remove with **d**. Use samples in scripts by name:
|
||||
|
||||
```
|
||||
"kick" s .
|
||||
"hat" s 0.5 gain .
|
||||
```
|
||||
|
||||
The sample index is shown on the Engine page with the total count.
|
||||
|
||||
## Visualizers
|
||||
|
||||
The Engine page displays two real-time visualizers:
|
||||
|
||||
- **Scope**: Waveform display (64 samples), updated on every audio callback
|
||||
- **Spectrum**: 32-band FFT analyzer with logarithmic frequency scaling (20Hz to Nyquist), Hann window, displayed in dB
|
||||
|
||||
Both can be toggled on or off in the Options page.
|
||||
|
||||
## Monitoring
|
||||
|
||||
The Engine page shows live metrics:
|
||||
|
||||
- **Active voices**: Current polyphony count
|
||||
- **Peak voices**: Highest voice count since last reset (press **r** to reset)
|
||||
- **CPU load**: Audio thread utilization
|
||||
- **Events**: Total emitted and dropped event counts
|
||||
|
||||
## Tempo Scaling
|
||||
|
||||
Some parameters are automatically scaled by step duration so they sound consistent across tempos. These include envelope times (attack, decay, release), filter envelopes, pitch envelopes, FM envelopes, glide, and reverb/delay times.
|
||||
|
||||
## Commands
|
||||
|
||||
On the Engine page:
|
||||
|
||||
- **h**: Hush (graceful fade-out of all voices)
|
||||
- **p**: Panic (hard stop all voices immediately)
|
||||
- **r**: Reset peak voice counter
|
||||
- **t**: Test sound (plays a 440Hz sine)
|
||||
@@ -1,55 +1,16 @@
|
||||
# Welcome to Cagire
|
||||
|
||||
Cagire is a terminal-based step sequencer for live music. Each step in a pattern contains a Forth script that controls sound synthesis and effects.
|
||||
Cagire is a terminal-based step sequencer for live coding music. Each step in a pattern contains a **Forth** script that produces sound and create events. It is made by BuboBubo (Raphaël Maurice Forment): [https://raphaelforment.fr](https://raphaelforment.fr). Cagire is open-source (AGPL-3.0 licensed) and available on GitHub : [https://github.com/BuboBubo/cagire](https://github.com/BuboBubo/cagire). This help view will teach you everything you need to know to start using Cagire and and to live code with it.
|
||||
|
||||
## Pages
|
||||
|
||||
Navigate between pages with **Ctrl+Left/Right**:
|
||||
Cagire is organized in several views. Navigate between them using **Ctrl+Left/Right/Up/Down**:
|
||||
|
||||
- **Sequencer**: Edit patterns, write Forth scripts, manage playback slots
|
||||
- **Patterns**: Browse and select across 16 banks x 16 patterns
|
||||
- **Engine**: Audio device selection, sample loading, CPU and voice monitoring
|
||||
- **Options**: Application settings
|
||||
- **Dict**: Forth word reference, organized by category
|
||||
- **Help**: Documentation (you are here)
|
||||
- **Sequencer**: Main view. Edit or preview patterns and scripts. Write Forth scripts.
|
||||
- **Patterns**: Project patterns management. 32 banks of 32 patterns per project. Edit pattern properties (name, length, etc).
|
||||
- **Engine**: Internal audio engine management: device selection, sample loading, performance options and voice / state monitoring.
|
||||
- **Options**: General application settings.
|
||||
- **Dict**: Forth word dictionary, organized by category. Learn about the internal programming language and its features.
|
||||
- **Help**: Documentation. This is the page view you are looking at right now.
|
||||
|
||||
## Quick Start
|
||||
|
||||
1. Press **Space** to start the transport
|
||||
2. Use **arrow keys** to navigate steps
|
||||
3. Press **Tab** to focus the editor
|
||||
4. Write a Forth script (e.g. `/sound/sine`)
|
||||
5. Press **Ctrl+E** to compile
|
||||
6. Press **Tab** to return to the sequencer
|
||||
7. Press **Enter** to activate the step
|
||||
8. Press **g** to queue the pattern to a slot
|
||||
|
||||
## Example Script
|
||||
|
||||
A step that plays a filtered saw with reverb:
|
||||
|
||||
```
|
||||
"saw" s c4 note 0.5 dur 0.3 decay
|
||||
0.6 gain 2000 lpf 0.4 lpq
|
||||
0.3 verb 2.0 verbdecay .
|
||||
```
|
||||
|
||||
A rhythmic pattern using subdivisions and probability:
|
||||
|
||||
```
|
||||
"kick" s 0.8 gain .
|
||||
div
|
||||
"hat" s < 0.3 0.5 0.7 > gain . .
|
||||
~
|
||||
{ "snare" s 0.6 gain . } often
|
||||
```
|
||||
|
||||
## Concepts
|
||||
|
||||
**Banks and Patterns**: 16 banks of 16 patterns each. Each pattern has up to 32 steps with configurable length and speed.
|
||||
|
||||
**Slots**: 8 concurrent playback slots. Queue patterns into slots with **g**. Slot changes are quantized to bar boundaries.
|
||||
|
||||
**Ableton Link**: Cagire syncs tempo and phase with other Link-enabled applications on your network.
|
||||
|
||||
**Forth**: The scripting language used in each step. Open the **Dict** page to browse all available words.
|
||||
Have fun with Cagire! Remember that live coding is all about experimentation and exploration!
|
||||
|
||||
Reference in New Issue
Block a user