version: "1.0.1" name: pattrns description: Guide for creating generative, emergent music with Pattrns, the Lua-based pattern sequencing engine for Renoise. Use when composing algorithmic patterns, generating evolving breakbeats/rhythms, creating generative melodies/harmonies, designing textures, or working with euclidean rhythms and live coding patterns. Covers breakbeat/jungle/DnB, IDM/experimental, jazz, industrial/trip-hop, and ambient styles.

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:

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):

pulse = pulse.euclidean(7, 16)  -- 7 hits distributed in 16 steps

Scale-Based Melodies:

local s = scale("c4", "minor")
event = s.notes  -- Use scale notes as sequence

Random Generation with Control:

event = function(context)
  local notes = scale("c4", "pentatonic minor").notes
  return notes[math.random(#notes)]
end

Tidal Cycles Mini-Notation:

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:

pulse = {1, 0, 1, 1, 0, 1, 0, 0}  -- Hand-crafted rhythm

Euclidean Distribution:

pulse = pulse.euclidean(5, 8)     -- Algorithmic rhythm

Dynamic/Generative:

pulse = function(context)
  return math.random() > 0.5      -- Probabilistic rhythm
end

Subdivisions (Cramming):

pulse = {1, {1, 1, 1}, 1, 0}      -- Quarter + triplet + quarter + rest

3. Design Note Generation (Event)

Create melodic/harmonic content:

Static Sequence:

event = {"c4", "e4", "g4", "b4"}

Scale-Based:

local s = scale("c4", "minor")
event = function(context)
  return s.notes[math.imod(context.step, #s.notes)]
end

Chord Progressions:

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

Generative/Evolving:

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:

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:

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:

-- 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:

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:

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:

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:

-- 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 grooves, dark textures
• Ambient: Slow evolution, drones, sparse atmospheres

Search patterns:

• grep -i "breakbeat\|jungle\|dnb" references/genre_recipes.md
• grep -i "idm\|experimental\|glitch" references/genre_recipes.md
• grep -i "jazz\|swing\|walking" references/genre_recipes.md

API Quick Reference (references/api_quick_reference.md)

Load when needing:

• Function signatures and parameters
• Available scale modes
• Context object properties
• Utility functions
• Common code patterns
• Workflow tips and gotchas

Pattern Templates

The assets/ directory contains starter templates for common patterns:

• euclidean_drum.lua: Euclidean-based drum pattern
• generative_melody.lua: Scale-based melody with constraints
• evolving_chord.lua: Slowly evolving chord progression
• texture_cloud.lua: Sparse atmospheric texture

Copy and modify these as starting points.

Best Practices

Start Simple, Add Complexity

1. Begin with static pulse and static event
2. Make one dynamic (usually event first)
3. Add gate for probability/filtering
4. Add parameters for control
5. Layer multiple patterns

Controlled Randomness

Use seeded random for reproducibility:

event = function(init_context)
  local rand = math.randomstate(12345)  -- Consistent seed
  return function(context)
    return generate_with(rand)
  end
end

State Management

• Global state: Shared across all triggers (use sparingly)
• Local state (in generators): Per-trigger isolation (preferred)
• Use init function + inner function pattern for local state

Performance Optimization

• Cache expensive calculations in init functions
• Use local variables
• Avoid creating tables in inner loops
• Return nil for rests, not 0 or false

Tracker Context for Programmers

• Lua uses 1-based indexing: array[1] is first element
• Use math.imod(step, #array) for array wrapping
• Patterns run in musical time (beats/bars), not CPU time
• BPM and time signature from Renoise project settings

Troubleshooting

Pattern not triggering:

• Check unit is appropriate for tempo
• Verify pulse returns non-zero values
• Check gate (if present) isn't filtering all events

Notes out of key:

• Use scale() to constrain note generation
• Check root note and mode are correct

Pattern too predictable:

• Add randomization with math.random()
• Use euclidean rhythms with different parameters
• Implement constrained random walk for melodies

Pattern too chaotic:

• Use seeded random for consistency
• Add constraints to random generation
• Use scale-based generation for harmonic coherence
• Lower probability in gates

Lua errors:

• Check 1-based indexing
• Verify init function returns inner function for generators
• Use math.imod for array wrapping, not %

Generative Workflow Summary

The power of Pattrns for emergent music:

IDEA → ALGORITHM → PATTERN → EVENTS → AUDIO → RESAMPLE → NEW PATTERN

1. Generate: Create algorithmic patterns with controlled randomness
2. Evolve: Use stateful generators to create evolving material
3. Render: Bounce patterns to audio in Renoise
4. Resample: Chop and manipulate rendered audio
5. Resequence: Create new patterns using resampled material
6. Iterate: Repeat for continuous evolution and emergence

This workflow enables creating "parts" that can be assembled into songs in Renoise or exported to traditional DAWs, with each iteration adding new layers of complexity and emergence.

Resources

references/

Detailed technical documentation and genre-specific recipes. Load as needed:

• core_techniques.md: In-depth technique explanations and code patterns
• genre_recipes.md: Complete examples for different musical styles
• api_quick_reference.md: Function signatures and API reference

assets/

Pattern templates ready to copy and modify:

• Starter templates for common musical tasks
• Genre-specific boilerplate patterns