Skip to content

The open-source full-stack studio for Opus 5.5 motion video. Reverse engineering for any video. Code video with HTML: recreate, edit and render. BYOA + BYOK · Motion.md · Images, Video, Music & Voice.

16.2 KB
Raw Blame

OpenDesign 编辑器开发

当前产品能力与维护规则见 产品架构 和 文档中心。

编辑器前端完整迁入本仓库,上游为 Hyperframes 0.9.7,commit 3baf81f9a92615507f76fe8de33e489034ee77ec。studio/ 包含原版 src、public、测试和测试素材,Apache-2.0 许可保存在 studio/LICENSE。运行时使用本地源码构建的编辑器。

功能与集成边界

The Motion host now exposes an MVP editor. StudioHost.mvpEditor gates product entry points without deleting native editing, source, history or MCP services. The root route resolves the active project before mounting ArtifactViewer; home, conversation and browser-tab components are not mounted. WorkspaceFrame lists searchable projects, waits for pending saves before switching, and opens the project drawer on demand, including embedded views.

The visible panels are Compositions, Assets, Catalog, Preview, Design, Layers and Timeline. Dock.Root uses fixed positions and motion.mvp.dock.v1 preferences; resizing dividers and restoring their sizes remain supported. Newly enabled fixed panels are added to saved layouts without resetting divider sizes. Panel close/move/reset controls and layout presets are hidden. Side headers offer a collapse toggle; collapsed groups retain their panels in 48px icon rails and give the released space to preview. The toggle restores the last tab and width; rail icons expand their target module. Both sides start collapsed, with the timeline at 30% of dock height; shrinking the host below 900px collapses the sides again. Collapsed sizes are not persisted, and the preview stays mounted. Preview also supports temporary expansion within the editor. The allowed-panel list also rejects programmatic reopening of excluded panels.

The header retains rename, transient save/error status, templates, undo/redo, a version-history button and native export. MVP undo/redo use plain curved arrows and name-plus-shortcut tooltips. The MVP playback row omits browser fullscreen and its keyboard target, with volume, speed and loop controls aligned right. Save status is not a history action and disappears when idle. The sidebar footer keeps theme/language. Integration/model setup, Capture, Inspector toggle and preview/slideshow controls are hidden. The history button opens a right-aligned popover below the trigger, with an independently scrolling version list and the existing restore action. The MVP omits version-pinning buttons, filters and badges. The popover footer contains only the restore button; file-change details and explanatory copy are omitted. History is not a dock tab. Existing native history and Agent version APIs remain unchanged. MVP track headers omit clip-count badges and provide one speaker before visibility for audio and audible video clips (click to mute, hover or focus to adjust volume); batch saves preserve per-clip gain when toggling mute and create one undo step per operation. Video visibility and preview-monitor volume stay independent.

The inspector retains text, font, size, color, three alignments, solid fill and opacity. The MVP hides the Layout section, including X/Y/W/H inputs. The element Ask Agent footer and its empty-state hint are hidden. Advanced animation/style controls, recording, rotation, variables and blur are hidden. Opening an authored project must not remove its existing animations, gradients, effects or styles. Canvas selection, drag, resize, crop, text editing and context actions remain; canvas snapping stays enabled without guide/grid controls.

Timeline editing, snapping, zoom/Fit, imports, track visibility, clip clipboard/delete/split remain. Clip/range Ask Agent entry points are hidden. Generation/image replacement, advanced clip tools, lower undo/redo, keyframes, linked/ripple controls and beats are hidden; thumbnails stay enabled. Keyboard editing and native save/reload guards remain in place.

Undo/redo availability is filtered by the workspace host using history metadata and readable native blob/aside files, without loading media contents. Missing contents, pruned steps and known later file conflicts disable the matching visible undo/redo control; keyboard shortcuts do not dispatch an unavailable step. Adding media can still be undone and redone through the native aside store. Native execution retains its final validation for concurrent changes and I/O failures. This does not change history budgets, pin behavior or MCP retained-version storage.

Hosts passing a custom editHistory handle to useEditHistoryActions must supply canUndo and canRedo from their history view, alongside the step functions. usePersistentEditHistory already supplies these flags.

The sidebar language menu offers English, Simplified Chinese, Japanese, Korean, German, French, Russian, Spanish, Brazilian Portuguese, Italian and Turkish. The first launch still defaults to Simplified Chinese; motion.studio.locale stores the preference in browser localStorage and synchronizes it between same-origin windows. The document language and browser-tab title follow the selected locale. Unsupported or removed preferences fall back to Chinese. studio/src/i18n/messages.ts owns the supported languages, English message keys, dictionaries, interpolation and locale-aware plural forms; I18n.tsx provides the React context and Intl date/number formatting. Missing messages fall back to the English source.

Simplified Chinese interface copy uses “项目” for a project throughout the editor and connection pages. This display terminology leaves English message keys, API fields, project identifiers and local directory names unchanged.

Localization covers editor labels, tooltips, placeholders, empty/error states and the embedded MCP/template dialog. The DOM fragment updates bound labels in place, preserving the selected client, searches and live media. Switching language does not remount the editor, change Dock layout, modify property values or translate authored text, project/template titles, source paths and protocol identifiers. Property sections receive English source titles and translate them only for display, so duplicate translations cannot change their internal IDs. README/Skill/installer translations, third-party template descriptions, copied Agent instructions and long connection guides are outside this interface change. MVP additions use mvp-zh-CN.json, mvp-ui.json and error-ui.json. The eleven languages cover preparation progress and failures, import retry, asset-name validation, common editing feedback and media fit/crop labels. Retained advanced effects, audio processing and block-parameter additions may still fall back to English outside the MVP. Known-message detection includes the error dictionary, so recognized guidance is preserved by error summaries. Privacy, diagnostic-export and template feedback keep source message keys in state and translate them on render; changing language does not repeat a privacy request. Template filter labels use the same display translation in the sidebar and dialog, while brand names and stored filter values remain unchanged. New locale dictionaries include machine-translated text; automated key/placeholder checks do not replace native-speaker review.

Header Export opens a compact, right-aligned popover below the button with settings and task history, replacing the MVP Renders tab. Opening it does not start a render; its Export action continues using the native render queue, retaining MP4/MOV/WebM/GIF, resolution, frame rate, quality, cancellation, progress, render history and download. GIF retains native loop-count controls and the 30 fps limit. Composition-row render actions and GPU controls are hidden. 一期插件 openmotion_export_request 仍提供独立的后台快照渲染,供 Agent 使用;不会替代界面的原生导出。

品牌宿主隐藏上游桌面下载推广与反馈邀约,相关上游组件仍保留在源码中。Studio 的原生暗色/浅色偏好由 hf-studio-ui-preferences 管理;data-theme="paper" 为浅色,无属性为暗色。设计系统变量映射到这一机制,不再使用第二套编辑器主题状态。

前端可以直接修改。CLI 服务、core、parsers、player、SDK 与渲染器使用锁定的 0.9.7 npm 包,并未复制整个 monorepo。桌面端的宿主功能以开源 Studio 的实际能力为准。

修改入口

先用 产品架构 判断需求归属;多模态入口、原图修改和后续属性面板接入遵循 素材生成设计。该设计记录用户意图、候选采用、原生历史与过期目标的边界,本页维护实现位置。

Model configuration and media generation are hidden in the MVP editor. MediaGatewayProvider remains mounted for native import; the Gateway backend and external Agent tools are unchanged. Asset context menus expose rename/delete; drag-to-timeline and uploads keep their native paths.

TimelineMediaBar and the fallback range EditPopover are not mounted in the MVP, so selecting clips, the ruler or a Shift-range does not open an Agent prompt. The legacy generation and image replacement implementation is retained for non-MVP hosts. Existing source writes, revision checks and native history must not be bypassed.

MediaRequest.anchor 保存触发元素或时间轴虚拟锚点。useMediaPopoverPosition 共用实际浮层尺寸、滚动监听与 ResizeObserver:优先放在目标上方,空间不足时翻转或限制高度,保持 8px 间距与 12px 视口边距,不再轮询整个时间轴顶部。片段锚点读取可见片段的位置;范围/标尺锚点换算缩放与滚动后的坐标。空态引导在生成面板打开时隐藏且不可聚焦,保留布局以跟随按钮位置;文件拖入仍显示拖放反馈。是否切换到真实轨道继续由原生元素列表决定,不维护另一个“已插入”标记;关闭面板后仍为空或撤销至空轨道时恢复引导。

需求 入口
Direct editor route and project sidebar studio/src/motion/MotionApp.tsx、MotionHome.tsx、WorkspaceFrame.tsx、workspace.css
Save guards and template entry studio/src/motion/MotionStudioHost.tsx、WorkspaceFrame.tsx、useWorkspace.ts
Retained browser runtime (hidden in MVP) browser.ts、shared/browser.ts、studio/src/motion/WebBrowser.tsx;见 浏览器架构
Retained session/conversation modules (hidden in MVP) studio/src/motion/MotionSessionFrame.tsx、ProjectConversation.tsx、artifactBrowser.ts、shared/session.ts、shared/conversation.ts
Legacy home template UI (hidden in MVP) studio/src/motion/HomeTemplates.tsx
宿主插槽 studio/src/motion/StudioHost.tsx、studio/src/components/StudioHeader.tsx
模型设置、生成面板、时间轴桥接 studio/src/motion/ModelSettings.tsx、MediaGenerator.tsx、MediaGatewayContext.tsx、MotionTimelineMedia.tsx
Legacy non-MVP timeline Agent and media actions studio/src/motion/TimelineMediaBar.tsx、timelineMediaSelection.ts;挂载于 Timeline.tsx 的原生 Provider 内;定位共用 mediaPopoverPosition.ts、useMediaPopoverPosition.ts
共享生成合约与服务 shared/gateway.ts、gateway/、server.ts、mcp.ts
原生 Capture、Inspector、Export studio/src/components/StudioHeader.tsx
模板画廊、视频预览、出处与热度 web/template-gallery.ts、web/template-gallery.css、template-catalog.ts
内置原生模板与工程副本 template-library.ts、template-library/
MCP 与模板统一弹框、配置下载与 Agent 指引 studio/src/motion/ConnectionDialog.tsx、web/connect.*、shared/integration.ts
设计变量 web/design-system/tokens.json,执行 npm run design:tokens
编辑器主题 studio/src/motion/theme.css
Dock 与面板注册 studio/src/components/dock/
Legacy preview/layout presets (hidden in MVP) studio/src/motion/MotionLayoutControls.tsx
Version-history popover and retained native history API studio/src/motion/MotionHistoryPopover.tsx, MotionHistoryPanel.tsx
Editor language resources, formatting and language menu studio/src/i18n/
时间轴、片段、关键帧 studio/src/player/
画布、属性与动画编辑 studio/src/components/editor/
素材、合成、Catalog studio/src/components/sidebar/
原生导出队列 studio/src/components/renders/
保存、历史、预览刷新 studio/src/hooks/
浏览器 Agent 工具 studio/src/webmcp/
原生 API 转发 editor-server.ts
工程切换、模板与后台导出 server.ts、workspace.ts

服务与工程

/motion-api/ 为产品 API,/api/ 为原生 Studio API。流式代理保留文件版本头、上传体、媒体 Range、SSE 文件变化和渲染进度;只有通过本机 Host/Origin 检查的请求才会转发。

切换工程前等待原生保存队列完成,切换后重新加载文档以释放旧编辑会话。原生渲染、版本写入或写冲突期间,所有入口禁止新建、切换工程、返回首页或应用模板。空白项目和三个官方模板均创建为独立工程,原工程与素材保留。通过 URL 恢复工程时只验证工程及会话归属,再挂载对应 Studio 页面;不会切换其他页面。一个原生服务进程按工程请求复用原生宿主上下文,文件版本冲突仍拒绝覆盖。

新工程使用 CLI 默认的官方 Catalog。启动旧工程时,只移除先前版本误写的 https://hyperframes.heygen.com/registry,该地址返回 404;用户自定义 Registry 与其他配置不变。

UI 主题不会写入影片 HTML、CSS、GSAP 或 Studio 编辑数据,预览与导出均由原版播放器和渲染器处理。MCP 仍共享同一组原生文件与 revision。

构建与验证

npm ci
npm run dev
npm run build:studio
npm run typecheck:studio
npm run check
npm run test:studio
npm test
npm run package:plugin

生产页面使用 studio/build/,前端修改后重新构建并刷新。该目录不提交;插件 ZIP 包含运行时源码、构建产物、使用文档和许可证,不包含个人工程、依赖目录或 sourcemap。

test:studio 启用完整上游单元与 DOM 测试。迁移适配只涉及包路径、独立仓库样式入口、Happy DOM 21 的 iframe 开关、异步弹层收尾,以及由 jsdom 验证的 WebKit 文本填色。原版 Chrome bench 和 E2E 文件保留,*.browser.test.ts 不属于该单元命令。

npm test 覆盖原生 API/MCP 双向编辑、revision 冲突、路径隔离、上传、媒体 Range、SSE、工程切换、模板与真实音视频渲染。Registry 迁移测试保证自定义配置不被覆盖。宿主顶栏测试保证 Export 继续走原版回调,渲染中禁止替换当前工程。

MVP regressions cover fixed panels, excluded-panel guards, divider persistence, embedded sidebar state and hidden controls alongside retained edits/exports. Legacy Dock regressions still cover free layouts outside the MVP host. 历史集成测试使用真实服务验证保留版本在重启后仍存在,恢复不删除后续记录,并可撤销恢复。面板测试覆盖保存失败与原生恢复拒绝,确保失败时不重新加载或替换工程。

The editor template modal reuses the gallery controller but hides integration sections. The standalone integration page retains Codex, Claude Code, DeepSeek Harness and stdio configuration/guides. 配置中的数据目录、Node 路径和端口来自当前运行服务;ChatGPT 云端接入尚无远程端点。一期目录发现由 Studio 或指引链接提供,openmotion_create_project 的 template 类型只复制实际内置原生模板;旧目录/详情/应用 handler 仅作内部兼容,不能按一期 Tool 调用。外部参考由 Agent 分析后写入可编辑原生源文件。数据、封面与热度的维护见 模板目录。

Language regression tests cover all eleven preferences, unavailable storage, same-origin synchronization, interpolation, plural forms and complete dictionary keys. DOM tests check stable section IDs, native property values and label updates without recreating editor inputs, preview iframes or the connection gallery. Real-browser checks remain separate from native-speaker translation and cross-platform acceptance.