# @alpha2-sh/node 中文文档

规范地址：https://npmcn.com/package/%40alpha2-sh/node/

版本：0\.5\.3
npm 元数据更新时间：2026-11-04T23:27:19.323Z
中文译文更新时间：2026-11-06T16:16:38.114Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40alpha2-sh/node
原文对照：https://npmcn.com/package/%40alpha2-sh/node/?lang=original
项目主页：https://github.com/alpha2-sh/alpha2#readme
源码仓库：https://github.com/alpha2-sh/alpha2

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：215 kB，22 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：^22\.21\.0 \|\| \>=24\.5\.0
- 运行依赖：1 个
- 首次发布：2026-10-19T20:35:29.263Z
- 最新版本发布：2026-11-04T23:27:19.005Z
- 近 30 天下载量：2761（2026-10-06 至 2026-11-04，npm 官方下载统计）
- 已发布版本数：19（近 12 个月 19 个）

## 中文简介

Alpha2本土渲染主机的Node.js客户端.

## 安装

```sh
npm install @alpha2-sh/node
```

也可以使用：`pnpm add @alpha2-sh/node`、`yarn add @alpha2-sh/node`、`bun add @alpha2-sh/node`

## README

# @alpha2-sh/节点

一个Node.js客户端 `alpha2-host`,原生的alpha2渲染器:它从Node.js或一个Electron主进程向MP4,MOV,Matroska或WebM文件输出alpha2项目,其中FFmpeg用于解码和编码,而GPU用于渲染.

## 安装

```sh
npm install @alpha2-sh/node
```

软件包不包括 `alpha2-host`。为这个软件包的版本和平台下载它 :

```sh
npx @alpha2-sh/node install
```

这个取出平台的 `bundled` [本地归档](https://github.com/alpha2-sh/alpha2/blob/main/docs/native.md) 从 [GitHub 发布](https://github.com/alpha2-sh/alpha2/releases) 在同一个版本中,对照SHA-256来检查此套件的指针(已公布的套件包含每个版本的存档的SHA-256,因此一面镜不能取而代之;对照发行的SHA-256进行源检出检查) `checksums.sha256` 相反;结果 `verifiedBy` 然后把它拆入缓存中: `ALPHA2_HOST_CACHE_DIR` 当它被设定, 否则 `alpha2` 内 `$XDG_CACHE_HOME` 或者说 `~/.cache` 在Linux上, `~/Library/Caches` 关于macOS和 `%LOCALAPPDATA%` 在视窗上. `--force` 再次下载,以及 `installHost(options)` 从代码中执行相同。 下载通过 `HTTPS_PROXY` (单位:千美元)`HTTP_PROXY` 用于 `http:` 镜子,与 `NO_PROXY` )和信任系统的证书存储以及节点本身的根,因此一旦根证书在系统存储中(或者在 `NODE_EXTRA_CA_CERTS`) (中文(简体) ). `ALPHA2_HOST_DOWNLOAD_URL` (或 `downloadUrl` 选项)命名一个镜像 `https://github.com/alpha2-sh/alpha2/releases/download`。将公布档案 `linux-x64`, (中文(简体) ), `linux-arm64` (glibc 2.35或以后;高山等肌肉系统被拒绝), `macos-arm64` (Rosetta下的一个x64节点也使用)和 `win-x64` (没有Windows on ARM). 要使用一个系统 FFmpeg 8, 从源创建主机(`cargo install alpha2-host`)和设置 `ALPHA2_HOST_PATH`。 。 。 .

客户找 `alpha2-host` (单位:千美元)`alpha2-host.exe` 以此顺序 :

1.  页:1 `hostPath` 选项;
2.  页:1 `ALPHA2_HOST_PATH` 环境变量(相对路径与 `cwd` 选项,否则就是工作目录;
3.  在电中, `process.resourcesPath/bin/`,则 `process.resourcesPath/`· ;
4.  这个包是自己的 `bin/` 目录;
5.  缓存中此软件包版本的归档(该 `cacheDirectory` 选项,否则上方的目录);
6.  打开目录 `PATH`。 。 。 .

当没有的时候,客户会扔一个 `Alpha2HostError` 有代码 `HOST_NOT_FOUND`。 。 。 . `installHost` 以 `Alpha2HostInstallError` 相反,谁 `code` 实值 `UNSUPPORTED_PLATFORM`, (中文(简体) ), `DOWNLOAD_FAILED`, (中文(简体) ), `CHECKSUM_MISMATCH`, (中文(简体) ), `EXTRACT_FAILED` 或者说 `ABORTED`。 。 。 .

节点.js 22.21或后 (24.5或后在节点24上).

## 导出一个工程

```js
import { Alpha2NodeClient } from "@alpha2-sh/node";

const client = new Alpha2NodeClient(); // finds the host `npx @alpha2-sh/node install` put in the cache
const output = await client.exportProject({
  project, // an alpha2 project document
  assets: { "image-1": "/media/image.png" }, // the file of each source
  startTicks: 0,
  endTicks: 120_000, // ticks: 120,000 a second
  frameRate: { num: 30, den: 1 },
  videoQuality: "high",
  output: "/exports/tutorial.mp4",
  onProgress: ({ phase, completed, total }) => console.log(phase, completed, total),
});
```

每个出口都是自己运算的 `alpha2-host` 进程。 检查项目 `validateProject` 从 `alpha2/project` 程序开始前; 无效程序被拒绝 `Alpha2ProjectValidationError` 列出问题。 拒绝现有输出, 除非请求设定 `overwrite: true`,而作为请求输入之一的输出总是被拒绝: 主机写入 `<stem>.a2partial.<ext>` 在它旁边,并在它完成后移动它的位置。 无法移动的已完成文件保存在旁边, 错误(`OUTPUT_PUBLISH_FAILED`名称在 `keptPath`。 。 。 . `exportProject` 在文件完成后用输出路径解决; `onResult` 接收主机关于出口的报告(框架、编码器、速率控制、时间,每个来源都读取).

请求的字段在 `ExportProjectRequest`; 数据 [主机协议](https://github.com/alpha2-sh/alpha2/blob/main/docs/host-protocol.md) 列出它们的默认值。 其中: `container` (单位:千美元)`mp4`, (中文(简体) ), `mov`, (中文(简体) ), `mkv` 或者说 `webm`;默认的是输出的扩展名, `videoCodec` 财务报告和审定财务报表 `audioCodec` (默认情况下,容器的: `h264` 财务报告和审定财务报表 `aac`,或 `vp9` 财务报告和审定财务报表 `opus` 用于网络管理; `hevc`, (中文(简体) ), `av1`, (中文(简体) ), `mpeg4-part2` 财务报告和审定财务报表 `prores` (MOV)是其他视频解码器,每个容器只提供一些,因为 `encode.containers` 清单), `alpha` 财务报告和审定财务报表 `bitDepth` (与WebM或ProRes 4444中的VP9以及10位相片的透明性), `videoQuality` 财务报告和审定财务报表 `audioQuality` (a级, `very-low` 改为 `very-high`, (中文(简体) ), `high` 默认,即主机转换为编码器、大小和帧速率的速率,或明确的比特率), `includeAudio`, (中文(简体) ), `loudness`, (中文(简体) ), `fonts`, (中文(简体) ), `effectAssets`, (中文(简体) ), `proxies` 与 `media: "proxies"`, (中文(简体) ), `renderCache` 财务报告和审定财务报表 `memory`。 。 。 .

## 能力

`client.getCapabilities()` 报告主机能够解码和编码的内容,以及 `encode.containers` 每个容器都提供哪个解码器。 MP4、MOV或Matroska 导出不包含 `videoCodec` 得到 H.264,而一个无法编码的主机则拒绝导出而不是写入另一个编码器. 主机编码为 H.264, 或用编码器在 `encode.video` 或通过其GPU-居民路径, `encode.gpuOutputPath`,其编码器仅在GPU上取框(在Linux, `h264_vulkan`)所以没有在 `encode.video`。 。 。 . `encode.h264` 总结如下: `available` (每个出口都可以), `gpu-only` (仅导出 GPU- 居民路径) 或 `unavailable`,带有 `reason` (单位:千美元) `remedy`数字 :

```js
const { encode } = (await client.getCapabilities()).capabilities;
if (encode.h264.status !== "available") console.warn(encode.h264.reason, encode.h264.remedy);
```

第一个 `getCapabilities` 调用解码模式, 渲染器启动主机; 在运行时调用它, 其答案服务于以后调用这些模式.

`videoDecode` (单位:千美元)`software`, (中文(简体) ), `auto`, (中文(简体) ), `hardware-required`)选择主机如何解码视频,作为客户端选项或每次导出;默认由主机决定, `auto` 关于Linux和macOS,以及 `software` 在视窗上。 下 `auto`,一个导出其硬件解码器摊位在软件中再次运行解码.

`renderer` (单位:千美元)`auto`, (中文(简体) ), `gpu`, (中文(简体) ), `cpu`)选择绘制框架的内容,作为客户端选项或每个导出;未设置,主机读取 `ALPHA2_RENDERER`,其他用途 `auto`。 。 。 . `auto` 在一个硬件GPU上制造,如果有的话,在CPU上制造,否则就永远不要在软件GPU适配器上制造(lavapipe、lvmpipe、WARP、SwiftShader); `gpu` 拿走主机找到的适配器并失败 `GPU_INIT_FAILED` (b) 无需一个; `cpu` 不打开图形驱动程序。 成果和能力报告 `renderer` (单位:千美元)`gpu` 或者说 `cpu`, (中文(简体) ), `rendererReason` (为什么主机在CPU上)和,在CPU上, `rendererThreads`· ; `capabilities.features` 已经 `renderer.gpu`, (中文(简体) ), `renderer.cpu` 财务报告和审定财务报表 `effects.runtime`。运行时WGSL效应无法运行在 CPU 渲染器上: 此导出失败 `EFFECT_ERROR`。 。 。 .

## 软件H.264(OpenH264)

没有硬件H.264编码器的地方, `alpha2-host` 可以在软件中用Cisco的OpenH264库编码H.264,它在运行时会加载. 这个软件包和原生档案都不包括该库,除非您询问:思科的专利许可只覆盖了用户从思科那里取来时的二进制.

```sh
npx @alpha2-sh/node install --openh264
```

这个下载了 Cisco 的 OpenH264 2.7.0 二进制的平台 `https://ciscobinary.openh264.org`,检查下载和里面的图书馆 对照他们的SHA -256, 并将图书馆放在存储器 旁边的主机档案 `openh264-2.7.0-<target>/`时 `alpha2-host` 发现它。 它只安装库,不是 `alpha2-host`。 。 。 . `--force` 再次下载, `installOpenH264(options)` 从代码中做同样的,和 `ALPHA2_OPENH264_DOWNLOAD_URL` (或 `downloadUrl` 选项)命名镜像。 每个运行印出思科的通知:

```text
OpenH264 Video Codec provided by Cisco Systems, Inc.
```

图书馆是思科的二进制,下方 [思科的条件](https://www.openh264.org/BINARY_LICENSE.txt)设置 `ALPHA2_OPENH264=0` 保留 `alpha2-host` 从使用它. `encode.openh264` 在能力中,说明主机是否装入,以及使用它的导出名称为 `videoEncoder: "openh264"` 与 `videoEncoderLibrary`。 。 。 .

## 错误

每一次拒绝都是 `Alpha2HostError` 带有 `code`,协议的错误代码和客户端自己的(`HOST_NOT_FOUND`, (中文(简体) ), `HOST_EXITED`, (中文(简体) ), `HOST_OOM_KILLED` (一个内核外的杀手结束了,在Linux上), `HOST_LOAD_FAILED`, (中文(简体) ), `HOST_START_TIMEOUT`, (中文(简体) ), `HOST_QUARANTINED`, (中文(简体) ), `HOST_BLOCKED`, (中文(简体) ), `ABORTED`页:1 内容 `failure` 为复试策略分类( e)`alpha2/export-failure`, (中文(简体) ), `alpha2/export-retry`:步骤和框架它失败,以及它是否是丢失设备的证据,内存耗尽或输入不良. `stderr` 持有主机标准错误的结束。 子类 :

-   `Alpha2ProjectValidationError`: 项目无效(`problems`) (中文(简体) ).
-   `Alpha2ConformError`:媒体还没有准备好,所以没有做任何事情`report` 说,每个来源,什么是缺失,离线或不 媒体记录的项目. `client.conform({ project, assets })` 提出同样的问题而不出口.
-   `Alpha2GpuInitializationError`: 主机无法创建其 GPU 设备( 只使用 `renderer: "gpu"`) (中文(简体) ).
-   `Alpha2AbortError`:请求 `signal` 流产了.

内无内容的主机 `hostStartTimeoutMs` (一个客户选项,默认为30 000, `Infinity` 请求失败 `HOST_START_TIMEOUT`:有些东西在跑出前就持有了,门卫检查macOS,或者在Windows上进行抗病毒扫描或App控制政策. 在macOS上,一个文件带有浏览器下载的隔离属性而守门员不接受的主机在开始前被拒绝 `HOST_QUARANTINED`,其信息名称为 `xattr -dr com.apple.quarantine` 指挥它清除。 一个主机Windows通过策略拒绝(Smart App Control, App Control, AppLocker)是 `HOST_BLOCKED`,而一个Linux主机其程序解释器缺失(一个glibc基于musl(如高山等)),或者其glibc太老是 `HOST_LOAD_FAILED`;没有重试修复任何三个.

## 取消

`signal` (单位:千美元) `AbortSignal`)取消导出。 客户写道: `cancel` 向主机行,该主机停止导出,删除其部分文件和答案;然后进程结束,以及 `exportProject` 拒绝方式 `Alpha2AbortError` 一旦它不见了。 一个在5秒内不回答的主机被终结. 主机还监视起动的过程:当该过程被终止后,主机会取消其输出和退出.

## 货币

`client.still({ project, assets, time, output })` 使一个框架变成PNG, 框架是出口在当时绘制的(项目网格的框架, `stills[0].frameTime` - 视频没有编码; `client.stills({ ..., stills: [{ time, output }, ...] })` 最多256个宿主. `time` 在滴答声中.

`concurrency` (default 1)是客户端同时运行多少个主机处理,因此有多少个导出共享了GPU;更多的请求等待一个槽. 模块级别 `exportProject(request, options)`, (中文(简体) ), `still`, (中文(简体) ), `stills` 财务报告和审定财务报表 `getCapabilities(options)` 每个主机二进制共享一个客户端,并 `concurrency`。 。 。 .

## 电子

运送档案 `bin/` 财务报告和审定财务报表 `lib/` aSAR 归档之外, 例如 `bin/` 财务报告和审定财务报表 `lib/` 在应用程序的资源目录中( e)`process.resourcesPath`),即客户端在一个电子主进程中找到主机. 内部主机路径 `app.asar` 可从 `app.asar.unpacked` 换句话说.

## 许可证

MIT,版权Alpha2贡献. 本地档案的FFmpeg 属于 LGPL;参见 [土著档案](https://github.com/alpha2-sh/alpha2/blob/main/docs/native.md)。 。 。 .

## 常见问题

### @alpha2-sh/node 是什么？

Alpha2本土渲染主机的Node\.js客户端\.

### 如何安装 @alpha2-sh/node？

在项目目录运行 npm install @alpha2-sh/node，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 alpha2-node，可以用 npx alpha2-node 直接运行。

### @alpha2-sh/node 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @alpha2-sh/node 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @alpha2-sh/node 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js ^22\.21\.0 \|\| \>=24\.5\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @alpha2-sh/node 可以商用吗？

@alpha2-sh/node 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @alpha2-sh/node 的下载量有多少？

根据 npm 官方下载统计，@alpha2-sh/node 在 2026/10/06 – 2026/11/04 这 30 天内被下载 2,761 次，日均约 92 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @alpha2-sh/node 还在维护吗？

最新版本 0\.5\.3 发布于 2026/11/05（2 天前）；至今共发布 19 个版本，其中过去 12 个月发布了 19 个；首次发布于 2026/10/20。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。