@one2x/visionular

微帧（Visionular）云转码 Node SDK：转码前自检 → 提交 → 等待 → 产物校验 → 取回目标桶，一条龙。

克隆即跑的 Demo

git clone [email protected]:one2x-ai/visionular-node.git
cd visionular-node && pnpm install && pnpm build

export VISIONULAR_ACCESS_KEY=xxx    # 找运维拿
export VISIONULAR_SECRET_KEY=xxx

# ① 最快体验：只跑权限自检（不转码、不花钱）
node examples/demo-preflight.mjs my-bucket

# ② 本地视频 → 480P → 存回你的桶
node examples/demo-local.mjs /tmp/example.mp4 my-bucket

# ③ S3 已有视频 → 1080P + 480P 双档（CMS 同款用法）
node examples/demo-dual-tier.mjs my-bucket video/abc.mp4

每个 demo 不到 30 行，就是最好的用法文档。

快速开始（当 npm 包用）

pnpm add @one2x/visionular

import { transcode } from '@one2x/visionular';

const result = await transcode({
  source: { bucket: 'my-bucket', key: 'video/abc.mp4' }, // S3 源
  // source: { url: 'https://...' },                     // 或公网 URL
  // source: { bucket, key, buffer },                    // 或本地文件（自动先上传）
  tier: '480p',                                          // '1080p' | '480p' | 双档数组
  saveTo: { bucket: 'my-bucket', key: 'video/abc-480p.mp4' },
});

需要配置什么

| 项 | 环境变量 | 说明 | |---|---|---| | 微帧凭证 | VISIONULAR_ACCESS_KEY / VISIONULAR_SECRET_KEY | 找运维/微帧对接人；其余均有公司默认值可不配 | | AWS 凭证 | AWS 标准凭证链（~/.aws / IRSA / AWS_*） | 操作你自己的桶用你自己的身份 |

权限前提（运维一次性）：你的 AWS 身份需能读写你自己的桶、能读中转桶 memota-external-851725565622-us-west-2。transcode() 默认先跑 preflight() 自检，缺权限会立即报错并附上可转发运维的策略文案，不会发出转码任务。

数据流（你的代码不搬运视频数据）

你的源桶 ──预签名URL──→ 微帧转码 ──→ 中转桶 ──S3服务端拷贝──→ 你的目标桶

高级用法

import { VisionularClient, preflight } from '@one2x/visionular';

const client = new VisionularClient();            // 需要自定义时逐个调用
const taskId = await client.createTask({...});
await client.waitTask(taskId);                    // 轮询到终态（可设间隔/超时）

await preflight({ source: {...}, saveTo: {...} }); // 只跑自检看报告

错误类型（都带可操作信息）

• PreflightError：自检失败清单 + 给运维的策略文案
• TranscodeFailedError / TranscodeTimeoutError：微帧侧失败/超时
• OutputValidationError：产物码率超档位上限（不拷回目标桶，坏产物不落地）

模板参数背景（为什么是 480p/1080p 两档）

公司模板实测结论：分辨率短边自适应（横竖屏/超宽自动处理、小源不放大）、码率为上限语义（1080P ≤2.5M、480P ≤800k）、低码率源不会被拉高但可能轻微反向膨胀。SDK 的产物校验即基于此。