# UzuParser
Parser for Uzu pattern mini-notation, used in live coding and algorithmic music generation.
## Overview
UzuParser converts text-based pattern notation into structured, timed musical events. It's designed for live coding environments and algorithmic music systems, providing a simple yet expressive syntax for creating rhythmic and melodic patterns.
## Installation
Add `uzu_parser` to your dependencies in `mix.exs`:
```elixir
def deps do
[
{:uzu_parser, "~> 0.1.0"}
# Or for local development:
# {:uzu_parser, path: "../uzu_parser"}
]
end
```
## Quick Start
```elixir
# Parse a simple pattern
UzuParser.parse("bd sd hh sd")
# => [
# %UzuParser.Event{sound: "bd", time: 0.0, duration: 0.25},
# %UzuParser.Event{sound: "sd", time: 0.25, duration: 0.25},
# %UzuParser.Event{sound: "hh", time: 0.5, duration: 0.25},
# %UzuParser.Event{sound: "sd", time: 0.75, duration: 0.25}
# ]
```
## Syntax
### Basic Sequences
Space-separated sounds are evenly distributed across one cycle (0.0 to 1.0):
```elixir
UzuParser.parse("bd sd hh sd") # 4 events at times 0.0, 0.25, 0.5, 0.75
```
### Rests
Use `~` for silence:
```elixir
UzuParser.parse("bd ~ sd ~") # kick and snare on alternating beats
```
### Subdivisions
Brackets create faster divisions within a step:
```elixir
UzuParser.parse("bd [sd sd] hh") # snare plays twice as fast
UzuParser.parse("bd [sd hh cp]") # three sounds in the time of one step
```
### Repetition
Asterisk multiplies elements:
```elixir
UzuParser.parse("bd*4") # equivalent to "bd bd bd bd"
UzuParser.parse("bd*2 sd") # two kicks, one snare
```
### Sample Selection
Colon selects different samples/variations:
```elixir
UzuParser.parse("bd:0") # kick drum, sample 0
UzuParser.parse("bd:1 bd:2") # different kick drum samples
UzuParser.parse("bd:0*4") # repeat sample 0 four times
UzuParser.parse("bd:0 sd:1 hh:2") # each sound uses a different sample
```
### Polyphony (Chords)
Comma within brackets plays multiple sounds simultaneously:
```elixir
UzuParser.parse("[bd,sd]") # kick and snare together
UzuParser.parse("[bd,sd,hh]") # three sounds at once
UzuParser.parse("bd [sd,hh] cp") # chord on second beat
UzuParser.parse("[bd:0,sd:1]") # chord with sample selection
```
### Random Removal (Probability)
Question mark adds probability - events may or may not play:
```elixir
UzuParser.parse("bd?") # 50% chance to play
UzuParser.parse("bd?0.25") # 25% chance to play
UzuParser.parse("bd sd? hh") # only sd is probabilistic
UzuParser.parse("bd:0?0.75") # sample selection + probability
```
The parser stores probability in the event's `params` field. The playback system decides whether to play each event based on this value.
### Elongation (Temporal Weight)
At sign specifies relative duration/weight of events:
```elixir
UzuParser.parse("bd@2 sd") # kick twice as long as snare (2/3 vs 1/3)
UzuParser.parse("[bd sd@3 hh]") # snare 3x longer than bd and hh
UzuParser.parse("bd@1.5 sd") # fractional weights supported
```
Events are assigned time and duration proportionally based on their weights. Default weight is 1.0 if not specified.
### Replication
Exclamation mark repeats events (similar to `*` but clearer intent):
```elixir
UzuParser.parse("bd!3") # three bd events
UzuParser.parse("bd!2 sd") # two kicks, one snare
UzuParser.parse("[bd!2 sd]") # replication in subdivision
```
Note: In this parser, `!` and `*` produce identical results. Both create separate steps rather than subdividing time.
### Random Choice
Pipe randomly selects one option per evaluation:
```elixir
UzuParser.parse("bd|sd|hh") # pick one each time
UzuParser.parse("[bd|cp] sd") # randomize first beat
UzuParser.parse("bd:0|sd:1") # with sample selection
```
The parser stores all options in the event's `params` field. The playback system decides which option to play using random selection.
### Alternation
Angle brackets cycle through options sequentially:
```elixir
UzuParser.parse("<bd sd hh>") # bd on cycle 1, sd on 2, hh on 3, repeats
UzuParser.parse("<bd sd> hh") # alternate kick pattern
UzuParser.parse("<bd:0 sd:1>") # with sample selection
```
The parser stores all options in the event's `params` field. The playback system uses the cycle number to select which option to play.
### Complex Patterns
Combine features for expressive patterns:
```elixir
# Realistic drum pattern
UzuParser.parse("bd sd [hh hh] sd")
# Layered pattern with repetition and subdivisions
UzuParser.parse("bd*4 ~ [sd sd] ~")
# Nested subdivisions and rests
UzuParser.parse("[bd ~ sd ~] hh")
```
## Event Structure
Each parsed event contains:
- `sound` - The sound/sample name (string)
- `sample` - Sample number (integer >= 0, or nil for default)
- `time` - Position in the cycle (0.0 to 1.0)
- `duration` - How long the event lasts (0.0 to 1.0)
- `params` - Additional parameters (map, for future extensions)
```elixir
%UzuParser.Event{
sound: "bd",
sample: 0,
time: 0.0,
duration: 0.25,
params: %{}
}
```
## Future Features
- Parameters: `"bd|gain:0.8|speed:2"`
- Euclidean rhythms: `"bd(3,8)"` (3 hits in 8 steps)
## Pattern Transformations
For pattern transformations like `fast`, `slow`, `rev`, `stack`, `cat`, `every`, and `jux`, see [UzuPattern](https://github.com/rpmessner/uzu_pattern) - the pattern orchestration library that builds on UzuParser.
## Ecosystem Role
UzuParser is part of the Elixir music ecosystem:
```
┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐
│ UzuParser │────▶│ UzuPattern │────▶│ Waveform │
│ (parsing) │ │ (transforms) │ │ (audio) │
│ │ │ │ │ │
│ • parse/1 │ │ • Pattern struct│ │ • OSC │
│ • mini-notation │ │ • fast/slow/rev │ │ • SuperDirt │
│ • [%Event{}] │ │ • stack/cat │ │ • MIDI │
│ │ │ • every/when │ │ • scheduling │
│ │ │ • query/2 │ │ │
└─────────────────┘ └─────────────────┘ └─────────────────┘
```
- **UzuParser**: Parses mini-notation strings into event lists
- **UzuPattern**: Applies transformations to patterns (fast, slow, rev, stack, cat, every, jux)
- **Waveform**: Handles audio output via OSC/SuperDirt/MIDI
## Development
```bash
# Run tests
mix test
# Generate documentation
mix docs
# Format code
mix format
```
## License
MIT License - See LICENSE for details
## Credits
Inspired by the pattern mini-notation from [TidalCycles](https://tidalcycles.org/) and [Strudel](https://strudel.cc/).
