# UzuPattern

Pattern library for TidalCycles/Strudel-style live coding in Elixir.

UzuPattern provides a query-based pattern system with time transformations, structure manipulation, conditional application, signal patterns for modulation, and effect parameters. It uses exact rational arithmetic for precise timing and integrates mini-notation parsing from [UzuParser](https://github.com/rpmessner/uzu_parser).

## Installation

```elixir
def deps do
  [
    {:uzu_pattern, "~> 0.8.0"}
  ]
end
```

## Quick Start

```elixir
# Parse mini-notation into a pattern
pattern = UzuPattern.parse("bd sd hh cp")

# Query events for a specific cycle
haps = UzuPattern.query(pattern, 0)

# Apply transformations
pattern
|> Pattern.fast(2)
|> Pattern.rev()
|> Pattern.every(4, &Pattern.slow(&1, 2))
```

## Core Concepts

### Patterns as Query Functions

Patterns are query functions, not static event lists. This enables cycle-aware transformations:

```elixir
pattern = UzuPattern.parse("bd sd") |> Pattern.every(2, &Pattern.rev/1)

Pattern.query(pattern, 0)  # Cycle 0: reversed
Pattern.query(pattern, 1)  # Cycle 1: normal
Pattern.query(pattern, 2)  # Cycle 2: reversed
```

### Haps (Events)

Each query returns a list of `Hap` structs containing:
- `whole` - The timespan of the complete event
- `part` - The portion of the event within the queried range
- `value` - Map with `:sound`, `:sample`, and effect parameters
- `context` - Source locations and tags

```elixir
[hap | _] = UzuPattern.query(pattern, 0)
Hap.sound(hap)   # => "bd"
Hap.sample(hap)  # => 0
hap.part.begin   # => Ratio.new(0, 1)  (exact rational)
hap.part.end     # => Ratio.new(1, 4)
```

### Exact Rational Timing

All time values use exact rational arithmetic via the Ratio library. This prevents rhythmic drift and enables precise pattern calculations:

```elixir
# Times are exact fractions, not floats
hap.part.begin  # => Ratio.new(1, 3) not 0.333...

# Conversion to floats only at the scheduling boundary
TimeSpan.begin_float(hap.part)  # => 0.3333333...
```

## Modules

Functions are organized into logical groups:

| Module | Functions |
|--------|-----------|
| **Pattern** | `query`, `events`, `pure`, `silence`, `stack`, `cat`, `slowcat`, `fastcat`, `timeCat` |
| **Pattern.Time** | `fast`, `slow`, `early`, `late`, `ply`, `compress`, `zoom`, `linger`, `inside` |
| **Pattern.Structure** | `rev`, `palindrome`, `mask`, `degrade`, `jux`, `jux_by`, `superimpose`, `off`, `echo`, `striate`, `chop` |
| **Pattern.Conditional** | `every`, `sometimes`, `often`, `rarely`, `almostNever`, `almostAlways`, `iter`, `first_of`, `last_of`, `when_fn`, `chunk` |
| **Pattern.Effects** | `gain`, `pan`, `speed`, `cut`, `room`, `delay`, `lpf`, `hpf`, `set_param` |
| **Pattern.Rhythm** | `euclid`, `euclid_rot`, `swing`, `swing_by` |
| **Pattern.Signal** | `sine`, `saw`, `isaw`, `tri`, `square`, `rand`, `irand`, `range`, `rangex`, `segment` |
| **Pattern.Algebra** | `add`, `sub`, `mul`, `div_op`, `mod`, `pow`, `app_left`, `app_right`, `app_both` |

## Signal Patterns

Signals provide continuous values for modulating parameters:

```elixir
# Modulate filter cutoff with sine wave (200-2000 Hz)
UzuPattern.parse("bd sd hh cp")
|> Pattern.lpf(Signal.sine() |> Signal.range(200, 2000))

# Random gain per cycle
UzuPattern.parse("bd sd")
|> Pattern.gain(Signal.rand() |> Signal.range(0.5, 1.0))

# Stereo panning sweep
UzuPattern.parse("arpy:0 arpy:1 arpy:2 arpy:3")
|> Pattern.pan(Signal.tri() |> Signal.range(-1, 1))

# Discretize signal into stepped values
Signal.saw() |> Signal.segment(8)  # 8 discrete steps per cycle
```

Available waveforms: `sine`, `saw`, `isaw`, `tri`, `square`, `rand`, `irand`

## Effects

All effects accept static values or signal patterns:

```elixir
pattern
|> Pattern.gain(0.8)           # Static gain
|> Pattern.pan(-0.5)           # Static pan (left)
|> Pattern.speed(2)            # Double speed playback
|> Pattern.cut(1)              # Cut group (monophonic)
|> Pattern.room(0.5)           # Reverb send
|> Pattern.delay(0.3)          # Delay send
|> Pattern.lpf(2000)           # Low-pass filter
|> Pattern.hpf(200)            # High-pass filter
|> Pattern.lpf(Signal.sine() |> Signal.range(200, 2000))  # Modulated
```

## Time Transformations

```elixir
Pattern.fast(pattern, 2)              # Double speed
Pattern.slow(pattern, 2)              # Half speed
Pattern.rev(pattern)                  # Reverse
Pattern.early(pattern, 0.25)          # Shift earlier by 1/4 cycle
Pattern.late(pattern, 0.25)           # Shift later by 1/4 cycle
Pattern.ply(pattern, 3)               # Repeat each event 3 times
Pattern.compress(pattern, 0.25, 0.75) # Fit into time window
Pattern.zoom(pattern, 0.5, 1.0)       # Extract and expand portion
Pattern.linger(pattern, 0.25)         # Loop first 1/4 of pattern
Pattern.inside(pattern, 4, &Pattern.rev/1)  # Apply transform at 4x speed
```

## Structure

```elixir
Pattern.stack([p1, p2, p3])           # Layer patterns (simultaneous)
Pattern.cat([p1, p2, p3])             # Sequence patterns (one per cycle)
Pattern.fastcat([p1, p2, p3])         # Sequence within one cycle
Pattern.slowcat([p1, p2, p3])         # Alias for cat
Pattern.timeCat([{3, p1}, {1, p2}])   # Weighted sequence
Pattern.palindrome(pattern)           # Forward then backward
Pattern.jux(pattern, &Pattern.rev/1)  # Stereo split with transform
Pattern.jux_by(pattern, 0.5, fun)     # Partial stereo separation
Pattern.superimpose(pattern, fun)     # Layer with transform
Pattern.off(pattern, 0.125, fun)      # Offset copy with transform
Pattern.echo(pattern, 3, 0.25, 0.8)   # Multiple echoes with decay
Pattern.striate(pattern, 4)           # Slice into 4 parts
Pattern.chop(pattern, 4)              # Chop each event into 4
```

## Conditional

```elixir
Pattern.every(pattern, 4, fun)        # Apply every 4th cycle
Pattern.sometimes(pattern, fun)       # 50% probability
Pattern.often(pattern, fun)           # 75% probability
Pattern.rarely(pattern, fun)          # 25% probability
Pattern.almostNever(pattern, fun)     # 10% probability
Pattern.almostAlways(pattern, fun)    # 90% probability
Pattern.iter(pattern, 4)              # Rotate by 1/4 each cycle
Pattern.first_of(pattern, 4, fun)     # Apply on first of every 4
Pattern.last_of(pattern, 4, fun)      # Apply on last of every 4
Pattern.when_fn(pattern, pred, fun)   # Apply when predicate true
Pattern.degrade(pattern)              # Remove ~50% of events randomly
Pattern.degrade_by(pattern, 0.3)      # Remove ~30% of events
```

## Rhythm

```elixir
Pattern.euclid(pattern, 3, 8)         # 3 hits over 8 steps (Euclidean)
Pattern.euclid_rot(pattern, 3, 8, 2)  # With rotation offset
Pattern.swing(pattern, 2)             # Swing on 8th notes
Pattern.swing_by(pattern, 0.2, 2)     # Swing with specific amount
```

## Pattern Algebra

Combine patterns with arithmetic operations:

```elixir
Pattern.add(p1, p2)       # Add values
Pattern.mul(p1, p2)       # Multiply values
Pattern.app_left(p1, p2)  # Apply structure from left pattern
Pattern.app_right(p1, p2) # Apply structure from right pattern
Pattern.app_both(p1, p2)  # Combine both structures
```

## Mini-Notation Features

The parser supports the full Strudel/Tidal mini-notation:

```elixir
# Basic sequences and rests
"bd sd hh cp"       # Four sounds
"bd ~ sd ~"         # With rests

# Subdivisions
"bd [sd sd] hh"     # Subdivision
"[[bd sd] hh]"      # Nested

# Modifiers
"bd*4"              # Repeat 4 times
"[bd sd]/2"         # Slow by 2
"bd:3"              # Sample 3
"bd?"               # 50% probability
"bd?0.25"           # 25% probability
"bd@2 sd"           # Weight (bd twice as long)
"bd _ sd"           # Elongation

# Polyphony
"[bd,sd,hh]"        # Chord (simultaneous)
"{bd sd, hh hh hh}" # Polymetric

# Alternation
"<bd sd hh>"        # Cycle through options
"bd|sd|hh"          # Random choice

# Euclidean
"bd(3,8)"           # 3 over 8
"bd(3,8,1)"         # With rotation

# Parameters
"bd|gain:0.8|speed:2"
```

## Examples

### Layered Drum Pattern

```elixir
kicks = UzuPattern.parse("bd ~ bd ~")
snares = UzuPattern.parse("~ sd ~ sd")
hats = UzuPattern.parse("[hh hh hh hh]")

Pattern.stack([kicks, snares, hats])
|> Pattern.lpf(Signal.sine() |> Signal.range(800, 4000))
```

### Evolving Pattern

```elixir
UzuPattern.parse("bd sd hh cp")
|> Pattern.every(4, &Pattern.rev/1)
|> Pattern.every(8, &Pattern.fast(&1, 2))
|> Pattern.sometimes(&Pattern.degrade/1)
|> Pattern.gain(Signal.saw() |> Signal.range(0.6, 1.0))
```

### Stereo Arpeggio

```elixir
UzuPattern.parse("arpy:0 arpy:1 arpy:2 arpy:3")
|> Pattern.jux(&Pattern.rev/1)
|> Pattern.lpf(Signal.tri() |> Signal.range(500, 3000))
```

### Polyrhythmic Layers

```elixir
Pattern.stack([
  UzuPattern.parse("bd(3,8)"),
  UzuPattern.parse("sd(5,8)"),
  UzuPattern.parse("hh*8")
])
|> Pattern.every(4, &Pattern.fast(&1, 2))
```

## Related Projects

- [UzuParser](https://github.com/rpmessner/uzu_parser) - Mini-notation parser
- [Waveform](https://github.com/rpmessner/waveform) - Audio playback via SuperCollider/MIDI

## License

MIT License - see [LICENSE](LICENSE) for details.