pattrns

What this skill does

# Pattrns - Generative Music Creation

## Overview

Pattrns is a Lua-based pattern generation engine for Renoise that enables algorithmic, generative music creation. Use this skill when working with Pattrns to create emergent, evolving musical patterns across genres including breakbeat/jungle, IDM, jazz, industrial/trip-hop, and ambient music.

**Core Architecture:** Pattrns separates rhythm from melody through a **Pulse → Gate → Event** pipeline:
- **Pulse**: Defines when events occur (rhythm)
- **Gate**: Optional filter for pulse values (probability, complexity)
- **Event**: Generates notes, chords, or sequences (melody/harmony)

This separation enables powerful generative techniques where rhythms and melodies can evolve independently and be recombined in creative ways.

## When to Use This Skill

Invoke this skill when:
- Creating generative or algorithmic patterns in Renoise
- Working with euclidean rhythms or polyrhythms
- Designing evolving, emergent musical structures
- Generating breakbeats, complex drum patterns, or rhythmic variations
- Creating generative melodies, harmonies, or chord progressions
- Building textural, ambient, or atmospheric patterns
- Using Tidal Cycles mini-notation for pattern creation
- Developing patterns that resample and resequence for iterative composition

## Quick Start

### Basic Pattern Structure

Every Pattrns pattern follows this structure:

```lua
return pattern {
  unit = "1/16",              -- Time grid (1/16, 1/8, 1/4, bars, etc.)
  resolution = 1,             -- Multiplier (2/3 for triplets)
  offset = 0,                 -- Delay pattern start
  repeats = true,             -- Loop pattern
  pulse = {1, 0, 1, 1},      -- Static rhythm array
  event = {"c4", "e4", "g4"} -- Static note sequence
}
```

### Essential Techniques at a Glance

**Euclidean Rhythms** (most common starting point):
```lua
pulse = pulse.euclidean(7, 16)  -- 7 hits distributed in 16 steps
```

**Scale-Based Melodies**:
```lua
local s = scale("c4", "minor")
event = s.notes  -- Use scale notes as sequence
```

**Random Generation with Control**:
```lua
event = function(context)
  local notes = scale("c4", "pentatonic minor").notes
  return notes[math.random(#notes)]
end
```

**Tidal Cycles Mini-Notation**:
```lua
return cycle("kd ~ sn ~, [hh hh]*4"):map({
  kd = "c4 #1",  -- Kick drum
  sn = "c4 #2",  -- Snare
  hh = "c4 #3 v0.5"  -- Hi-hat, quieter
})
```

## Core Workflow

### 1. Choose Musical Goal

Identify what to create:
- **Rhythmic**: Drum pattern, breakbeat, groove
- **Melodic**: Bassline, lead, arpeggio
- **Harmonic**: Chord progression, pad, texture
- **Textural**: Atmosphere, drone, evolving soundscape

### 2. Design Rhythm (Pulse)

Start with rhythmic foundation:

**Static Arrays:**
```lua
pulse = {1, 0, 1, 1, 0, 1, 0, 0}  -- Hand-crafted rhythm
```

**Euclidean Distribution:**
```lua
pulse = pulse.euclidean(5, 8)     -- Algorithmic rhythm
```

**Dynamic/Generative:**
```lua
pulse = function(context)
  return math.random() > 0.5      -- Probabilistic rhythm
end
```

**Subdivisions (Cramming):**
```lua
pulse = {1, {1, 1, 1}, 1, 0}      -- Quarter + triplet + quarter + rest
```

### 3. Design Note Generation (Event)

Create melodic/harmonic content:

**Static Sequence:**
```lua
event = {"c4", "e4", "g4", "b4"}
```

**Scale-Based:**
```lua
local s = scale("c4", "minor")
event = function(context)
  return s.notes[math.imod(context.step, #s.notes)]
end
```

**Chord Progressions:**
```lua
local s = scale("c4", "minor")
event = sequence(
  s:chord("i"),   -- Tonic
  s:chord("iv"),  -- Subdominant
  s:chord("v")    -- Dominant
)
```

**Generative/Evolving:**
```lua
event = function(init_context)
  local state = initial_value
  return function(context)
    -- Update and use state to create evolution
    state = state + delta
    return generate_from(state)
  end
end
```

### 4. Add Variation (Optional Gate)

Filter or modify pulse triggers:

```lua
gate = function(context)
  -- Higher probability on downbeats
  local is_downbeat = (context.pulse_step - 1) % 4 == 0
  local probability = is_downbeat and 0.9 or 0.3
  return math.random() < probability
end
```

### 5. Add Control (Parameters)

Enable live tweaking without code changes:

```lua
parameter = {
  parameter.integer("variation", 1, {1, 4}),
  parameter.number("density", 0.5, {0.0, 1.0}),
}

-- Access in functions
event = function(context)
  local var = context.parameter.variation
  -- Use var to select different patterns
end
```

### 6. Iterate & Evolve

**Workflow for Emergent Music:**
1. Generate pattern → Test in Renoise
2. Render/bounce to audio
3. Resample and chop
4. Create new patterns using resampled material
5. Layer and arrange into parts
6. Repeat process for continuous evolution

## Common Musical Tasks

### Creating Breakbeats

Load `references/genre_recipes.md` and search for "Breakbeat" for complete examples.

**Quick pattern:**
```lua
-- Euclidean-based break
local kick = pulse.euclidean(4, 16)
local snare = pulse.euclidean(3, 16, 2)
local hats = pulse.from{1,0,1,0}:repeat_n(4)

-- Use cycle notation to combine
return cycle("[kd*16], [sn*16], [hh*16]"):map({
  kd = function(ctx) return kick[math.imod(ctx.step,16)] and "c4 #1" end,
  sn = function(ctx) return snare[math.imod(ctx.step,16)] and "c4 #2" end,
  hh = function(ctx) return hats[math.imod(ctx.step,16)] and "c4 #3" end
})
```

### Generative Melodies

Load `references/core_techniques.md` and search for "Constrained Random Walk" or "Scale-Based Generation".

**Quick pattern:**
```lua
return pattern {
  unit = "1/16",
  pulse = pulse.euclidean(7, 16),  -- Rhythmic interest
  event = function(init_context)
    local notes = scale("c4", "pentatonic minor").notes
    local last_idx = 1
    return function(context)
      -- Prefer small intervals (smoother melody)
      local next_idx = last_idx
      while math.abs(next_idx - last_idx) > 2 do
        next_idx = math.random(#notes)
      end
      last_idx = next_idx
      return notes[next_idx]
    end
  end
}
```

### Chord Progressions

Load `references/core_techniques.md` and search for "Chord Progressions".

**Quick pattern:**
```lua
local s = scale("c4", "minor")
return pattern {
  unit = "1/4",  -- Whole notes
  pulse = {1, 1, 1, 1},
  event = sequence(
    s:chord("i", 3),   -- i minor
    s:chord("iv", 3),  -- iv minor
    s:chord("v", 3),   -- v minor
    s:chord("i", 3)    -- i minor
  )
}
```

### Evolving Textures

Load `references/genre_recipes.md` and search for "Ambient" or "Textural".

**Quick pattern:**
```lua
return pattern {
  unit = "1/16",
  pulse = function(context)
    return math.random() > 0.85  -- Sparse
  end,
  event = function(context)
    local notes = scale("c4", "phrygian").notes
    return note(notes[math.random(#notes)])
      :volume(0.2 + math.random() * 0.3)
      :delay(math.random() * 0.5)
      :panning(math.random() * 2 - 1)
  end
}
```

### Polyrhythms

Load `references/core_techniques.md` and search for "Polyrhythms".

**Quick pattern:**
```lua
-- 3:4:5 polyrhythm
cycle("[c4*3]/4, [e4*4]/4, [g4*5]/4")
```

## Key Techniques Reference

For detailed explanations and complete code examples, load these reference files:

### Core Techniques (`references/core_techniques.md`)
Load when working with:
- Euclidean rhythms and pulse operations
- Randomization and controlled chaos
- Scale-based generation
- Pattern evolution and stateful generators
- Polyrhythms and unusual time signatures
- Note transformations
- Tidal Cycles mini-notation
- Texture generation

Search patterns:
- `grep -i "euclidean" references/core_techniques.md`
- `grep -i "random" references/core_techniques.md`
- `grep -i "scale" references/core_techniques.md`

### Genre-Specific Recipes (`references/genre_recipes.md`)
Load when creating:
- **Breakbeat/Jungle/DnB**: Complex breaks, swing, reese bass
- **IDM/Experimental**: Glitchy effects, algorithmic complexity
- **Jazz**: Swing, walking bass, chord substitutions
- **Industrial/Trip-Hop**: Heavy groove