# Rhythm and drum patterns

SDK 1.53.0. Generated from the SDK source and its original JSDoc. See the [API index](/docs/sdk-index) for version and source provenance, or the [SDK guide](/docs/sdk) for a first composition.

## `RhythmCycleSpec`

Per-pass variation of a rhythm row (T-1 Cycles).

```ts
export type RhythmCycleSpec = Readonly<{
  pulses?: number;
  rotate?: number;
  repeats?: number;
  probability?: number;
  velocity?: number;
}>;
```

## `RhythmOptions`

Parameters of one generated voice. Every field is optional; DAWN checks
ranges when the song loads. Note values are strings: `"1/16"`, `"1/8t"`.

```ts
export type RhythmOptions = Readonly<{
  /** Steps 1..64, default 16. */
  steps?: number;
  /** Hits 0..steps spread as evenly as possible, default 4. */
  pulses?: number;
  /** Shift the pattern later by this many steps (negative: earlier), like Strudel's `euclidRot`. */
  rotate?: number;
  /** Length of a step, default `"1/16"`. */
  division?: string;
  /** Explicit steps instead of a Euclidean pattern: `x` hit, `X` accent, `.` rest. */
  grid?: string;
  /** Extra triggers after each pulse, 0..16 (T-1 Repeats). Cut off by the next pulse. */
  repeats?: number;
  /** Spacing of the repeats as a note value, default the step (T-1 Time). */
  time?: string;
  /** -1..1: repeats accelerate (<0) or decelerate (>0) (T-1 Pace). */
  pace?: number;
  /** -1..1: repeats fade out (<0) or build up (>0). */
  ramp?: number;
  /** Base velocity 0..1, default 0.8. */
  velocity?: number;
  /** 0..1: how far accented pulses rise toward full velocity. */
  accent?: number;
  /** Accented pulses as E(accents, pulses); default 1 (the first). */
  accents?: number;
  /** Note length in steps, 0.05..4 (T-1 Sustain), default 1. */
  gate?: number;
  /** Every pulse lasts until the next one, like Strudel's `euclidLegato`. */
  legato?: boolean;
  /** Chance 0..1 that a pulse plays; deterministic for a given `seed`. */
  probability?: number;
  /** Integer 0..1000000 choosing which pulses `probability` drops. */
  seed?: number;
  /** -0.5..0.5 of a step: every second step later (>0) or earlier. */
  swing?: number;
  /** -0.5..0.5 of a step: the whole row later or earlier. */
  nudge?: number;
  /** Variations applied on successive passes of the row (T-1 Cycles). */
  cycles?: readonly RhythmCycleSpec[];
}>;
```

## `RhythmSpec`

One generated voice on a track's `rhythm` list. Build with `euclid()` or `grid()`.

```ts
export type RhythmSpec = Readonly<
  RhythmOptions & {
    kind: "rhythm";
    voice: string;
  }
>;
```

## `euclid`

A Euclidean rhythm row: `pulses` hits spread over `steps`, rotated later
by `rotate` steps. Same patterns and rotation direction as Strudel's
`euclid`/`euclidRot` (`euclid("kick", 3, 8)` is `x..x..x.`). DAWN expands
the row into hits when the song loads, so you edit the parameters, not
the notes; the row repeats every `steps` steps to the end of the loop.

```ts
rhythm: [
  euclid("kick", 4, 16),
  euclid("hat", 7, 16, 2, { velocity: 0.5, accent: 0.6, accents: 3 }),
  euclid({ voice: "snare", pulses: 2, steps: 16, rotate: 4 }),
];
```

```ts
export declare function euclid(
  voice:
    | string
    | (RhythmOptions & {
        voice: string;
      }),
  pulses?: number,
  steps?: number,
  rotate?: number | RhythmOptions,
  options?: RhythmOptions,
): RhythmSpec;
```

## `euclidRot`

`euclid(voice, pulses, steps, rotate)` under Strudel's name.

```ts
export declare function euclidRot(
  voice: string,
  pulses: number,
  steps: number,
  rotate: number,
  options?: RhythmOptions,
): RhythmSpec;
```

## `euclidLegato`

A Euclidean row whose hits last until the next one (Strudel `euclidLegato`).

```ts
export declare function euclidLegato(
  voice: string,
  pulses: number,
  steps: number,
  rotate?: number,
  options?: RhythmOptions,
): RhythmSpec;
```

## `grid`

An explicit step row: `grid("snare", "....x.......x...")`. `x` is a
hit, `X` an accented hit, `g` a ghost note (a quarter of the velocity,
never accented) and `f` a flam (the hit plus a half-velocity grace hit a
1/96 note earlier; SDK 1.38.0); `.` or `-` rests. The string's length is
the step count.

```ts
export declare function grid(
  voice: string,
  steps: string,
  options?: RhythmOptions,
): RhythmSpec;
```

## `RHYTHM_KEYS`

Row fields in the order DAWN stores and prints them.

```ts
export declare const RHYTHM_KEYS: readonly string[];
```

## `DrumPattern`

A named starting groove: one rhythm row per voice, ready for a
`instrument: "kit"` track. Rows are Euclidean where the part is
Euclidean and explicit grids otherwise. All patterns are 4/4; `swing`
is already applied to the rows.

```ts
export type DrumPattern = Readonly<{
  name: string;
  label: string;
  tags: readonly string[];
  /** Usual tempo range and a suggested tempo, BPM. */
  tempo: Readonly<{
    min: number;
    max: number;
    bpm: number;
  }>;
  beatsPerBar: number;
  /** Swing of the 16th rows, -0.5..0.5 of a step. */
  swing: number;
  /** A synthesized kit that suits it (see `kit` on `track()`). */
  kit: string;
  rows: readonly RhythmSpec[];
  /**
   * The player's feel (SDK 1.38.0): seeded timing scatter in ms either side
   * and velocity scatter in percent, as a track's `humanize`. DAWN's
   * `/pattern` sets it on a kit track that has no humanize of its own.
   * Absent for machine-tight grooves.
   */
  humanize?: Readonly<{
    timing?: number;
    velocity?: number;
  }>;
}>;
```

## `DRUM_PATTERNS`

The library. Written for DAWN from common knowledge of each style (no
transcriptions): the defining placements of kick, snare and hats, kept
short so they are easy to vary.

```ts
export declare const DRUM_PATTERNS: readonly DrumPattern[];
```

## `findPattern`

The pattern named `name` (case-insensitive), if any.

```ts
export declare function findPattern(name: string): DrumPattern | undefined;
```

## `pattern`

A library pattern's rows, for a kit track's `rhythm`:

```ts
track({
  name: "drums",
  instrument: "kit",
  kit: "lofi",
  rhythm: pattern("boom-bap"),
});
```

Spread it to change or add rows: `[...pattern("house"), euclid("rim", 5, 16)]`.
Rows with the same voice must not repeat, so drop the original first.

```ts
export declare function pattern(name: string): readonly RhythmSpec[];
```
