mlua-pulse 0.1.0

# 节奏与鼓机


## 你会学到什么


- 使用 `pulse.drum_grid()` 手动构造鼓步进网格。
- 使用 `pulse.drum_machine("808")` 快速写 808 鼓机 pattern。
- 理解 pattern 字符串和 0 起始步号。
- 用欧几里得节奏和命名节奏生成稳定律动。

## 适合谁读


想让作品“站起来”的用户应该读本章。旋律可以很简单，但没有节奏支撑的 loop 往往听起来像练习片段。

## 前置知识


- [快速开始](getting-started.md)
- [序列、乐句与编排](arrangement.md)

## 心智模型


鼓网格是一条固定步数的时间线。16 步常表示一小节十六分音符；第 0 步是小节开头。pattern 字符串里的 `x`、`X`、`1`、`*` 表示命中，`-` 或其他空字符表示休止。

808 鼓机是便捷构建器。它不是另一套渲染系统，而是帮你把 kick、snare、hihat、clap、open hat 等 pattern 组合成 `DrumGrid`。

## 最小可运行例子


```lua
local pulse = require("pulse")

local beat = pulse.drum_machine("808")
  :steps(16)
  :step_duration(0.125)
  :kick("x---x---x---x---")
  :snare("----x-------x---")
  :hihat("x-x-x-x-x-x-x-x-")
  :grid()
  :volume(0.55)
  :effect("compressor", "drum_bus")

pulse.song()
  :tempo(120)
  :add_drum_grid(beat)
  :master_effect("limiter", "standard")
  :export_wav("output/drums.wav", { normalize = "rms" })
```

## 参数和边界


`DrumGrid:steps(n)` 设置步数，必须大于 0。`:step_duration(seconds)` 设置每步长度，必须大于 0。`:sound(name, pattern)` 接受鼓名和 pattern，鼓名可用 `pulse.drums()` 查询。

数组 pattern 使用 0 起始步号：

```lua
pulse.drum_grid()
  :steps(16)
  :sound("kick_808", {0, 4, 8, 12})
```

字符串 pattern 的第一个字符同样对应第 0 步：

```lua
:sound("snare_808", "----x-------x---")
```

`pulse.euclidean(4, 16)` 返回 `{0, 4, 8, 12}` 这种步号数组，`pulse.euclidean_pattern(4, 8)` 返回二进制 pattern 数组。`pulse.pattern("tresillo")` 返回命名节奏。

## 完整鼓声清单


`pulse.drums()` 当前返回基础鼓声和分层鼓声别名。基础鼓声解析为一个 `tunes` 鼓类型；分层鼓声会在同一步触发多个鼓类型，用来快速获得更厚的 kick、snare、clap、hat 或 crash。

Kick、低频和冲击：

- `kick`, `kick_808`, `sub_kick`, `kick_909`, `kick_tight`, `kick_deep`
- `kick_acoustic`, `kick_click`, `bass_drop`, `boom`

Snare、clap、rim 和反向军鼓：

- `snare`, `snare_808`, `snare_909`, `rimshot`, `side_stick`, `snare_rim`
- `snare_tight`, `snare_loose`, `snare_piccolo`, `reverse_snare`
- `clap`, `clap_808`, `clap_dry`, `clap_room`, `clap_group`, `clap_snare`, `clap_909`
- `rim_909`

Hi-hat、ride、crash 和镲片：

- `hihat_closed`, `hihat_open`, `hihat_808_closed`, `hihat_808_open`, `hihat_pedal`, `hihat_half_open`
- `hihat_sizzle`, `hihat_909_closed`, `hihat_909_open`
- `crash`, `crash_2`, `crash_short`, `ride`, `ride_bell`, `ride_tip`
- `china`, `splash`, `reverse_cymbal`, `cymbal_swell`

Tom、定音鼓和电子 tom：

- `tom`, `tom_high`, `tom_low`, `floor_tom_low`, `floor_tom_high`
- `tom_808_low`, `tom_808_mid`, `tom_808_high`, `timpani`

手打、世界打击和小打：

- `cowbell`, `cowbell_808`, `cowbell_909`, `claves`, `clave_808`, `triangle`
- `wood_block`, `wood_block_high`, `tambourine`, `shaker`, `egg_shaker`, `tube_shaker`
- `cabasa`, `guiro_short`, `guiro_long`, `vibraslap`, `agogo_high`, `agogo_low`
- `timbale_high`, `timbale_low`, `conga_high`, `conga_low`, `bongo_high`, `bongo_low`
- `djembe`, `tabla_bayan`, `tabla_dayan`, `cajon`, `fingersnap`, `maracas`
- `castanet`, `sleigh_bells`, `gong`, `chimes`, `laser_zap`, `white_noise_hit`, `stick_click`

分层鼓声：

- `kick_808_deep_layer`：`kick_808` 加 `sub_kick`，适合 808 低频主 kick。
- `kick_909_click_layer`：`kick_909` 加 `kick_click`，适合更有点击头部的电子 kick。
- `kick_acoustic_room_layer`：`kick_acoustic` 加 `boom`，适合偏现场的低频冲击。
- `snare_808_body_layer`：`snare_808` 加 `snare_loose`，增强身体感。
- `snare_909_snap_layer`：`snare_909` 加 `snare_rim`，增强啪声和切入感。
- `snare_piccolo_clap_layer`：`snare_piccolo` 加 `clap_dry`，适合小清新或流行 backbeat。
- `clap_808_stack_layer`：`clap_808` 加 `clap_group`，更厚的 808 clap。
- `clap_909_wide_layer`：`clap_909` 加 `clap_room`，更宽的 909 clap。
- `hihat_808_sizzle_layer`：`hihat_808_closed` 加 `hihat_sizzle`，增强高频空气感。
- `hihat_909_sizzle_layer`：`hihat_909_closed` 加 `hihat_sizzle`，适合更硬的电子律动。
- `tom_808_stack_layer`：`tom_808_low` 加 `tom_808_mid`，适合 fill 和 808 tom 滑动感。
- `crash_swell_layer`：`crash` 加 `cymbal_swell`，适合段落进入和过门。

## 常见陷阱


最容易错的是步号起点。Lua 数组索引是 1 起始，但鼓步号是 0 起始。`{0}` 才是第一拍，`{1}` 是第二个步格。

鼓太刺耳时，先降音量和 velocity，再考虑压缩。压缩器会让鼓更稳定，但过度压缩会把噪声和高频也抬起来。

不要给 kick 和低频鼓声加太湿的 reverb。低频空间太多会让导出糊成一团。

## 进阶用法


分层鼓别名可以增强冲击力：

```lua
local hard = pulse.drum_grid()
  :steps(16)
  :step_duration(0.125)
  :sound("kick_808_deep_layer", "x---x-----x-x---")
  :sound("snare_808_body_layer", "----x-------x---")
  :sound("clap_909_wide_layer", "----x-------x---")
  :sound("hihat_808_sizzle_layer", "x-x-x-x-x-x-x-x-")
  :volume(0.5)
```

欧几里得节奏适合做附加打击乐，例如 5 次命中分布到 16 步，再和标准 backbeat 叠加。

## 相关章节


- [完整作品工作流](full-song-workflows.md)
- [混音](../02-sound-design/mixing.md)
- [生成器配方](../03-generation/recipes.md)
- [Lua API](../06-reference/lua-api.md)