如何把 HyperFrames Studio 的项目预览与渲染 API 挂载到自己的服务器

如何把 HyperFrames Studio 的项目预览与渲染 API 挂载到自己的服务器【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes如果你的应用需要自己托管 HyperFrames Studio 的后端——即由你的服务负责项目列表、composition 预览、源码修改回写、缩略图生成和渲染任务启动而不是依赖npx hyperframes preview的内置流程——就需要把hyperframes/studio-server挂载到你自己的服务器上。它返回一个 Hono 应用通过一个 adapter 接口对接你项目的存储、打包、lint 和渲染实现。官方文档明确提醒大多数用户不需要这个包CLI 在运行npx hyperframes preview时已经替你接好了 server 和 Studio只有当你的应用必须自行托管 Studio 后端时才使用它。什么时候需要自己挂载先确认你的场景属于后者你只是想打开一个项目的完整 Studio 编辑器直接运行npx hyperframes preview不需要安装hyperframes/studio-server。你要构建自己的编辑器外壳或让你的服务端承载 Studio 的项目与预览 API使用本文路径。新集成统一从hyperframes/studio-server导入。hyperframes/core/studio-api只是保留的废弃兼容 re-export不要在新代码里继续用它。参考实现可以直接读仓库里的两个官方 adapterCLI 内嵌服务器 packages/cli/src/server/studioServer.tshyperframes preview在仓库外运行时使用的单项目、进程内渲染 adapter以及 Studio 的 vite 开发服务器 packages/studio/vite.config.ts。两者都调用同一个createStudioApi各自提供 host 专属的 adapter见 createStudioApi.ts 头部注释。安装包并挂载 API在你的应用目录下安装npm install hyperframes/studio-servercreateStudioApi()接收一个 adapter返回包含全部 Studio API 路由的 Hono 子应用。挂载方式与官方文档一致/api前缀是文档示例使用的路径adapter是你自己实现的StudioApiAdapterimport type { Hono } from hono; import { createStudioApi, type StudioApiAdapter, } from hyperframes/studio-server; export function mountStudioApi( app: Hono, adapter: StudioApiAdapter, ) { app.route(/api, createStudioApi(adapter)); }adapter 是 Studio 与你的项目存储、bundler、linter、renderer 之间的边界API 路由调用 adapter 的方法你负责把方法落到真实的项目目录和渲染管线上。由于示例代码面向 Hono 应用app.route是 Hono 的方法hono ^4.0.0也是该包的运行时依赖见 package.json你的应用应使用 Hono或在其等价的路由挂载点上调用createStudioApi(adapter)的返回值。挂载后/api下注册的完整路由集包括 projects、storyboard、files、preview、lint、render、thumbnail、selection、media、waveform、fonts、registry、globalAssets 等路由组见 createStudioApi.ts。实现 StudioApiAdapter 契约adapter 的完整类型定义在 packages/studio-server/src/types.ts。必选成员是成员签名职责listProjects(): PromiseResolvedProject[] \| ResolvedProject[]列出所有可用项目resolveProject(id: string): PromiseResolvedProject \| null \| ...把项目 ID或 session ID解析到目录未找到返回nullbundle(projectDir: string): Promisestring \| null把项目目录打包成单个 HTML 字符串不可用时返回nulllint(html: string, opts?: { filePath?: string }) PromiseLintResult \| LintResultlint 单个 HTML 字符串runtimeUrlstring属性hyperframe 运行时 JS 的 URL会注入到预览 HTML 中rendersDir(project: ResolvedProject): string渲染输出文件的存储目录startRender(opts: {...}) RenderJobState启动渲染任务adapter 拥有异步执行并必须响应式地更新返回的RenderJobState对象startRender的入参里几个容易踩坑的字段均来自 types.ts 的注释formatmp4 | webm | mov。fpsHTTP 层POST /projects/:id/render既接受 JSON 数字整数帧率如30也接受 ffmpeg 风格有理数字符串如30000/1001路由会把两者归一化为有理数形式的Fps后才调用 adapter所以 adapter 实现只会看到有理数形式。composition相对projectDir的入口文件如compositions/intro.html默认index.html。variablescomposition 变量覆盖{variableId: value}与hyperframes render --variables走同一通道。可选成员不实现时对应能力不可用可选成员用途lintProjectlint 完整项目包括文件间关系单文件lint保留为旧版 adapter 的兼容回退getProjectSignature项目文件的缓存签名用于使预览帧缓存失效transformPreviewHtml在 Studio 增强之前对预览 HTML 做后处理适合预览需要镜像渲染期编译步骤的场景generateThumbnail在路由指定的输出尺寸下生成缩略图resolveSession把 session ID 解析到项目多项目模式listRegistryCatalog/installRegistryBlock列出 / 安装 registry 条目blocks componentsstartBackgroundRemoval启动背景移除媒体处理任务官方文档对此有一条明确的边界以你安装的版本导出的接口作为精确契约它随着 Studio 获得新能力而变化。也就是说不要对着某个固定版本的字段清单开发升级包时重新核对类型。渲染任务的执行与结果判定startRender返回一个RenderJobState对象定义见 types.ts渲染结果围绕它的状态生命周期判定export interface RenderJobState { id: string; status: rendering | complete | failed | cancelled; progress: number; stage?: string; outputPath: string; error?: string; cancel?: () void; }你的 adapter 在后台执行渲染并响应式地更新这个对象的status与progressSSE 进度处理器轮询的就是这个状态。status到达complete表示该任务产出完成outputPath指向输出文件所在目录由 adapter 的rendersDir(project)约定failed时error携带错误信息。cancel是可选的中断钩子取消路由会调用它来停止进行中的渲染不能中断的 adapter 可以省略它取消路由仍会把任务标记为cancelled使 SSE 流正常结束。预览与渲染虽然共用同一套可 seek 的 composition 契约但预览依赖浏览器实时播放渲染逐帧抓取——重项目可能在预览时卡顿却仍会渲染出每一帧见 docs/packages/studio.mdx。托管后端时不要把预览的播放流畅度当作渲染质量指标。其他子入口挂载主 API 之外包还导出一组用于渲染侧回放与守卫的子入口用途列来自 docs/packages/studio-server.mdxImport用途hyperframes/studio-server/source-mutation对 composition 源码应用受守卫的修改hyperframes/studio-server/screenshot-clip计算元素截图几何信息hyperframes/studio-server/manual-edits-render-script渲染时重新应用 Studio 手动编辑hyperframes/studio-server/studio-motion-render-script渲染时重新应用 Studio 运动编辑hyperframes/studio-server/draft-markers处理 draft 手势标记hyperframes/studio-server/finite-mutation对源码修改做非有限值守卫hyperframes/studio-server/media-proxy-preview支持预览中的代理媒体如果你的服务器只是承载预览与渲染 API 而暂不需要这些渲染回放能力可以先只挂载主 API涉及 Studio 编辑结果参与渲染时再按需接入对应入口。验证挂载是否生效文档没有提供单独的“健康检查”端点可用的核对路径有两层类型层把你的 adapter 标注为StudioApiAdapter类型并编译。必选成员缺失listProjects、resolveProject、bundle、lint、runtimeUrl、rendersDir、startRender会在类型检查中暴露这是最直接的契约校验。运行层通过/api下的路由触发真实任务。典型闭环是发起一次渲染请求POST /projects/:id/render观察你 adapter 返回的RenderJobState从rendering走到complete并确认outputPath处的文件与rendersDir(project)声明的目录一致失败路径则检查error字段内容。需要注意的限制adapter 契约随 Studio 版本演进升级hyperframes/studio-server后要重新比对类型预览 HTML 中的运行时来自runtimeUrl如果预览里 runtime 加载失败先检查这个属性指向的 URL 是否可访问。更多编辑工作流细节见 Studio 指南。【免费下载链接】hyperframesWrite HTML. Render video. Built for agents.项目地址: https://gitcode.com/GitHub_Trending/hy/hyperframes创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考