在 Remotion Monorepo 中本地启动 Convert 视频转换应用从仓库构建到浏览器预览的完整实操指南【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion本篇指南以仓库中的 convert 技能定义 为核心线索讲解如何在本仓库Remotion Monorepo中完成环境准备、编译工作区依赖、启动remotion/convert本地开发服务器并在浏览器中打开 UI。读完本文你既能按照可复现的命令跑通convert.remotion.dev的本地版本也能理解 Convert 应用背后的包结构、Remix Vite 构建配置与源码级实现方便在此基础上进行调试、二次开发或 Agent 自动化调用。一、该技能是什么一条面向 Agent 与开发者的启动流程在仓库 .agents/skills/convert/SKILL.md 中定义了一个名为convert的 Agent 技能。它的 Frontmatter 明确了触发条件与目标--- name: convert description: Start the local remotion/convert app and open it in the Codex browser. Use when the user invokes /convert or $convert, asks to launch convert.remotion.dev locally, or wants to inspect the Convert package UI. ---从描述可以看出该技能服务的对象是仓库中真实的 packages/convert 包——一个可以在本地启动的“视频转换器”Web 应用。触发方式包括显式调用/convert、$convert或当用户要求本地启动convert.remotion.dev、查看 Convert 包 UI 时自动激活。技能文档将其工作拆解为“Prepare → Launch → Verify”三步本质是一个最小可执行的本地启动清单在仓库根目录执行依赖安装与编译bun i bun run build在packages/convert目录下启动 Vite/Remix 开发服务器bun run dev保持进程运行从终端输出中解析本地 URL并交由浏览器工具打开。值得注意的是该技能并非孤立存在。仓库根 package.json 中提供了checkskills、syncskills等脚本内部调用packages/skills/scripts/sync-agent-skills.ts、validate-links.ts等用于同步与校验.agents/skills/**/SKILL.md这类技能文件.agents/skills/convert/agents/openai.yaml还提供了面向 Agent 的接口描述display_name 为 Convert Appdefault_prompt 为 “Use $convert to build Remotion and open the Convert app locally.”。这表明它是一套与仓库同步维护、可被 Agent 工具系统识别和调用的一等公民工作流。二、Convert App 是什么Mediabunny 驱动的浏览器端视频转换器在深入启动流程前先建立对目标应用的整体认知。packages/convert/README.md 只有短短两段话却给出了最准确的产品定位The source code for remotion.dev/convert, a fast video converter powered by Mediabunny.也就是说remotion/convert是线上remotion.dev/convert其 package.json 的homepage字段亦指向https://convert.remotion.dev的源码所在其核心能力是基于 Mediabunny 驱动的视频转换。该包在 packages/convert/package.json 中标注为private、remotion/convert、版本号与 monorepo 保持一致并以 “Video conversion tool - convert.remotion.dev” 作为描述遵循 MIT 许可。从源码结构与依赖看它的能力边界packages/convert/package.json 的依赖项直接揭示了功能构成依赖类别具体依赖推断用途编码器mediabunny/mp3-encoder、aac-encoder、flac-encoder、prores、ac3、dts音视频转码为不同容器 / 编码格式播放器与流媒体vidstack/react、hls.js、mux/upchunk预览播放、HLS 流与分块上传解码与算法mediabunny、fast-average-color核心媒体处理、取帧取色Remotion 家族remotion/captions、remotion/media、remotion/paths、remotion/player、remotion/shapes、remotion/timeline-utils、remotion/whisper-webgpu、remotion/design、remotion/layout-utils、remotion/mac-cursors字幕、媒体元数据、路径几何、播放器、时间轴与语音转写等进一步看 packages/convert/app/routes 的路由文件可以清晰地枚举出应用提供的工具页面_index.tsx——应用首页 / 落地页convert._index.tsx、convert.$action.tsx——核心“转换”工作流trim._index.tsx、trim.$format.tsx——视频裁剪Trimcrop._index.tsx、crop.$format.tsx——画面裁剪Croprotate._index.tsx、rotate.$format.tsx——旋转mirror._index.tsx、mirror.$format.tsx——镜像翻转resize._index.tsx、resize.$format.tsx——尺寸调整timing-editor._index.tsx——时间轴 / 时序编辑transcribe._index.tsx——语音转字幕/转写对应用了remotion/whisper-webgpu这一 WebGPU 端 Whisper 实现probe._index.tsx——媒体探测查看容器、流与元数据report._index.tsx——问题反馈结合mux/upchunk依赖推断其支持上传媒体样本。$format参数化路由的存在说明裁剪、旋转等操作针对不同输出格式如 mp4、webm 等存在独立页面分支。从工程引用看packages/convert/tsconfig.json 将../media-parser、../webcodecs、../design作为 TypeScript 工程引用并且 lib 中启用了WebWorker与 DOM WebCodecs 相关类型。这印证了 Convert 的转换管线与仓库内 packages/media-parser媒体解析、packages/webcodecs基于 WebCodecs 的浏览器端编码紧密耦合——从源码结构可以推断它的核心卖点是把解析、转码、转写等重活放在浏览器本地或 Worker完成转换速度快且无需上传服务端。三、启动前环境准备明确这套命令的运行前提SKILL.md 的 Workflow 第一步默认了环境已经具备或即将完成两件事理解它们有助于避免“命令报错却不知为何”包管理器为 Bun仓库根 package.json 声明packageManager: bun1.3.3。所有安装、脚本执行都围绕 Bun 展开如bun i、bun run build、bun test test。如果本机 Bun 版本差异过大建议先按bun1.3.3对齐。运行时版本packages/convert/package.json 的engines声明node: 20.0.0开发 Convert 包时应确保 Node.js 不低于 20。Monorepo 工作区根 package.json 将packages/**全部纳入 npm workspacesremotion/convert即位于其中通过workspace:*协议引用同仓库包例如remotion/media、remotion/whisper-webgpu。这意味着“安装依赖”必须在仓库根执行一次才能解析所有 workspace 包。注意本仓库为只读用途。上述命令只用于“查看、安装、运行、配置”的本地演示场景请勿以修改仓库文件为目的执行。四、逐步实操按技能文档启动 Convert 本地服务下面完整复现 SKILL.md 的 5 步工作流并对每一步补充执行细节与故障排查要点。步骤 1在仓库根目录安装依赖并预编译工作区bun i bun run buildbun i依据根bun.lock与workspaces配置一次性安装全部 workspace 的依赖。bun run build对应根 package.json 中的build: turbo run make --no-update-notifier即通过 Turborepo 触发各包make任务。这一步并非可有可无remotion/convert在 dev 模式下会依赖同仓库的remotion/media、remotion/design、remotion/media-parser、remotion/webcodecs、remotion/whisper-webgpu等包这些包需要先生成各自的构建产物dist / 原生绑定等Convert 的 Vite dev server 才能正常解析workspace:*导入。首次执行时bun i可能耗时较长monorepo 依赖树很大bun run build也会按拓扑顺序编译多个包请耐心等待其完成、退出码为 0。步骤 2在 Convert 包目录内启动开发服务器cd packages/convert bun run devbun run dev解析到 packages/convert/package.json 中的dev: remix vite:dev——即通过 Remix 的 Vite 插件启动开发服务器而不是直接vite。这里存在一个容易踩的细节技能文档假定你已经身处仓库根目录因此先cd packages/convert再执行。若直接在工作区根运行会因缺少dev脚本而失败。步骤 3保持进程运行并读取终端输出的 URLSKILL.md 明确要求“Keep the server process running and read its output for the local URL.” 也就是说不要让 dev server 在后台被回收或中断——Convert 的入口 HTML、HMR 与路由都依赖这个常驻进程。预期默认端口为http://localhost:5173这是 Vite 的默认端口。如果 5173 被占用Vite 会自动递增选择下一个可用端口并在终端打印最终地址因此请“follow the printed URL if Vite chooses another port”不要盲目假设端口。步骤 4在浏览器中打开本地 URL 并完成验证打开后依据 packages/convert/app/root.tsx应用会以Remotion Convert作为文档标题、bg-slate-50作为页面底色渲染并加载 manifest 与 favicon。此时可以在首页验证各工具入口Trim / Crop / Rotate / Mirror / Resize / Transcribe / Probe 等路由是否可访问任选一条路由如trim拖入一个本地媒体文件确认 HLS/播放器与转换 UI 能正常初始化。若你是在 Agent 环境中执行SKILL.md 提示如果当前会话还没有可用的浏览器控制工具应先通过tool_search找到“in-app browser control”类工具再用它导航到本地 URL。步骤 5向用户汇报结果技能流程的最后一步要求区分两种状态并明确告知这是一个“全新启动”的服务还是“已经运行中”的服务例如端口已被占用时可能命中先前实例。同时把确切的 Convert URL 交付给用户方便其直接访问。五、Dev 脚本背后的构建配置remix vite:dev在做什么为什么bun run dev能起效、产物如何组织答案在 Convert 包的两份 Vite 配置中。主配置vite.config.tspackages/convert/vite.config.ts 是 dev 与 SSR 构建共用的入口核心要点包括使用remix-run/dev导出的vitePluginRemix Vite 插件并挂载vercelPreset()——说明该应用线上以 Vercel 为部署目标启用一组 Remix v3 未来特性开关v3_singleFetch、v3_lazyRouteDiscovery、v3_fetcherPersist等保持向 Remix 2.17 的演进兼容接入vite-tsconfig-paths使tsconfig.json中定义的~/*、/*路径别名在 Vite 中生效额外配置resolve.alias→./app与 tsconfig 的paths保持一致顶部调用installGlobals()为服务端运行时补齐 fetch 等全局对象。因此当 SKILL.md 告诉你cd packages/convert bun run dev时实际启动的是一个“带 Remix 路由约定、Tailwind 样式、路径别名与 Vercel preset”的 Vite dev server路由文件即 packages/convert/app/routes 下所见的那批*.tsx。SPA 产物配置vite-spa.config.ts值得顺带了解的是Convert 除了普通页面构建还支持纯静态 SPA 产物packages/convert/vite-spa.config.ts 在 Remix 插件中设置ssr: false、buildDirectory: spa-dist并把base设为/convert/对应 package.json 中的build-spa: remix vite:build -c vite-spa.config.ts bun build-service-worker.ts构建完成后还会调用bun build-service-worker.ts生成 Service Worker。结合根布局中引用的manifest.json见 packages/convert/app/root.tsx可以推断该应用支持以 PWA/Service Worker 形式离线缓存静态资源。六、深入验证与二次开发可用脚本与源码地图如果你不只满足于“跑起来”以下是继续深入时可利用的既有设施全部来自仓库真实文件类型检查bun run typecheck即tsc。注意 packages/convert/tsconfig.json 设置了noEmit: true——Vite 负责产出tsc 只做类型把关。单元测试bun run test执行bun test test测试目录位于 packages/convert/test运行环境使用happy-dom/global-registrator见包内 happydom.ts。代码规范bun run lint会先跑tsc再对app目录执行 ESLint。源码入口UI 根组件见 packages/convert/app/root.tsx客户端入口见 packages/convert/app/entry.client.tsxSEO 描述集中管理在 packages/convert/app/seo.ts。想要研究转换引擎本身则应沿工程引用向上追溯packages/media-parser媒体容器/流解析、packages/webcodecsWebCodecs 封装、packages/whisper-webgpu转写能力三者的源码共同构成 Convert 的“发动机”而 packages/convert/tsconfig.json 的references正是这三条链路最直接的索引。七、常见问题速查现象原因与对策bun i报依赖解析错误仓库使用 bun.lock 与 workspaces请在仓库根执行勿在packages/convert内单独安装确认 Bun 版本与packageManager: bun1.3.3接近bun run build失败多为某个 workspace 依赖包构建出错可根据 turbo 输出的包名定位到对应packages/*修复后再重试bun run dev提示脚本不存在未先cd packages/convert该包脚本定义在 packages/convert/package.json打开页面报 404 或白屏dev server 尚未就绪 / 端口被占用请以终端实际打印的 URL 为准默认 5173被占用时 Vite 会自动换端口访问后 UI 无媒体处理能力确认已执行根目录bun run build确保remotion/media、remotion/webcodecs等 workspace 依赖产物存在Node 版本过旧Convert 包engines要求 Node 20请升级运行时后重试总结convert技能文档虽然短小但它浓缩的是一条从“仓库就绪”到“浏览器内使用视频转换器”的完整链路根目录bun i bun run build负责把 Monorepo 工作区及其底层媒体处理依赖编译就绪cd packages/convert bun run dev通过remix vite:dev启动带路由约定的 Vite 开发服务器随后保持进程常驻、读取打印端口并在浏览器中打开即完成验证。结合 packages/convert 的源码、路由结构与依赖清单无论是人工复现、Agent 自动化调用/convert、$convert还是基于 packages/media-parser、packages/webcodecs、packages/whisper-webgpu 做二次开发你都能在这份指南中找到准确的落点。【免费下载链接】remotion Make videos programmatically with React项目地址: https://gitcode.com/GitHub_Trending/re/remotion创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考