# Batucada — Brazilian Samba Percussion Ensemble
# Reference: "Samba Batucada Instruments: A Technical Guide" (upbeat.studio),
#            Dr. Jason Koontz / weteachpan.org Brazilian Rhythms guide,
#            "The Samba Batucada" (music notation by Damon Ferrante)
# Simulates a bateria (percussion ensemble) on a single drum kit by layering:
#   Surdo 1 (open bass): beat 1                     → GM note 35 (acoustic bass drum)
#   Surdo 2 (muted bass): beat 3 (mid-bar response) → GM note 36 (bass drum 1)
#   Caixa (snare): ghost-note roll + accents         → GM note 38 (acoustic snare)
#   Tamborim: carreteiro figure (3+3+2+3+3+2)        → GM note 37 (side stick)
#   Repique (tenor drum): call/response fills         → GM note 47 (low-mid tom)
#   Agogô (cowbells): steady syncopated bell pulse    → GM note 56 (cowbell)
# Five groove variations capture different phases of a real bateria performance:
#   full_bateria: all layers — the "cruising" sound of a full ensemble
#   featured_tamborim: tamborim leads with double-hit accents (call figure)
#   repique_call: repique breaks out of the texture for a solo call phrase
#   agogo_drive: agogô bell takes the foreground over a stripped-down backdrop
#   sparse_base: surdo + caixa only — entry feel when the bateria starts

#
# ── Step grid notation ────────────────────────────────────────────────────────
# Each character in a step grid represents one subdivision of the bar.
# Resolution controls how many steps per bar (16 = 16th notes in 4/4; 12 = 16th notes in 6/8).
#
#   X   Strong accent  — velocity = base_velocity × 1.00  (full hit / downbeat)
#   x   Medium accent  — velocity = base_velocity × 0.75  (firm stroke / upbeat)
#   o   Soft hit       — velocity = base_velocity × 0.55  (brush / light touch)
#   g   Ghost note     — velocity = base_velocity × 0.28  (barely audible, mostly felt)
#   .   Rest           — no note fired at this step
#
# Beat positions — 4/4 at resolution 16 (one char per 16th note):
#   pos  0  1  2  3  4  5  6  7  8  9 10 11 12 13 14 15
#        1  e1 +1 a1  2  e2 +2 a2  3  e3 +3 a3  4  e4 +4 a4
#   (1/+/2/+/3/+/4/+ = quarter beats; e = "e of"; a = "and-a of")
#
# Beat positions — 6/8 at resolution 12 (one char per 16th note):
#   pos  0  1  2  3  4  5  6  7  8  9 10 11
#        C1 .  e1 .  a1 .  C2 .  e2 .  a2 .
#   (C1/C2 = compound beat downbeats; each compound beat = 3 eighth notes = 6 steps)
#
# Swing / feel: the 'feel' field shifts odd-indexed steps (1,3,5,7…) forward in time.
#   straight   — no shift (all steps exactly on the grid)
#   swing_soft — odd steps delayed ~16 % of a step (light swing)
#   swing_hard — odd steps delayed ~34 % of a step (jazz/shuffle triplet feel)
#   laid_back  — same as straight with slower humanisation envelope
# ─────────────────────────────────────────────────────────────────────────────

name: Batucada
family: latin
bpm_range: [150, 200]
time_signature: [4, 4]
resolution: 16
feel: straight

instruments:
  surdo_open:  { note: 35, base_velocity: 108, velocity_range: 8,  timing_jitter: 0.010, duration_beats: 0.20 }
  surdo_mute:  { note: 36, base_velocity: 90,  velocity_range: 10, timing_jitter: 0.012, duration_beats: 0.12 }
  caixa:       { note: 38, base_velocity: 72,  velocity_range: 20, timing_jitter: 0.008, duration_beats: 0.08 }
  tamborim:    { note: 37, base_velocity: 90,  velocity_range: 12, timing_jitter: 0.012, duration_beats: 0.07 }
  repique:     { note: 47, base_velocity: 88,  velocity_range: 14, timing_jitter: 0.012, duration_beats: 0.08 }
  agogo:       { note: 56, base_velocity: 88,  velocity_range: 10, timing_jitter: 0.012, duration_beats: 0.07 }
  crash:       { note: 49, base_velocity: 100, velocity_range: 8,  timing_jitter: 0.010, duration_beats: 0.22 }

humanization:
  timing_jitter: 0.010
  velocity_jitter: 16
  velocity_drift: 0.05

sections:
  intro:
    type: count_in
    hits: 4
    note: 37

  groove:
    bars: 1
    variations:
      - name: full_bateria
        weight: 3
        # The full ensemble in motion: all layers present.
        # Surdo interlock: open on beat 1, muted on beat 3 (pos 8).
        # Caixa: ghost roll throughout (gxgx), accented "a" of beats 2 & 4 (pos 7,15).
        # Tamborim carreteiro: 3+3+2+3+3+2 grouping = hits at pos 0,3,5,8,11,13.
        # Agogô: syncopated bell pattern — off the beat pulse (pos 2,6,10,14 = 8th upbeats).
        surdo_open: "X..............."
        surdo_mute: "........X......."
        caixa:      "gxgxgxgXgxgxgxgX"
        tamborim:   "X..X.X..X..X.X.."
        agogo:      "..X...X...X...X."
      - name: featured_tamborim
        weight: 2
        # Tamborim doubles on the first hit of each phrase group (pos 0 and 8) —
        # this "chamada" (call) figure is how the tamborim section signals a section change.
        surdo_open: "X..............."
        surdo_mute: "........X......."
        caixa:      "gxgxgxgXgxgxgxgX"
        tamborim:   "XX.X.X..XX.X.X.."
        agogo:      "..X...X...X...X."
      - name: repique_call
        weight: 2
        # Repique breaks free: it plays an "answer" phrase (syncopated fills)
        # while the surdo and caixa hold the foundation steady.
        surdo_open: "X..............."
        surdo_mute: "........X......."
        caixa:      "gxgxgxgXgxgxgxgX"
        repique:    "X.X.....X.X..X.X"
        agogo:      "..X...X...X...X."
      - name: agogo_drive
        weight: 1
        # Agogô drives the foreground: strong on beat 1 and beat 3 (pos 0,8),
        # medium on upbeats — simulates a larger cowbell ensemble.
        # Caixa pulls back to a sparse ghost/accent pattern.
        surdo_open: "X..............."
        surdo_mute: "........X......."
        caixa:      "g...g...g...gxgX"
        tamborim:   "X..X.X..X..X.X.."
        agogo:      "X.X.X.X.X.X.X.X."
      - name: sparse_base
        weight: 1
        # "Entrada" (entry): surdo and caixa alone — other instruments haven't
        # entered yet. Represents the moment the bateria first starts playing.
        surdo_open: "X..............."
        surdo_mute: "........X......."
        caixa:      "g...g...gxgxgxgX"

  fill:
    bars: 1
    variations:
      - name: virada
        # Classic "virada" (turn-around): caixa crescendo, all landing together.
        # Density doubles each beat: sparse → medium → dense → crash.
        caixa:      "g.g.gxgXXxXxXXXX"
        surdo_open: "X..............."
        surdo_mute: "........X......."
      - name: repique_break
        # Repique leads with a solo call phrase; caixa and surdos drop out briefly,
        # then re-enter on the last two 16th notes for maximum contrast.
        repique:    "X.X.X.X.X.X.X..."
        caixa:      "g.............XX"
        surdo_open: "X..............."
      - name: chamada
        # "Chamada" (call to attention): all instruments together on the clave
        # positions (0,3,5,8,11,13) — sounds like the whole bateria shouting at once.
        surdo_open: "X..X.X..X..X.X.."
        surdo_mute: "X..X.X..X..X.X.."
        tamborim:   "X..X.X..X..X.X.."
        repique:    "X..X.X..X..X.X.."
        caixa:      "X..X.X..X..X.X.."

  crash:
    bars: 1
    variations:
      - name: standard
        crash:      "X..............."
        surdo_open: "X..............."
        surdo_mute: "........X......."
        caixa:      "gxgxgxgXgxgxgxgX"
        agogo:      "..X...X...X...X."

structure:
  fill_every: 4
  break_every: 0
  break_length: 1
  crash_after_fill: true
  dynamic_build: true