@alpha2-sh/节点
一个Node.js客户端 alpha2-host,原生的alpha2渲染器:它从Node.js或一个Electron主进程向MP4,MOV,Matroska或WebM文件输出alpha2项目,其中FFmpeg用于解码和编码,而GPU用于渲染.
安装
npm install @alpha2-sh/node
软件包不包括 alpha2-host。为这个软件包的版本和平台下载它 :
npx @alpha2-sh/node install
这个取出平台的 bundled 本地归档 从 GitHub 发布 在同一个版本中,对照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
hostPath选项; - 页:1
ALPHA2_HOST_PATH环境变量(相对路径与cwd选项,否则就是工作目录; - 在电中,
process.resourcesPath/bin/,则process.resourcesPath/· ; - 这个包是自己的
bin/目录; - 缓存中此软件包版本的归档(该
cacheDirectory选项,否则上方的目录); - 打开目录
PATH。 。 。 .
当没有的时候,客户会扔一个 Alpha2HostError 有代码 HOST_NOT_FOUND。 。 。 . installHost 以 Alpha2HostInstallError 相反,谁 code 实值 UNSUPPORTED_PLATFORM, (中文(简体) ), DOWNLOAD_FAILED, (中文(简体) ), CHECKSUM_MISMATCH, (中文(简体) ), EXTRACT_FAILED 或者说 ABORTED。 。 。 .
节点.js 22.21或后 (24.5或后在节点24上).
导出一个工程
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; 数据 主机协议 列出它们的默认值。 其中: 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数字 :
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,它在运行时会加载. 这个软件包和原生档案都不包括该库,除非您询问:思科的专利许可只覆盖了用户从思科那里取来时的二进制.
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 选项)命名镜像。 每个运行印出思科的通知:
OpenH264 Video Codec provided by Cisco Systems, Inc.
图书馆是思科的二进制,下方 思科的条件设置 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;参见 土著档案。 。 。 .