mlua-pulse 0.1.0

# 生成器目录


## 你会学到什么


- 使用 `pulse.generators()` 查看 50+ 生成器。
- 使用 `pulse.generator_info(name)` 理解参数和输出类型。
- 区分数学、混沌、文本、矩阵、音乐和节奏生成器。
- 把生成器当成素材来源，而不是自动作曲按钮。

## 适合谁读


想用素数、斐波那契、L 系统、元胞自动机、混沌映射或节奏算法生成音乐材料的用户读本章。

## 前置知识


- [音乐理论](../01-lua-composition/theory.md)
- [映射方法](mapping.md)

## 心智模型


生成器产生“材料”，映射层把材料变成音高、时值、力度、声像或效果参数。不要直接把一串巨大数字当频率；先约束范围，再映射到音乐语境。

```text
generate -> normalize / map_to_scale -> sequence / drum_grid -> phrase -> song
```

生成器输出可能是 number array、integer array、matrix 或 text。不同输出适合不同用途：数列适合旋律和时值，矩阵适合鼓型和纹理，文本适合结构展开。

## 最小可运行例子


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

local fib = pulse.generate("fibonacci", { length = 8 })
local notes = pulse.map_to_scale(fib, "major_pentatonic", "C4", 2)
local durations = pulse.normalize(fib, 0.125, 0.5)

local seq = pulse.sequence()
  :notes(notes)
  :durations(durations)
  :instrument("celesta")
  :volume(0.24)

pulse.song():add(seq):export_wav("output/generated.wav", { normalize = "rms" })
```

## 参数和边界


常见家族：

| 家族 | 例子 | 输出倾向 |
| --- | --- | --- |
| 数学 | `fibonacci`、`primes`、`triangular` | 有序整数 |
| 低差异 | `van_der_corput` | 分布均匀的小数 |
| 混沌 | `logistic_map` | 有界但变化丰富 |
| 文本 | `l_system`、`l_system_values` | 字符串或数值展开 |
| 矩阵 | `cellular_automaton` | 多行图案 |
| 音乐 | `circle_of_fifths`、`harmonic_series`、`undertone_series` | 更接近音高逻辑 |
| 节奏 | `cantor_rhythm_16`、欧几里得相关 | 鼓步号或命中图案 |

`generator_info(name)` 会告诉你 `parameters`。例如 `fibonacci` 需要 `length`，`logistic_map` 需要 `r`、`initial`、`length`，`cellular_automaton` 需要 `rule`、`width`、`generations`。

## 完整生成器清单


`pulse.generators()` 当前返回 140 个生成器名称。带 `_short`、`_classic`、`_long` 等后缀的是免参数预置；不带后缀的基础生成器通常需要传入 `generator_info(name).parameters` 指定的参数。

数学整数序列：

- `fibonacci`, `fibonacci_short`, `fibonacci_medium`, `fibonacci_classic`, `fibonacci_long`, `fibonacci_extended`
- `primes`, `primes_short`, `primes_medium`, `primes_classic`, `primes_long`, `primes_polyrhythm`
- `arithmetic`, `arithmetic_ascending`, `arithmetic_evens`, `arithmetic_odds`, `arithmetic_fives`, `arithmetic_whole_tone`, `arithmetic_chromatic`
- `geometric`, `geometric_doubling`, `geometric_tripling`, `geometric_exponential`, `geometric_moderate`, `geometric_aggressive`
- `triangular`, `triangular_short`, `triangular_classic`, `triangular_extended`
- `powers_of_two`, `powers_of_two_short`, `powers_of_two_classic`, `powers_of_two_extended`, `powers_of_two_byte`
- `collatz`, `collatz_short`, `collatz_medium`, `collatz_classic`, `collatz_dramatic`, `collatz_epic`, `collatz_sparse`
- `lucas`, `lucas_short`, `lucas_classic`, `lucas_extended`
- `catalan`, `catalan_short`, `catalan_classic`, `catalan_extended`
- `padovan`, `padovan_short`, `padovan_classic`, `padovan_extended`
- `pell`, `pell_short`, `pell_classic`, `pell_extended`
- `pentagonal`, `pentagonal_short`, `pentagonal_classic`, `pentagonal_extended`

生成式、混沌、文本和矩阵：

- `random_walk`, `random_walk_short`, `random_walk_classic`, `random_walk_long`, `random_walk_large_steps`
- `bounded_walk`, `bounded_walk_classic`, `bounded_walk_narrow`, `bounded_walk_wide`
- `logistic_map`, `logistic_ordered`, `logistic_oscillating`, `logistic_edge_of_chaos`, `logistic_chaotic`, `logistic_classic`
- `tent_map`, `tent_chaotic`, `tent_moderate`, `tent_mild`
- `sine_map`, `sine_smooth`, `sine_chaotic`, `sine_gentle`
- `thue_morse`, `thue_morse_short`, `thue_morse_classic`, `thue_morse_extended`
- `recaman`, `recaman_short`, `recaman_classic`, `recaman_long`, `recaman_epic`
- `van_der_corput`, `van_der_corput_short`, `van_der_corput_classic`, `van_der_corput_long`, `van_der_corput_ternary`, `van_der_corput_pentary`
- `perlin_noise`, `perlin_smooth_drift`, `perlin_classic`, `perlin_rich_texture`, `perlin_fast_modulation`, `perlin_ambient_pad`
- `l_system`, `l_system_values`, `l_system_fibonacci`, `l_system_thue_morse`, `l_system_cantor`, `l_system_binary_tree`, `l_system_classic`
- `cellular_automaton`, `cellular_rule30`, `cellular_rule110`, `cellular_rule90`, `cellular_rule184`, `cellular_classic`
- `cantor_set`, `cantor_rhythm_16`, `cantor_rhythm_27`, `cantor_rhythm_9`, `cantor_rhythm_81`
- `markov`, `markov_c_major_melody`, `markov_up_down`

音乐理论和律动生成：

- `circle_of_fifths`, `circle_of_fourths`, `harmonic_series`, `undertone_series`, `golden_ratio`
- `golden_sections`, `pythagorean_tuning`, `just_intonation_major`, `just_intonation_minor`
- `euclidean`, `euclidean_pattern`, `golden_ratio_rhythm`, `shepard_tone`, `circle_map`

## 生成器参数速查


| 参数组 | 生成器 | 参数 |
| --- | --- | --- |
| 长度型整数序列 | `fibonacci`, `primes`, `triangular`, `powers_of_two`, `lucas`, `catalan`, `padovan`, `pell`, `pentagonal`, `thue_morse`, `recaman`, `undertone_series`, `golden_ratio`, `pythagorean_tuning` | `length` |
| 等差序列 | `arithmetic` | `start`, `step`, `length` |
| 等比序列 | `geometric` | `start`, `ratio`, `length` |
| Collatz | `collatz` | `start`, `max_terms` |
| 随机游走 | `random_walk` | `start`, `step`, `steps` |
| 有界随机游走 | `bounded_walk` | `start`, `step`, `min`, `max`, `steps` |
| 混沌映射 | `logistic_map`, `sine_map` | `r`, `initial`, `length` |
| Tent map | `tent_map` | `mu`, `initial`, `length` |
| 低差异序列 | `van_der_corput` | `length`, `base` |
| Perlin 噪声 | `perlin_noise` | `seed`, `frequency`, `octaves`, `persistence`, `length` |
| L-system 文本 | `l_system` | `axiom`, `rules`, `iterations` |
| L-system 数值化 | `l_system_values` | `pattern` |
| 元胞自动机 | `cellular_automaton` | `rule`, `width`, `generations` |
| Cantor set | `cantor_set` | `iterations`, `resolution` |
| 五度/四度循环 | `circle_of_fifths`, `circle_of_fourths` | `length`, `start` |
| 泛音列 | `harmonic_series` | `fundamental`, `length` |
| 黄金分割 | `golden_sections` | `value`, `divisions` |
| 欧几里得节奏 | `euclidean`, `euclidean_pattern` | `pulses`, `steps` |
| 黄金比例节奏 | `golden_ratio_rhythm` | `steps` |
| Shepard tone | `shepard_tone` | `length`, `steps_per_octave`, `ascending` |
| Circle map | `circle_map` | `omega`, `k`, `initial`, `iterations` |

## 输出类型说明


| 输出类型 | 含义 | 常见用途 |
| --- | --- | --- |
| `integers` | 整数数组 | 映射到音阶级数、鼓步偏移、和弦选择。 |
| `numbers` | 浮点数组 | 映射到时值、音量、声像、滤波 cutoff。 |
| `steps` | 0 起始步号数组 | 直接喂给 `drum_grid:sound(name, steps)`。 |
| `integer_matrix` | 整数矩阵 | 元胞自动机图案、鼓组纹理、分层触发。 |
| `text` | 文本 | L-system 结构展开，再用 `l_system_values` 转成数列。 |

## 常见陷阱


生成器长度不要一开始就很大。8、16、32 是更好的试验长度。太长的随机感材料会让旋律失去记忆点。

不要把生成值直接当 duration。先用 `pulse.normalize(values, 0.125, 0.5)` 限制范围，避免极短音造成噪声感，或极长音拖垮结构。

不要让生成器控制所有参数。通常让它控制一两个维度就够了，例如音高和时值，其他维度手写。

## 进阶用法


把生成器放在“装饰层”往往更自然。主旋律保持人写的动机，生成器负责琶音、反旋律、鼓点变化或滤波 cutoff。这样音乐既有结构又有变化。

你也可以先生成多个候选，再手动挑选。生成式编曲最重要的不是全自动，而是快速得到可编辑材料。

## 相关章节


- [映射方法](mapping.md)
- [生成配方](recipes.md)
- [音乐理论](../01-lua-composition/theory.md)
- [Lua API](../06-reference/lua-api.md)