# @csound/wasm-bin 中文文档
规范地址：https://npmcn.com/package/%40csound/wasm-bin/
版本：7\.0\.0
npm 元数据更新时间：2026-10-22T17:07:59.007Z
中文译文更新时间：2026-11-11T11:02:43.210Z
软件包许可：LGPL-2\.1
本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。
原始 npm 页面：https://www.npmjs.com/package/%40csound/wasm-bin
原文对照：https://npmcn.com/package/%40csound/wasm-bin/?lang=original
项目主页：https://github.com/csound/csound/tree/main/platform/wasm-wasi
源码仓库：https://github.com/csound/csound
## 关键信息（来自 npm 元数据）
- 包体积（解压后）：183 MB，64 个文件
- 模块格式：CommonJS
- TypeScript 类型：未声明
- 运行依赖：0 个
- 首次发布：2021-01-18T21:01:29.972Z
- 最新版本发布：2026-10-22T17:07:58.758Z
- 近 30 天下载量：2199（2026-10-11 至 2026-11-09，npm 官方下载统计）
- 已发布版本数：51（近 12 个月 23 个）
## 中文简介
包含可被捆绑到其他相声包的相声二进制包
## 安装
```sh
npm install @csound/wasm-bin
```
也可以使用：`pnpm add @csound/wasm-bin`、`yarn add @csound/wasm-bin`、`bun add @csound/wasm-bin`
## README
# @csound/wasm——地方发展指南
本指南解释如何在当地建立 Csound WASM 并将其与 [声波网络 IDE](https://github.com/csound/web-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 二进制
建筑用途 [无](https://nixos.org/) 保证可复制的 我跨越编译器。 确保您安装了 Nix .
```bash
# 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命令,用于运行时间,如Wasmtime
- `csound-plugin-sdk.tar.gz` - SDK 匹配选定的浏览器引擎
- `csound-plugin-sdk-compat.tar.gz` - 基线浏览器引擎的SDK
- `plugin_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`。 。 。 .
```text
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.
```bash
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 处理例外。 直接援引似乎是:
```bash
wasmtime run -Wexceptions=y --dir=. ./lib/csound-cli.wasm -nd ./example.csd
```
本地 Csound 还可以使用 Wasmtime 来装入所支持的 opcode 插件 `--opcode-lib=file.wasm`。见 [原生 Csound 网络大会插件](https://npmcn.com/package/%40csound/wasm-bin/NATIVE_OPCODE_PLUGINS.md) 建筑物 选项,当前ABI限制,以及编译缓存规则.
运行命令行 CSD 套件与已建的套件 `lib/csound-cli.wasm`数字 :
```bash
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 实时浏览器
通过通常的命令构建二进制和浏览器包装 :
```bash
# 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 响应头:
```text
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.
```js
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 否则. ` --realtime ` 也能让它成为现实 复置正明旗. 包装器读取本地状态, 因此被拒绝的选项更改不会更改其 模式。 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 类 语法错误返回原生的失败结果,留下以后可用的调用.
```js
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 检查时, 使用仅测试的入门 :
```bash
# 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 目标 :
```bash
# 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仍然不在这一目标之外.
正常的内出错让克苏德保持了记事记-错误的行为. 一个致命的工人错误 命令以失败结束: 工人无法使用渲染线程跳 缓冲或安全清理 半完成的操作码。 浏览器反应堆使用 同样的规则.
* * *
## 浏览器中的外部分数程序
浏览器构建支持 `` 通过通常 声乐分数分析器. 将 WASI 预览 1 命令上传到 Csound 的文件系统 在汇编文档之前:
```js
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` 当地
```bash
# 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.
```bash
cd browser
npm ci # install browser-wrapper dependencies
npm link @csound/wasm-bin # replace the npm version with your local build
```
* * *
## 3\. 建设 `@csound/browser`
```bash
# 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
```bash
# Inside platform/wasm-wasi/browser/
npm link # registers this directory as the local @csound/browser
```
```bash
# Inside web-ide/
npm link @csound/browser # replace the npm version with your local build
```
Web IDE Dev 服务器现在将导入您的本地构建 `@csound/browser` (并转接本地 `.wasm` 二进制),每次运行时:
```bash
# Inside web-ide/
npm start
```
* * *
## 5\. 在变化后进行重复
一旦建立了链接(步骤1-4是) **一次性设置**),重建周期 仅仅是:
```bash
# 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\. 拆分——恢复已出版的版本
当您在本地测试完成时, 请移除符号链接 :
```bash
# 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
```
## 常见问题
### @csound/wasm-bin 是什么？
包含可被捆绑到其他相声包的相声二进制包
### 如何安装 @csound/wasm-bin？
在项目目录运行 npm install @csound/wasm-bin，或使用 pnpm add / yarn add / bun add。
### @csound/wasm-bin 支持 TypeScript 吗？
该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/csound\_\_wasm-bin 是否存在。
### @csound/wasm-bin 支持 ESM 还是 CommonJS？
以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。
### @csound/wasm-bin 可以商用吗？
@csound/wasm-bin 使用 LGPL-2\.1 许可。弱 Copyleft：作为库被调用时通常不要求开源你自己的代码，但修改库本身需以 LGPL 开源；前端打包合并后的适用边界存在不同理解。以上为概括，不构成法律意见，请以许可原文为准。
### @csound/wasm-bin 的下载量有多少？
根据 npm 官方下载统计，@csound/wasm-bin 在 2026/10/11 – 2026/11/09 这 30 天内被下载 2,199 次，日均约 73 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。
### @csound/wasm-bin 还在维护吗？
最新版本 7\.0\.0 发布于 2026/10/23（19 天前）；至今共发布 51 个版本，其中过去 12 个月发布了 23 个；首次发布于 2021/01/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。