isobar 技术文档

1. 安装指南

isobar 是一个用于创建和操作音乐模式的 Python 库，专为算法作曲、生成音乐和声音化设计。它使得表达复杂的音乐想法变得快速而简单，并且可以从多种不同的来源发送和接收事件，包括 MIDI、MIDI 文件和 OSC。

安装方式

isobar 可以通过 pip 进行安装，具体命令如下：

pip3 install isobar

安装完成后，您可以通过导入 isobar 模块来开始使用该库。

2. 项目的使用说明

isobar 的核心元素是 Timeline，它可以控制自己的节奏或与外部时钟同步。在 Timeline 上，您可以调度 Pattern，这些模式可以是音符序列、控制事件、程序更改或通过 lambda 函数生成的其他任意事件。模式用作生成事件的模板，这些事件会在 OutputDevice 上触发音符或控制更改。

示例代码

以下是一个简单的示例，展示了如何使用 isobar 创建一个几何序列并在小调音阶上播放：

from isobar import *

# 创建一个小调音阶上的几何序列
arpeggio = PSeries(0, 2, 6)
arpeggio = PDegree(arpeggio, iso.Scale.minor) + 72
arpeggio = PPingPong(arpeggio)
arpeggio = PLoop(arpeggio)

# 创建一个速度序列，每第4个音符有强调，并添加随机漫步以创建动态变化
amplitude = PSequence([50, 35, 25, 35]) + PBrown(0, 1, -20, 20)

# 创建一个时间线，设置速度为 120 BPM
timeline = Timeline(120)

# 调度事件，属性由模式对象生成
timeline.schedule({
    "note": arpeggio,
    "duration": 0.25,
    "amplitude": amplitude
})

# 运行时间线
timeline.run()

3. 项目 API 使用文档

isobar 提供了丰富的 API 来生成和操作音乐模式。以下是一些常用的模式类及其功能：

核心模式类 (CORE)

• Pattern: 所有模式生成器的抽象超类。
• PConstant: 返回一个固定值。
• PRef: 包含对另一个模式的引用，可以动态替换。
• PFunc: 返回由函数生成的值。
• PArrayIndex: 从数组中请求指定的索引。
• PDict: 从字典数组或字典的数组中构造模式。
• PDictKey: 从字典中请求指定的键。
• PConcatenate: 连接多个序列的输出。

标量模式类 (SCALAR)

• PChanged: 如果输入模式的值发生变化，则输出 1。
• PDiff: 输出输入模式的当前值与先前值之间的差异。
• PSkipIf: 如果 skip 为假，则返回 input；否则返回 None。
• PNormalise: 将 input 自适应地归一化到 [0..1] 的线性范围。
• PMap: 将任意函数应用于输入模式。
• PMapEnumerated: 将任意函数应用于输入，并传递一个计数器。
• PScaleLinLin: 将 input 从线性范围 [a,b] 映射到线性范围 [c,d]。
• PScaleLinExp: 将 input 从线性范围 [a,b] 映射到指数范围 [c,d]。
• PRound: 将 input 四舍五入到 N 位小数。
• PScalar: 将元组和列表减少为单个标量值。
• PWrap: 将输入音符值包装在 <min>, <max> 之间。
• PIndexOf: 在 <list> 中查找 pattern 中项目的索引。

序列模式类 (SEQUENCE)

• PSeries: 算术序列，从 start 开始，以 step 递增。
• PRange: 类似于 PSeries，但指定最大值/步长值。
• PGeom: 几何序列，从 start 开始，以 step 相乘。
• PImpulse: 每 <period> 个事件输出 1，否则输出 0。
• PLoop: 重复有限 pattern 进行 n 次重复。
• PPingPong: 将输入模式来回播放 N 次。
• PCreep: 循环 length 音符段，在 repeats 次重复后前进 creep 音符。
• PStutter: 将 pattern 的每个音符播放 count 次。
• PSubsequence: 返回输入模式的有限子序列。
• PReverse: 反转有限序列。
• PReset: 每当 trigger 为真时重置 pattern。
• PCounter: 每当 trigger 过零时，计数器加 1。
• PCollapse: 跳过 input 中的任何休止符。
• PNoRepeats: 跳过 input 中的重复值。
• PPad: 用休止符填充 pattern，直到达到长度 length。
• PPadToMultiple: 用休止符填充 pattern，直到其长度可被 multiple 整除。
• PArpeggiator: 琶音器。
• PEuclidean: 生成欧几里得节奏。
• PPermut: 生成 count 个输入项目的每个排列。
• PPatternGeneratorAction: 每当其模式耗尽时，通过调用 <fn> 请求新模式。
• PSequenceAction: 遍历数组，执行函数并重复。

随机模式类 (CHANCE)

• PWhite: 在 min 和 max 之间的白噪声。
• PBrown: 布朗噪声。
• PCoin: 硬币抛掷，根据 probability 返回 0 或 1。
• PWalk: 在列表中随机漫步。
• PChoice: 从 values 中随机选择一个元素，可选地按 weights 加权。
• PSample: 从 values 中随机选择多个元素。

4. 项目安装方式

isobar 的安装非常简单，只需使用 pip 命令即可完成安装：

pip3 install isobar

安装完成后，您可以通过导入 isobar 模块来开始使用该库。详细的安装指南和使用说明可以参考官方文档。

---

通过本文档，您应该能够快速上手 isobar，并利用其强大的功能进行音乐创作和声音化处理。如果您有任何问题，可以参考官方文档或查阅示例代码。