@csound/wasm——地方发展指南
本指南解释如何在当地建立 Csound WASM 并将其与 声波网络 IDE。 。 。 .
概览
WASM 堆栈在此目录内分为两个包:
| 软件包 | 路径 | npm 名称 |
|---|---|---|
二进制( B).wasm 文档) | platform/wasm-wasi/ | @csound/wasm-bin |
| 浏览器包装器 | platform/wasm-wasi/browser/ | @csound/browser |
Web IDE 依赖于 @csound/browser,这反过来取决于
@csound/wasm-bin通过将安装的 npm 软件包替换为
连锁点在你的本地建筑.
1. 构建 WASM 二进制
建筑用途 无 保证可复制的 我跨越编译器。 确保您安装了 Nix .
# From the repo root
cd platform/wasm-wasi
npm install # install build-script dependencies
npm run build # builds Csound, plugins and accessory commands with Nix
scripts/compile.sh 生产下列工艺品: platform/wasm-wasi/lib/数字 :
csound.wasm编号 :csound.wasm.z- 基线浏览器反应堆和压缩副本csound-browser-realtime.wasm编号 :.wasm.z- 共享浏览器反应堆,当支持时csound-cli.wasm- 独立的WASI命令,用于运行时间,如Wasmtimecsound-plugin-sdk.tar.gz- SDK 匹配选定的浏览器引擎csound-plugin-sdk-compat.tar.gz- 基线浏览器引擎的SDKplugin_example.wasm编号 :plugin_example_cpp.wasm- 基线示例插件plugin_example_shared.wasm编号 :plugin_example_cpp_shared.wasm- 共享实例,如果得到支持
这些模块公布于 @csound/wasm-bin软件包 main
输入仍然是浏览器反应堆, csound.wasm。命令行运行时间应当
装入 csound-cli.wasm 当然.
命令构建还将这些工具放在 lib。每个文件使用工具
名称后继 .wasm。 。 。 .
atsa csbeats cvanal dnoise envext
extract extractor het_export het_import hetro
lpanal lpc_export lpc_import mixer mkir
pv_export pv_import pvanal pvlook scale
scot scsort sdif2ad smf_conv src_conv
npm run build {\fn黑体\fs22\bord1\shad0\3ahbe\4ah00\fscx67\fscy66\2chffffff\3ch808080}通过一切来构建 scripts/compile.sh在命令中
模式, src/csound.nix 将 Csound 的核心编译一次,用于主命令和
所有的工具。 此模式还运行 Wasmtime 检查 postInstall编辑
自由模拟在 src/libsamplerate.nix命令和
浏览器构建链接, 所以 oversample 财务报告和审定财务报表 undersample 能够使用 sinc
转换器。 如果 CMake 找不到库, 配置失败 .
每个工具都是独立的 WASI 预览 1 命令,并带有导出 _start
入口和它自己的导出内存 。 它包括它的效用代码和
库,所以它不需要本地的 Csound 安装或工具插件.
例如,用Wasmtime将一个声音文件转换为48 kHz.
wasmtime run -Wexceptions=y --dir=. ./lib/src_conv.wasm -r48000 -ooutput.wav input.wav
一个浏览器WASI主机可以装入与其主模块相同的命令. 东道主
必须提供 WASI 预览 1 导入、参数、文件和标准流,
然后打电话 _start 一次在新的实例。 浏览器必须支持标准
网络大会例外处理。 这些命令与
@csound/browser 音频反应堆及其插件加载器.
构建默认为本地的Nix系统. 要使用配置的远程构建器,
设定 NIX_SYSTEM 给那个建筑商提供的系统 例如,从
达尔文, NIX_SYSTEM=x86_64-linux yarn build 选择可用的
x86_64-linux 建会者.
独立模块目前针对Wasmtime的标准化WebAssembly 处理例外。 直接援引似乎是:
wasmtime run -Wexceptions=y --dir=. ./lib/csound-cli.wasm -nd ./example.csd
本地 Csound 还可以使用 Wasmtime 来装入所支持的 opcode 插件
--opcode-lib=file.wasm。见
原生 Csound 网络大会插件 建筑物
选项,当前ABI限制,以及编译缓存规则.
运行命令行 CSD 套件与已建的套件
lib/csound-cli.wasm数字 :
source ./scripts/nixpkgs-pin.sh
nix-build ./src/csound-tests.nix
测试衍生也默认为本地的Nix系统. 过
--argstr system x86_64-linux 以明确选择已配置的 Linux 构建器.
它使用从被绑住的Nixpkgs的Wasmtime, 禁用音频 -nd,运行
发现的 CSD 文件 tests/commandline。每个文件宣布自己的文件
包括WebAssembly 覆盖。 OSC和同步
ftaudio 病例检查无法使用的套接字和线程的诊断.
发布新的 @csound/wasm-bin 在更新和
出版 @csound/browser; 旧的二进制软件包不包含新软件包
csound-cli.wasm 指挥文物.
WASI 实时支持
npm run build 构建兼容的浏览器模块, 当工具链
支持 WASI 线程,一个共享模组浏览器反应堆. 两艘都上了船
@csound/wasm-bin编辑 csound.js 捆绑包括一个引擎:共享
如果有反应堆,否则就是基线舱。 所有浏览器 API 使用
那个引擎。 不需要单独的实时构建命令或运行时模块 URL .
电脑 BUILD_WASI_REALTIME 设置默认值为 AUTO编辑/链接
检查需要真实的线程切入点, 免锁的动漫, 并共享
记忆. ON 需要这种支持; OFF 关闭它。 正常的 Nix 构建
请检查access-date=中的日期值 (帮助) C/C++ 运行时间用被绑定的LLVM 21构建. 如果支票
失败, 它只装入兼容模块 。 其他建设失败
失败的建设.
支持不能启用模式 。 Csound开始做背景工了
仅在 --realtime 设定在性能之前。 无支持的引擎
保持同步行为,并在给与旗帜时发出警告.
WASI 实时浏览器
通过通常的命令构建二进制和浏览器包装 :
# From platform/wasm-wasi
npm run build
cd browser
npm ci
npm run build:prod
包装器使用本地 ../lib 出现或安装的文物
@csound/wasm-bin 软件包。 服务 browser/dist/csound.js 从你的应用程序.
不需要第二个引擎文件 。 没有线状反应堆的构造使用
基线发动机.
线性主机需要一个安全的上下文(localhost works), AudioWorklet, 共享内存、 Wasm 动漫和例外,以及这些 HTTP 响应头:
Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp
useWorker 默认为 false在 AudioWorklet 中运行引擎
同步进取. 设定 useWorker: true 使用工人。 与共享引擎,
这需要共享主机,除非 useSAB: false
选择信件端口模式; 缺少支持在打开前造成错误
音频康特. 所有模式仍然需要捆绑引擎的Wasm特性.
一个失败的工人启动会关闭实例和它拥有的任何上下文.
明确 useWorker: false 在一个 AudioWorklet 中运行引擎. useSAB: false
保留现有的传输,不使用共享音频缓冲器。 这个名字
libcsound() 构造器保持其同步引擎API. 这些模式的使用
同一共享的Wasm二进制, 而不是通过工人传递记忆,
因此,它们不需要隔离头。 他们仍然需要分享瓦姆记忆,
和瓦斯标准例外。 他们使用同步输入,忽略
--realtime 有警告的; supportsRealtime() 返回 0.
import Csound from "/csound.js";
const cs = await Csound({ useWorker: true });
await cs.setOption("-odac -m0 --daemon");
await cs.setOption("--realtime");
await cs.compileOrc(`
sr = 48000
ksmps = 32
nchnls = 2
0dbfs = 1
instr 1
a1 oscils 0.1, p4, 0
outs a1, a1
endin
`);
// Start/resume from a user gesture if the browser requires one.
await cs.start();
await cs.event(0, [1, 0, 0.25, 440]);
// Later:
await cs.stop();
await cs.reset();
await cs.terminateInstance();
supportsRealtime() 当选定引擎支持模式时返回 1;
isRealtime() 返回本地国旗设置。 两者均返回 0 否则.
<CsOptions> --realtime </CsOptions> 也能让它成为现实 复置正明旗.
包装器读取本地状态, 因此被拒绝的选项更改不会更改其
模式。 Omiting the flag 保持了同步的init和通常的活引擎API.
共享的宿主为4名童工准备了256个米B瓦斯姆
记忆. src/shared-memory-max.txt 为引擎、插件设置此限制,
和浏览器捆绑。 更改文件并一起重建全部三个; CMake
拒绝冲突 CSOUND_WASI_MAX_MEMORY 超过。 Csound 使用它现有的
当旗帜被设定时, 输入它 。 联合调查局拥有所有五个工人,所以可以结束
失败的引擎, 即使渲染器的工人们等待在一块。 音频工作
从共享环中消耗音频。 旧的
在童工准备好之前 建筑工跑过一次.
与 --realtime,浏览器接受 compileOrc(), (中文(简体) ), evalCode()字符串
频道在回放时读取并写入. 单独的 Csound 线程运行这些
电话顺序。 在管弦乐团合并和全局化之后的汇编解决
init 已完成;评价以该请求的返回值解决。 A 类
语法错误返回原生的失败结果,留下以后可用的调用.
await cs.setStringChannel("source", "new live code");
const length = await cs.evalCode('return strlen(chnget:S("source"))');
await cs.compileOrc('instr 2\n a1 oscili 0.1, 660\n out a1\nendin');
await cs.event(0, [2, 0, 0.25]);
编译和样本钟在编译或评价运行时继续. 这些电话仍然和Csound的Mutex 一样 加上音符初始化:很长 编辑或全局init即使现有声音不断播放,也可以延迟新音符. 这样做可以消除工人的分析和评价;它不能保证 零下行或固定编辑间隔。 应用程序代码也必须协调 更改为显示其运行中的乐器已读.
之前声明的数字频道 start() 使用已保存的地址和原子
负荷/储存。 之后创建的频道使用控制线程进行安全检查;
新频道写入也可以创建它们的存储. 字符串在
信道锁定, 使同步调整大小不能超过结果缓冲 .
数字音符和结束事件, MIDI, 样本时钟, 固定音频设置, 模式
询问和暂停/恢复/停止. event(2, []) 结束性能;
[0, delay] 以秒计结束。 事件承诺确认承认;
realtimePerformanceEnded csound 加入背景工作和
浏览器发布音频节点.
文件系统调用、 分数文本、 表格更改以及完整的 CSD 汇编
要求停止执行。 控制线条不能打开制成器的
文件: live #include 和文件依赖的全局性输入不支持,即使
预装文件。 在提交源代码之前展开该代码
却停了下来 排队表事件不会将 GEN 工作移出渲染线程 .
在共享主机暂停时提交引擎调用前恢复 .
动态插件在所有模式中工作 。 重建匹配的插件
csound-plugin-sdk.tar.gz; 旧的未共享二进制无法使用共享引擎
以明显的迷误而失败。 普通构建生成匹配的 SDK 和
共享 C/C++ 示例。 通过插件 withPlugins,或者写给
虚拟文件系统,并在第一个选项之前通过 Csound 选项选择它们
start()。共享工人主机在第一次启动时修正其插件设置,
即使没有 --realtime重置可以重用这些插件,但不能添加新插件
这些。 创建新实例来更改此设定 .
SDK 和实例 Nix 构建检查 lib/csound-browser-realtime.wasm.z
来选择默认的内存 ABI,就像浏览器构建的那样。 路过时
sDK 从另一个软件包中存档, 也可以通过 --arg sharedMemory true 页:1
共享引擎或 --arg sharedMemory false 一个没有共享的引擎.
装载器给每个工人相同的功能表布局和每个线程 它自己的插件 TLS 存储 。 它初始化共享数据并运行构建器 一次 一次吗 插件可能使用模块本地 TLS; 跨模块 TLS 地址和依赖 共享库不支持 。 只有父模式仍然可以装入插件 同步通过文件系统. 儿童线程文件访问, 嵌入线程 创建和并行的 DSP 仍然不支持。 预加载文件不会 可用子文件描述符 。 插件必须避免在 (原始内容存档于2017-09-21). bender in it.
event(0, pfields) 在活动实时模式下使用 3-64 个有限数字
请求同步便条录入。 共享主机最多持有 256 API
每批最多拨打32个电话。 背景控制队列有四个
槽,包括其运行中的请求,并最多接受 UTF-8 文本的 1 MiB
每个请求;超过两个限制时拒绝呼叫。 已解决的说明活动
调用确认发送,而不是注意它或可调用输出。 本地队列溢出
顺着Csound的诊断.
四个文本缓冲器保留了4 MiB,约占共享256 MiB堆的1.6%. 它们先分配,然后停止使用。 保持它们固定,让我们 制片人提交申请时不拨打C分配器或采取 原生变种. JavaScript 在编码请求时仍然会分配缓冲.
在共享的工人主机上,编译,eval和频道的通话没有经过时间
期限,是否有效 --realtime; 完成、停止取消或工人
失败解决了他们。 短途运输电话保持超时,不能
取消已经发送的电话 。 单位
实时模式,停止拒绝队列控制工作,并允许运行中的请求
在清理前完成; 以后的运行从不重放旧作品 。 没有旗帜,
完成保留现有的 API 调用行为 。 MIDI 使用单独的
1 024个包环 拒绝全写而不替换未读包.
正常站点/ 重置等待init 和控制线程完成 。 不能这样
取消任意操作码。 交通超时或工人死亡错误
等待呼叫并结束诉讼。 后创建新实例 .
terminateInstance() (单位:千美元)
丢弃所有工人和共享引擎状态.
运行 Chrome 检查时, 使用仅测试的入门 :
# From platform/wasm-wasi, after the normal build
bash scripts/compile-test-fixtures.sh
cd browser
npm run test:fixtures
npm run test:realtime
CSOUND_THREADED_WASM 是对生反应堆或压缩反应堆的构建时间覆盖.
CI运行WASI命令的线程检查和这些浏览器检查. 测试固定装置
停留在出版物之外 lib/ 目录; 固定叶片 dist/ 打开
生产引擎。 大门没有正常的文物 检查
盖旗激活,
重设、 共享 C/ C++ 插件、 本地模式, 不隔离标题、 音频和
保存期间的时钟进度和评价,实时编译器错误恢复,
命令API结果,关闭。 他们没有建立 延迟
绑定或使每个操作码都安全 可以同时输入 设定
CSOUND_BROWSER_ENGINE=firefox 让他们在Firefox运行.
WASI 实时命令主机
已发布的命令模块仍能兼容未被穿透的WASI主机. 对于一个WASI预览 1 线程命令主机, 构建内部 Nix 目标 :
# From platform/wasm-wasi
source scripts/nixpkgs-pin.sh
nix-build src/csound-realtime.nix -o result_realtime
wasmtime run -Sthreads=y -Wthreads=y -Wshared-memory=y -Wexceptions=y \
-Ccache=n --dir=. result_realtime/lib/csound-realtime.wasm \
--realtime -nd example.csd
此目标保留其静态库和信头,并运行线程和 工人检查 它不取代已发布的命令模块. 这需要 a 主机有WASI P1线程,共享内存,以及Wasm例外.
不节奏的渲染可以提前计分时间,而背景会等待。 编译 操作前的仪器,并使用数字事件。 同时编译 仍然需要对共享编译器状态进行审计 。 外部动态插件 进程,平行的DSP仍然不在这一目标之外.
正常的内出错让克苏德保持了记事记-错误的行为. 一个致命的工人错误 命令以失败结束: 工人无法使用渲染线程跳 缓冲或安全清理 半完成的操作码。 浏览器反应堆使用 同样的规则.
浏览器中的外部分数程序
浏览器构建支持 <CsScore bin="csbeats"> 通过通常
声乐分数分析器. 将 WASI 预览 1 命令上传到 Csound 的文件系统
在汇编文档之前:
await csound.fs.writeFile("csbeats.wasm", bytes);
await csound.compileCSD(document);
绑定物首先查找准确的 bin 程序路径,相对
csound.fs.getcwd(),然后尝试路径 .wasm 附录。 装入
并只在 Csound 调用时编译文件。 它可缓存到四个
模块并检查每个调用时的字节, 因此替换一个上传
文件生效。 约束中不包含命令二进制或 URL .
Web IDE 这样的应用程序可以取回捆绑的 csbeats.wasm 需求
并通过相同的文件系统 API 写入它.
其他上传的命令使用相同的路径. 他们必须出口 memory 财务报告和审定财务报表
_start 并使用 WASI 预览 1 导入。 每次运行都有新鲜的内存和文件
解说. 命令将 Csound 当前的目录显示于 /像一个
WASI 运行时间预打开一个目录;目录外的文件是
未挂载。 Csound 作为最后一个通过分数输入和输出文件名
两个论点。 命令使用装订器现有的 WASI 代码并共享其
文件直接存储,没有额外的运行时间依赖或文件副本。 文件
更改会随着命令的写出而生效,包括当它后来失败时.
每个开口的手柄保持自己的位置. 标准输入为空
每个输出流中最后16 KB 转到 Csound 的留言听众 .
该调用是同步的,因为 Csound 读取生成的分数
system() 返回。 长指令可以支撑引擎线. 参数
可以使用引用和回击 逃脱, 但没有壳,管,
重定向,可变扩展或过程产卵. 非零退出状态,
缺少命令, 无效的模块或陷阱失败分数生成 。 不支持
我打电话回来 ENOSYS。 。 。 .
这是Csound浏览器的扩展,而不是WASI syscall. 被钉住的 Idi-libc
声明 system() 但不定义它,预览 1 没有 exec 或者说
system 导入。 浏览器二进制供应 system() 通过明确的
env.csoundWasiJsSystem(commandPointer) 导入。 主机读取了已终止的 NUL
从 Csound 内存返回的 UTF-8 字符串 exitCode << 8,或 -1 在一个主机上
错误. system(NULL) 返回零,因为没有空壳。 使用
匹配此二进制的浏览器包装 。 独立的WASI指挥有
没有新的主机导入并报告外部分数生成为不支持 .
2. 链接 @csound/wasm-bin 当地
# Inside platform/wasm-wasi/
npm link # registers this directory as the local @csound/wasm-bin
然后将浏览器包装器接上本地二进制 :
浏览器包需要Node.js 22.13或更晚. 它的 npm 设置执行
节点版本和对等依赖。 使用 npm ci 用于从
锁文件; 不使用 --legacy-peer-deps 或者说 --force。 。 。 .
对于 nvm 用户, platform/wasm-wasi/browser/.nvmrc 22.23.2. 运行 nvm install 财务报告和审定财务报表
nvm use 在安装依赖之前从目录中跳出 。 CI读到
同一个文件。 文件不自行更改您的 shell 或 PATH; Nix 用户
可以继续使用 nix-shell,它提供节点22 没有nvm.
cd browser
npm ci # install browser-wrapper dependencies
npm link @csound/wasm-bin # replace the npm version with your local build
3. 建设 @csound/browser
# Still inside platform/wasm-wasi/browser/
npm run build # development build
# or
npm run build:prod # production build
编译的输出土地 platform/wasm-wasi/browser/dist/。 。 。 .
4. 链接 @csound/browser 输入网络 IDE
# Inside platform/wasm-wasi/browser/
npm link # registers this directory as the local @csound/browser
# Inside web-ide/
npm link @csound/browser # replace the npm version with your local build
Web IDE Dev 服务器现在将导入您的本地构建 @csound/browser
(并转接本地 .wasm 二进制),每次运行时:
# Inside web-ide/
npm start
5. 在变化后进行重复
一旦建立了链接(步骤1-4是) 一次性设置),重建周期 仅仅是:
# Inside platform/wasm-wasi/browser/
npm run build
Vite会检测更新后的文件并自动重新装入.
没有必要再运行 npm link ——共鸣持续.
您可以在 Vite 输出中看到 Babel 注释 :
[BABEL] Note: The code generator has deoptimised the styling of .../csound.js as it exceeds the max of 500KB.这是 仅供参考 - Babel跳过漂亮的打印大文件 表现。 它不影响功能.
6. 拆分——恢复已出版的版本
当您在本地测试完成时, 请移除符号链接 :
# Inside web-ide/
npm unlink @csound/browser
npm install # re-install the published version
# Inside platform/wasm-wasi/browser/
npm unlink @csound/wasm-bin
npm install