Tone.js

Tone.js 是一个用于在浏览器中创建交互式音乐的 Web Audio 框架。Tone.js 的架构旨在让音乐家和音频程序员在创建基于 Web 的音频应用时都感到熟悉。在高层次上，Tone 提供了常见的数字音频工作站（DAW）功能，如用于同步和调度事件的全局传输控制，以及预构建的合成器和效果器。此外，Tone 还提供了高性能的构建块，用于创建您自己的合成器、效果器和复杂的控制信号。

API
示例

安装

有两种方法可以将 Tone.js 集成到项目中。首先，可以使用 npm 将其本地安装到项目中：

npm install tone      // 安装最新稳定版本
npm install tone@next // 或者，使用 'next' 版本

使用 JavaScript 的 import 语法将 Tone.js 添加到项目中：

import * as Tone from "tone";

Tone.js 也托管在 unpkg.com 上。它可以直接添加到 HTML 文档中，只需确保它位于任何项目脚本之前。点击此处查看示例以获取更多详细信息。

<script src="http://unpkg.com/tone"></script>

Tone 入门

// 创建一个合成器并将其连接到主输出（您的扬声器）
const synth = new Tone.Synth().toDestination();

// 播放一个中音"C"，持续时间为八分音符
synth.triggerAttackRelease("C4", "8n");

Tone.Synth

Tone.Synth 是一个基本的合成器，具有单个振荡器和 ADSR 包络。

triggerAttack / triggerRelease

triggerAttack 开始音符（振幅上升），而 triggerRelease 是振幅回到 0 的时候（即音符结束）。

const synth = new Tone.Synth().toDestination();
const now = Tone.now();
// 立即触发攻击
synth.triggerAttack("C4", now);
// 等待一秒后触发释放
synth.triggerRelease(now + 1);

triggerAttackRelease

triggerAttackRelease 是 triggerAttack 和 triggerRelease 的组合

第一个参数是音符，可以是赫兹频率（如 440）或"音高-八度"表示法（如 "D#2"）。

第二个参数是音符持续的时间。这个值可以是秒，也可以是与速度相关的值。

triggerAttackRelease 的第三个（可选）参数是音符应该在 AudioContext 时间轴上的何时播放。它可以用来安排未来的事件。

const synth = new Tone.Synth().toDestination();
const now = Tone.now();
synth.triggerAttackRelease("C4", "8n", now);
synth.triggerAttackRelease("E4", "8n", now + 0.5);
synth.triggerAttackRelease("G4", "8n", now + 1);

时间

Web Audio 具有先进的、精确到样本的调度能力。AudioContext 时间是 Web Audio API 用来调度事件的，从页面加载时开始计时，以秒为单位递增。

Tone.now() 获取 AudioContext 的当前时间。

setInterval(() => console.log(Tone.now()), 100);

Tone.js 抽象了 AudioContext 时间。所有接受时间作为参数的方法不仅可以接受秒数，还可以接受字符串。例如，"4n" 是四分音符，"8t" 是八分音符三连音，"1m" 是一小节。

阅读有关时间编码的更多信息。

开始音频

重要提示：浏览器在用户点击某些东西（如播放按钮）之前不会播放任何音频。只有在从用户操作（如"点击"或"按键"）触发的事件监听器中调用 Tone.start() 后，才能运行您的 Tone.js 代码。

Tone.start() 返回一个 promise，只有在该 promise 解决后，音频才会准备就绪。在 AudioContext 运行之前调度或播放音频将导致静音或不正确的调度。

// 为播放按钮添加点击监听器
document.querySelector("button")?.addEventListener("click", async () => {
    await Tone.start();
    console.log("音频已就绪");
});

调度

Transport

Tone.getTransport() 返回主时间控制器。与 AudioContext 时钟不同，它可以启动、停止、循环和实时调整。您可以将其视为数字音频工作站中的编排视图。

多个事件和部分可以沿着 Transport 进行安排和同步。Tone.Loop 是一种创建可以调度启动和停止的循环回调的简单方法。

// 创建两个单音合成器
const synthA = new Tone.FMSynth().toDestination();
const synthB = new Tone.AMSynth().toDestination();
// 每个四分音符播放一个音符
const loopA = new Tone.Loop((time) => {
    synthA.triggerAttackRelease("C2", "8n", time);
}, "4n").start(0);
// 在每个间隔的四分音符上播放另一个音符，从"8n"开始
const loopB = new Tone.Loop((time) => {
    synthB.triggerAttackRelease("C4", "8n", time);
}, "4n").start("8n");
// 当 Transport 启动时，所有循环开始
Tone.getTransport().start();
// 在 10 秒内将速度逐渐提高到 800 bpm
Tone.getTransport().bpm.rampTo(800, 10);

由于 JavaScript 回调的定时不精确，事件的精确到样本的时间被传递到回调函数中。使用这个时间值来调度事件。

乐器

有众多合成器可供选择，包括 Tone.FMSynth、Tone.AMSynth 和 Tone.NoiseSynth。

所有这些乐器都是单音（单声部）的，这意味着它们一次只能播放一个音符。

要创建多音合成器，请使用 Tone.PolySynth，它接受一个单音合成器作为第一个参数，并自动处理音符分配，因此您可以传入多个音符。API 与单音合成器类似，只是 triggerRelease 必须给定一个音符或音符数组。

const synth = new Tone.PolySynth(Tone.Synth).toDestination();
const now = Tone.now();
synth.triggerAttack("D4", now);
synth.triggerAttack("F4", now + 0.5);
synth.triggerAttack("A4", now + 1);
synth.triggerAttack("C5", now + 1.5);
synth.triggerAttack("E5", now + 2);
synth.triggerRelease(["D4", "F4", "A4", "C5", "E5"], now + 4);

采样

声音生成不仅限于合成声音。您还可以加载采样并以多种方式播放。Tone.Player 是加载和播放音频文件的一种方式。

const player = new Tone.Player(
    "https://tonejs.github.io/audio/berklee/gong_1.mp3"
).toDestination();
Tone.loaded().then(() => {
    player.start();
});

Tone.loaded() 返回一个 promise，当所有音频文件加载完成时解决。这是一个有用的快捷方式，避免了等待每个单独音频缓冲区的 onload 事件解决。

Tone.Sampler

多个采样也可以组合成一个乐器。如果你有按音符组织的音频文件，Tone.Sampler会对采样进行音高转换以填补音符之间的空缺。例如，如果你只有钢琴上每隔3个音符的采样，你可以将其转换为完整的钢琴采样。

与其他合成器不同，Tone.Sampler是多音的，所以不需要传递给Tone.PolySynth

const sampler = new Tone.Sampler({
	urls: {
		C4: "C4.mp3",
		"D#4": "Ds4.mp3",
		"F#4": "Fs4.mp3",
		A4: "A4.mp3",
	},
	release: 1,
	baseUrl: "https://tonejs.github.io/audio/salamander/",
}).toDestination();

Tone.loaded().then(() => {
	sampler.triggerAttackRelease(["Eb4", "G4", "Bb4"], 4);
});

效果器

在上面的例子中，音源总是直接连接到Destination，但合成器的输出也可以在到达扬声器之前通过一个（或多个）效果器。

const player = new Tone.Player({
	url: "https://tonejs.github.io/audio/berklee/gurgling_theremin_1.mp3",
	loop: true,
	autostart: true,
});
//创建一个失真效果
const distortion = new Tone.Distortion(0.4).toDestination();
//将播放器连接到失真效果
player.connect(distortion);

连接路由是灵活的，连接可以串行或并行。

const player = new Tone.Player({
	url: "https://tonejs.github.io/audio/drum-samples/loops/ominous.mp3",
	autostart: true,
});
const filter = new Tone.Filter(400, "lowpass").toDestination();
const feedbackDelay = new Tone.FeedbackDelay(0.125, 0.5).toDestination();

// 将播放器并行连接到反馈延迟和滤波器
player.connect(filter);
player.connect(feedbackDelay);

多个节点可以连接到同一个输入，使音源能够共享效果。Tone.Gain是用于创建复杂路由的有用工具节点。

信号

与底层的Web Audio API一样，Tone.js几乎在所有方面都建立在音频速率信号控制之上。这是一个强大的功能，允许对参数进行样本精确的同步和调度。

Signal属性有一些内置方法用于创建自动化曲线。

例如，Oscillator上的frequency参数是一个Signal，所以你可以创建一个从一个频率到另一个频率的平滑变化。

const osc = new Tone.Oscillator().toDestination();
// 从"C4"开始
osc.frequency.value = "C4";
// 在2秒内渐变到"C2"
osc.frequency.rampTo("C2", 2);
// 启动振荡器持续2秒
osc.start().stop("+3");

AudioContext

Tone.js在加载时创建一个AudioContext，并使用standardized-audio-context来增强其浏览器兼容性。可以通过Tone.getContext访问AudioContext。或者使用Tone.setContext(audioContext)设置你自己的AudioContext。