dsh-hyperframes 0.4.2 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +26 -0
- package/README.en.md +26 -87
- package/README.md +25 -89
- package/docs/USAGE.en.md +115 -0
- package/docs/USAGE.md +119 -0
- package/docs/VALIDATION.md +24 -0
- package/docs/validation-language-2026-10-03.md +16 -0
- package/lib/client.js +105 -0
- package/lib/index.d.ts +3 -0
- package/lib/index.js +5 -1
- package/lib/media-store.d.ts +25 -0
- package/lib/media-store.js +174 -0
- package/lib/media-templates.d.ts +52 -0
- package/lib/media-templates.js +91 -0
- package/lib/media-workbench.d.ts +42 -0
- package/lib/media-workbench.js +476 -0
- package/package.json +17 -4
- package/templates/DESIGN.md +26 -0
package/CHANGELOG.md
ADDED
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
# 更新记录
|
|
2
|
+
|
|
3
|
+
[返回简介](README.md) · [使用说明](docs/USAGE.md) · [验证记录](docs/VALIDATION.md)
|
|
4
|
+
|
|
5
|
+
## 0.5.1 (2026-10-03)
|
|
6
|
+
|
|
7
|
+
- 视频工作台后台错误与任务阶段支持英文；切换语言重新展示失败引导，项目文字和原始引擎日志保留原文。
|
|
8
|
+
- 验收范围见 [中英文界面检查](docs/validation-language-2026-10-03.md)。
|
|
9
|
+
|
|
10
|
+
## 0.5.0 (2026-10-03)
|
|
11
|
+
|
|
12
|
+
- 新增视频工作台、三种模板、素材副本上传、官方 Studio 预览、本机 MP4 与可编辑 ZIP 备份。
|
|
13
|
+
- 新增修订冲突检查、旧成片提示、任务记录与取消；首次环境准备使用固定版本官方 CLI 0.8.114。
|
|
14
|
+
- 保留现有上游技能；模板与工作台为本仓库原创实现。
|
|
15
|
+
|
|
16
|
+
## 0.4.2 (2026-09-29)
|
|
17
|
+
|
|
18
|
+
- 修正仓库与 npm 包的简介。
|
|
19
|
+
|
|
20
|
+
## 0.4.0 (2026-09-28)
|
|
21
|
+
|
|
22
|
+
- 同步 HyperFrames 官方 v0.8.82 的 21 个技能，保留上游来源。
|
|
23
|
+
|
|
24
|
+
## 更早的改动
|
|
25
|
+
|
|
26
|
+
完整历史可查阅 [GitHub 提交记录](https://github.com/STARDUSTLC666/dsh-hyperframes/commits/master)。
|
package/README.en.md
CHANGED
|
@@ -1,111 +1,50 @@
|
|
|
1
|
-
[中文](README.md)
|
|
2
|
-
|
|
3
|
-
   
|
|
4
|
-
|
|
5
1
|
# dsh-hyperframes
|
|
6
2
|
|
|
7
|
-
[
|
|
3
|
+
[中文](README.md)
|
|
8
4
|
|
|
9
|
-
|
|
5
|
+
Bring HyperFrames HTML video creation skills into DSH.
|
|
10
6
|
|
|
11
|
-
|
|
7
|
+
[](https://www.npmjs.com/package/dsh-hyperframes) [](https://www.npmjs.com/package/dsh-hyperframes)
|
|
12
8
|
|
|
13
|
-
|
|
9
|
+
## What it does
|
|
14
10
|
|
|
15
|
-
|
|
11
|
+
- A settings workbench for templates, editable content, media uploads, official Studio preview and local MP4 export.
|
|
12
|
+
- Title card, product card and slideshow templates in landscape, portrait or square format.
|
|
13
|
+
- Editable project backups, cancellable jobs and a warning when an MP4 uses an older revision.
|
|
16
14
|
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
15
|
+
- Cover animation, audio, captions, keyframes and timeline workflows.
|
|
16
|
+
- Create slideshows, launch videos, music-driven visuals and other formats.
|
|
17
|
+
- Include upstream CLI and Studio guidance plus skill health checks.
|
|
20
18
|
|
|
21
|
-
|
|
19
|
+
## Install
|
|
22
20
|
|
|
23
|
-
|
|
21
|
+
In DSH Desktop, install `dsh-hyperframes` from the Plugins panel. If the bundled dsh command is available:
|
|
24
22
|
|
|
25
23
|
```bash
|
|
26
|
-
dsh plugin --profile
|
|
24
|
+
dsh plugin --profile desktop add dsh-hyperframes
|
|
27
25
|
```
|
|
28
26
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
## Skills
|
|
33
|
-
|
|
34
|
-
| Skill | Purpose |
|
|
35
|
-
| :-- | :-- |
|
|
36
|
-
| `hyperframes` | Router: HTML video compositions (styles/palettes/captions/audio-reactive/transitions) |
|
|
37
|
-
| `hyperframes-core` | Core concepts and component model |
|
|
38
|
-
| `hyperframes-animation` | Animation: GSAP/Anime.js/Lottie/Three.js/WAAPI adapters |
|
|
39
|
-
| `hyperframes-audio` | Audio: voiceovers, audio-reactive visuals |
|
|
40
|
-
| `hyperframes-keyframes` | Keyframe animation |
|
|
41
|
-
| `hyperframes-creative` | Creative templates and styles |
|
|
42
|
-
| `hyperframes-cli` | `npx hyperframes` CLI (init/check/preview/render/timeline/publish/cloud/transcribe/tts/doctor, ...) |
|
|
43
|
-
| `hyperframes-registry` | `hyperframes add` registry block installation and wiring |
|
|
44
|
-
| `hyperframes-studio` | Studio timeline conventions: track layering, caption track, safe zones |
|
|
45
|
-
| `embedded-captions` | Embedded captions |
|
|
46
|
-
| `faceless-explainer` | Faceless explainer videos |
|
|
47
|
-
| `figma` | Figma asset integration |
|
|
48
|
-
| `general-video` | General video production |
|
|
49
|
-
| `media-use` | Media usage guidelines |
|
|
50
|
-
| `motion-graphics` | Motion graphics |
|
|
51
|
-
| `music-to-video` | Music-driven video |
|
|
52
|
-
| `pr-to-video` | PR-to-video |
|
|
53
|
-
| `product-launch-video` | Product launch videos |
|
|
54
|
-
| `remotion-to-hyperframes` | Remotion project migration |
|
|
55
|
-
| `slideshow` | Slideshow videos |
|
|
56
|
-
| `talking-head-recut` | Talking-head recuts |
|
|
57
|
-
|
|
58
|
-
## Requirements
|
|
59
|
-
|
|
60
|
-
Node.js 22.19+ (22.x) / 24+ + FFmpeg (`npx hyperframes`).
|
|
61
|
-
|
|
62
|
-
## Porting notes
|
|
63
|
-
|
|
64
|
-
Synced from the official `heygen-com/hyperframes` repository at v0.8.82 (2026-09-28): the complete packaged `skills/` tree, 21 skills, copied as-is with no frontmatter changes. Since v0.8.20, `hyperframes-studio` (Studio timeline conventions) is new, the brief/storyboard/script docs moved from `hyperframes-core` to the `hyperframes` skill, `media-use` and `music-to-video` were substantially reworked (built-in motion primitives), and the `embedded-captions` scripts were upgraded upstream.
|
|
27
|
+
For the web version, replace `desktop` with `web`. Restart DSH after installation.
|
|
65
28
|
|
|
66
|
-
##
|
|
29
|
+
## Start using it
|
|
67
30
|
|
|
68
|
-
|
|
31
|
+
Open Settings → HyperFrames → New video. Save your content, then upload media. Prepare the render environment on first use, inspect the official Studio preview, stop it and export MP4.
|
|
69
32
|
|
|
70
|
-
|
|
71
|
-
| :-- | :-- |
|
|
72
|
-
| Claude Code | `~/.claude/skills/` |
|
|
73
|
-
| Cursor | `.cursor/skills/` (or project-local `skills/`) |
|
|
74
|
-
| Gemini CLI | `~/.gemini/skills/` |
|
|
75
|
-
| OpenAI Codex | `~/.codex/skills/` |
|
|
33
|
+
Ask: “Make a short video from this material with HyperFrames, preview it, then render MP4.” The assistant follows the skills to create a project and run the renderer.
|
|
76
34
|
|
|
77
|
-
|
|
35
|
+
## Requirements and configuration
|
|
78
36
|
|
|
37
|
+
The plugin preserves upstream skills and adds a local workbench. First use needs Node.js 22.19+ / 24+ and npm; FFmpeg must also be in PATH. Dependencies are downloaded only when you explicitly prepare the environment.
|
|
79
38
|
|
|
80
|
-
|
|
39
|
+
Detailed configuration, tool arguments and troubleshooting are in the [usage guide](docs/USAGE.en.md). For standalone development, follow the Node requirement in [package.json](package.json).
|
|
81
40
|
|
|
82
|
-
|
|
83
|
-
|
|
84
|
-
Health checks do not mutate files or registrations. After changing a file or repairing one that failed initial loading, reload the plugin (or restart DSH). The result reports `changed`, `not_registered` or `registration_failed` until then. A previously loaded file that was temporarily missing becomes healthy again if its exact original content is restored and its registration remains active.
|
|
85
|
-
|
|
86
|
-
Each item retains `name / ok / detail` and adds `code / fileOk / registered / registryChecked / reloadRequired`. `registered` means the registry still matches the loaded version, so a changed file can have `registered: true` and `ok: false`. Missing or failed registry lookup produces `registry_unavailable`; a disposed plugin produces `disposed`. The public `checkBundledSkills()` is disk-only, while the original non-throwing `parseSkillFile()` helper remains available.
|
|
87
|
-
|
|
88
|
-
## Development and shared implementation
|
|
89
|
-
|
|
90
|
-
`src/index.ts` declares only package identity, skill names and the resource directory. Parsing, validation, registration and health logic live in `src/skill-bundle.ts`. The canonical source is in `dsh-hyperframes`; Remotion carries an identical version-controlled copy. Each package builds and ships its own `lib/skill-bundle.js`, with no cross-package runtime dependency and no sibling checkout required for building or installation.
|
|
91
|
-
|
|
92
|
-
With dependencies already installed:
|
|
93
|
-
|
|
94
|
-
```bash
|
|
95
|
-
node node_modules/typescript/bin/tsc -p tsconfig.json
|
|
96
|
-
node --test "test/*.test.mjs"
|
|
97
|
-
```
|
|
98
|
-
|
|
99
|
-
When developing the sibling repositories together, edit the shared module and regression tests in HyperFrames, then synchronize:
|
|
100
|
-
|
|
101
|
-
```bash
|
|
102
|
-
# Run in dsh-hyperframes; updates only three shared files in sibling dsh-remotion
|
|
103
|
-
node scripts/sync-skill-bundle.mjs
|
|
104
|
-
node scripts/sync-skill-bundle.mjs --check
|
|
105
|
-
```
|
|
41
|
+
## Documentation
|
|
106
42
|
|
|
107
|
-
|
|
43
|
+
- [Usage and troubleshooting](docs/USAGE.en.md)
|
|
44
|
+
- [Changelog](CHANGELOG.md)
|
|
45
|
+
- [Validation scope and history](docs/VALIDATION.md)
|
|
46
|
+
- [Report a problem or suggest a feature](https://github.com/STARDUSTLC666/dsh-hyperframes/issues)
|
|
108
47
|
|
|
109
48
|
## License
|
|
110
49
|
|
|
111
|
-
MIT
|
|
50
|
+
[MIT](LICENSE). Upstream skill licensing is documented in the usage guide.
|
package/README.md
CHANGED
|
@@ -1,114 +1,50 @@
|
|
|
1
|
-
[English](README.en.md)
|
|
2
|
-
|
|
3
1
|
# dsh-hyperframes
|
|
4
2
|
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
   
|
|
3
|
+
[English](README.en.md)
|
|
8
4
|
|
|
9
|
-
|
|
5
|
+
把 HyperFrames 的 HTML 视频创作技能接入 DSH。
|
|
10
6
|
|
|
7
|
+
[](https://www.npmjs.com/package/dsh-hyperframes) [](https://www.npmjs.com/package/dsh-hyperframes)
|
|
11
8
|
|
|
12
|
-
|
|
9
|
+
## 功能
|
|
13
10
|
|
|
14
|
-
|
|
11
|
+
- 设置页视频工作台：选模板、编辑内容、上传素材，在官方 Studio 预览并导出本机 MP4。
|
|
12
|
+
- 提供标题卡、产品介绍、图文轮播；支持横屏、竖屏和正方形。
|
|
13
|
+
- 保留可编辑工程备份、渲染记录与取消操作；工程修改后提醒重新导出。
|
|
15
14
|
|
|
16
|
-
|
|
15
|
+
- 提供动画、音频、字幕、关键帧和时间轴工作流。
|
|
16
|
+
- 支持幻灯片、产品发布、音乐驱动等创作场景。
|
|
17
|
+
- 保留官方 CLI / Studio 指引与技能自检。
|
|
17
18
|
|
|
18
19
|
## 安装
|
|
19
20
|
|
|
20
|
-
|
|
21
|
-
dsh plugin --profile web add dsh-hyperframes
|
|
22
|
-
```
|
|
23
|
-
|
|
24
|
-
重启后说「把这个网址做成 HyperFrames 视频」即可触发。
|
|
25
|
-
|
|
26
|
-
## 卸载
|
|
21
|
+
桌面版可在「插件」面板按包名 `dsh-hyperframes` 安装。已配置 dsh 命令时也可使用：
|
|
27
22
|
|
|
28
23
|
```bash
|
|
29
|
-
dsh plugin --profile
|
|
24
|
+
dsh plugin --profile desktop add dsh-hyperframes
|
|
30
25
|
```
|
|
31
26
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
## 技能清单
|
|
36
|
-
|
|
37
|
-
| 技能 | 用途 |
|
|
38
|
-
| :-- | :-- |
|
|
39
|
-
| `hyperframes` | 总纲：HTML 视频合成（视觉风格/调色板/字幕/音频响应/转场）|
|
|
40
|
-
| `hyperframes-core` | 核心概念与组件模型 |
|
|
41
|
-
| `hyperframes-animation` | 动画：GSAP/Anime.js/Lottie/Three.js/WAAPI 适配 |
|
|
42
|
-
| `hyperframes-audio` | 音频：配音、音频响应视觉 |
|
|
43
|
-
| `hyperframes-keyframes` | 关键帧动画 |
|
|
44
|
-
| `hyperframes-creative` | 创意模板与风格 |
|
|
45
|
-
| `hyperframes-cli` | `npx hyperframes` 命令行（init/check/preview/render/timeline/publish/cloud/transcribe/tts/doctor…）|
|
|
46
|
-
| `hyperframes-registry` | `hyperframes add` 注册表组件安装与接线 |
|
|
47
|
-
| `hyperframes-studio` | Studio 时间轴规范：轨道分层、字幕轨、安全区 |
|
|
48
|
-
| `embedded-captions` | 内嵌字幕 |
|
|
49
|
-
| `faceless-explainer` | 无脸讲解视频 |
|
|
50
|
-
| `figma` | Figma 素材接入 |
|
|
51
|
-
| `general-video` | 通用视频制作 |
|
|
52
|
-
| `media-use` | 媒体素材使用规范 |
|
|
53
|
-
| `motion-graphics` | 动态图形 |
|
|
54
|
-
| `music-to-video` | 音乐驱动视频 |
|
|
55
|
-
| `pr-to-video` | PR 转视频 |
|
|
56
|
-
| `product-launch-video` | 产品发布视频 |
|
|
57
|
-
| `remotion-to-hyperframes` | Remotion 项目迁移 |
|
|
58
|
-
| `slideshow` | 幻灯片视频 |
|
|
59
|
-
| `talking-head-recut` | 口播重剪 |
|
|
60
|
-
|
|
61
|
-
## 依赖
|
|
62
|
-
|
|
63
|
-
Node.js 22.19+ (22.x) / 24+ + FFmpeg（`npx hyperframes`）。
|
|
64
|
-
|
|
65
|
-
## 移植说明
|
|
27
|
+
网页版把命令中的 `desktop` 改为 `web`。安装后重启 DSH。
|
|
66
28
|
|
|
67
|
-
|
|
29
|
+
## 开始使用
|
|
68
30
|
|
|
69
|
-
|
|
31
|
+
打开「设置 → HyperFrames」→「新建视频」，填写内容并保存，再上传素材。首次点击「准备渲染环境」下载依赖，完成后启动官方预览，检查画面、停止预览，再导出 MP4。
|
|
70
32
|
|
|
71
|
-
|
|
33
|
+
可说：“用 HyperFrames 把这份材料做成短视频，先预览，再渲染 MP4。”助手会按技能指引建立项目和调用渲染工具。
|
|
72
34
|
|
|
73
|
-
|
|
74
|
-
| :-- | :-- |
|
|
75
|
-
| Claude Code | `~/.claude/skills/` |
|
|
76
|
-
| Cursor | `.cursor/skills/`（或项目内 `skills/`）|
|
|
77
|
-
| Gemini CLI | `~/.gemini/skills/` |
|
|
78
|
-
| OpenAI Codex | `~/.codex/skills/` |
|
|
35
|
+
## 依赖与配置
|
|
79
36
|
|
|
80
|
-
|
|
37
|
+
插件保留上游技能，并新增本地视频工作台。首次使用需 Node.js 22.19+ / 24+ 与 npm；还需 PATH 中可用的 FFmpeg。不会在 DSH 启动时自动下载依赖。
|
|
81
38
|
|
|
39
|
+
详细配置、工具参数与排错见[使用说明](docs/USAGE.md)。从源码独立开发时，Node 要求以 [package.json](package.json) 为准。
|
|
82
40
|
|
|
83
|
-
##
|
|
84
|
-
|
|
85
|
-
运行 `hyperframes_health` 会重新读取每个 `SKILL.md`，验证文件可读、YAML frontmatter 合法、名称与目录一致、描述与正文非空，再通过宿主 `skills.get` 确认实际生效的名称、描述、正文和资源目录与本次加载内容相符。文件存在但未注册、注册失败或后来被移除时，自检都会失败。
|
|
86
|
-
|
|
87
|
-
自检不修改文件或注册表。修改技能文件，或修复加载时损坏的技能后，应重载插件（也可重启 DSH）。它会报告 `changed`、`not_registered` 或 `registration_failed`，不会把磁盘修复直接当成运行时修复。若原先已成功加载，只是文件暂时丢失，恢复与加载时完全相同的内容即可重新通过检查。
|
|
88
|
-
|
|
89
|
-
每项结果保留 `name / ok / detail`，并增加 `code / fileOk / registered / registryChecked / reloadRequired`：`registered` 表示注册表仍匹配加载时的版本，因此文件变更时它可以为 true 而 `ok` 为 false。缺少或无法查询宿主注册表时返回 `registry_unavailable`；插件卸载后返回 `disposed`。`checkBundledSkills()` 仅检查磁盘文件，不推断运行时状态；原有不抛错的 `parseSkillFile()` 解析入口保持可用。
|
|
90
|
-
|
|
91
|
-
## 开发与共享实现
|
|
92
|
-
|
|
93
|
-
`src/index.ts` 只声明包名、技能清单和目录，解析、校验、注册与自检集中在包内 `src/skill-bundle.ts`。规范源位于 `dsh-hyperframes/src/skill-bundle.ts`，Remotion 保存相同的受版本控制副本；两包都编译并分发自己的 `lib/skill-bundle.js`，没有跨包运行时依赖，也不需要另一个仓库即可构建或安装。
|
|
94
|
-
|
|
95
|
-
依赖预先安装后，可直接离线构建和测试：
|
|
96
|
-
|
|
97
|
-
```bash
|
|
98
|
-
node node_modules/typescript/bin/tsc -p tsconfig.json
|
|
99
|
-
node --test "test/*.test.mjs"
|
|
100
|
-
```
|
|
101
|
-
|
|
102
|
-
两个仓库并列开发时，在 HyperFrames 修改公共模块与公共回归测试，再同步：
|
|
103
|
-
|
|
104
|
-
```bash
|
|
105
|
-
# 在 dsh-hyperframes 中执行；只更新相邻 dsh-remotion 的三个公共文件
|
|
106
|
-
node scripts/sync-skill-bundle.mjs
|
|
107
|
-
node scripts/sync-skill-bundle.mjs --check
|
|
108
|
-
```
|
|
41
|
+
## 文档
|
|
109
42
|
|
|
110
|
-
|
|
43
|
+
- [使用与排错](docs/USAGE.md)
|
|
44
|
+
- [更新记录](CHANGELOG.md)
|
|
45
|
+
- [验证范围与历史记录](docs/VALIDATION.md)
|
|
46
|
+
- [问题反馈与功能建议](https://github.com/STARDUSTLC666/dsh-hyperframes/issues)
|
|
111
47
|
|
|
112
48
|
## License
|
|
113
49
|
|
|
114
|
-
MIT
|
|
50
|
+
[MIT](LICENSE)。上游技能内容的来源和许可证见使用说明。
|
package/docs/USAGE.en.md
ADDED
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# dsh-hyperframes usage guide
|
|
2
|
+
|
|
3
|
+
[Overview](../README.en.md) · [Changelog](../CHANGELOG.md) · [Validation](VALIDATION.md)
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
dsh plugin --profile web add dsh-hyperframes
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
After restarting, say "turn this website into a HyperFrames video" to trigger it.
|
|
12
|
+
|
|
13
|
+
## Uninstall
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
dsh plugin --profile web remove dsh-hyperframes
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Then restart the web service. To clean up fully, also remove the plugin entry from your profile `cordis.patch.yml` if you overrode it.
|
|
20
|
+
|
|
21
|
+
## Video workbench
|
|
22
|
+
|
|
23
|
+
Open Settings → HyperFrames in DSH Web or Desktop.
|
|
24
|
+
|
|
25
|
+
1. Create a video. Select title card, product card or slideshow; set the title/body, canvas and an integer duration of 3–30 seconds, then save.
|
|
26
|
+
2. Upload local copies of PNG/JPEG images, one MP3/WAV background audio and one muted MP4 background video. Limits: 20 MB per asset, 40 MB total. Slideshows follow upload order and need at least two seconds per image.
|
|
27
|
+
3. Explicitly prepare the environment on first use. It downloads official CLI 0.8.114; Windows uses its managed rendering browser, while other platforms reuse installed Chrome when available. Project editing remains available. FFmpeg must be installed and in PATH; restart DSH after changing PATH.
|
|
28
|
+
4. Start official Studio and inspect the picture. Stop this preview before editing or exporting. No window is opened automatically.
|
|
29
|
+
5. Export, play and download MP4. Later edits preserve earlier MP4s and display a revision warning. Export again for a new final output.
|
|
30
|
+
|
|
31
|
+
The editable ZIP includes source, data and media. Extract it, run npm install, then npm run preview / render as explained by its README. Original template code is MIT; engines retain their own licenses. ZIP import is not yet available in settings.
|
|
32
|
+
|
|
33
|
+
Projects and caches stay in DSH_HOME/data/dsh-hyperframes; Web and Desktop profiles sharing the same DSH_HOME share saved projects; original assets and existing user projects are untouched. Closing settings preserves staged input within this page. Saved projects survive restart, but active jobs stop with DSH. Jobs can be cancelled. Tools: hyperframes_project (list/create/get/update), hyperframes_render (prepare/preview/render/job/cancel). Updates and rendering require id/revision; job/cancel require job id.
|
|
34
|
+
|
|
35
|
+
The workbench supports template edits rather than a full timeline, transcription, TTS or cloud rendering. Default: 24 FPS and 200 MB maximum MP4. Official preview listens on 127.0.0.1 only; other users on the same machine may still reach this local service.
|
|
36
|
+
|
|
37
|
+
## Skills
|
|
38
|
+
|
|
39
|
+
| Skill | Purpose |
|
|
40
|
+
| :-- | :-- |
|
|
41
|
+
| `hyperframes` | Router: HTML video compositions (styles/palettes/captions/audio-reactive/transitions) |
|
|
42
|
+
| `hyperframes-core` | Core concepts and component model |
|
|
43
|
+
| `hyperframes-animation` | Animation: GSAP/Anime.js/Lottie/Three.js/WAAPI adapters |
|
|
44
|
+
| `hyperframes-audio` | Audio: voiceovers, audio-reactive visuals |
|
|
45
|
+
| `hyperframes-keyframes` | Keyframe animation |
|
|
46
|
+
| `hyperframes-creative` | Creative templates and styles |
|
|
47
|
+
| `hyperframes-cli` | `npx hyperframes` CLI (init/check/preview/render/timeline/publish/cloud/transcribe/tts/doctor, ...) |
|
|
48
|
+
| `hyperframes-registry` | `hyperframes add` registry block installation and wiring |
|
|
49
|
+
| `hyperframes-studio` | Studio timeline conventions: track layering, caption track, safe zones |
|
|
50
|
+
| `embedded-captions` | Embedded captions |
|
|
51
|
+
| `faceless-explainer` | Faceless explainer videos |
|
|
52
|
+
| `figma` | Figma asset integration |
|
|
53
|
+
| `general-video` | General video production |
|
|
54
|
+
| `media-use` | Media usage guidelines |
|
|
55
|
+
| `motion-graphics` | Motion graphics |
|
|
56
|
+
| `music-to-video` | Music-driven video |
|
|
57
|
+
| `pr-to-video` | PR-to-video |
|
|
58
|
+
| `product-launch-video` | Product launch videos |
|
|
59
|
+
| `remotion-to-hyperframes` | Remotion project migration |
|
|
60
|
+
| `slideshow` | Slideshow videos |
|
|
61
|
+
| `talking-head-recut` | Talking-head recuts |
|
|
62
|
+
|
|
63
|
+
## Requirements
|
|
64
|
+
|
|
65
|
+
Node.js 22.19+ (22.x) / 24+ + FFmpeg (`npx hyperframes`).
|
|
66
|
+
|
|
67
|
+
## Porting notes
|
|
68
|
+
|
|
69
|
+
Synced from the official `heygen-com/hyperframes` repository at v0.8.82 (2026-09-28): the complete packaged `skills/` tree, 21 skills, copied as-is with no frontmatter changes. Since v0.8.20, `hyperframes-studio` (Studio timeline conventions) is new, the brief/storyboard/script docs moved from `hyperframes-core` to the `hyperframes` skill, `media-use` and `music-to-video` were substantially reworked (built-in motion primitives), and the `embedded-captions` scripts were upgraded upstream.
|
|
70
|
+
|
|
71
|
+
## Multi-harness
|
|
72
|
+
|
|
73
|
+
Skills use the open Agent Skills (SKILL.md) format — **not just DSH**. Copy the directories under `skills/` into another agent's skills directory:
|
|
74
|
+
|
|
75
|
+
| Agent | Skills directory |
|
|
76
|
+
| :-- | :-- |
|
|
77
|
+
| Claude Code | `~/.claude/skills/` |
|
|
78
|
+
| Cursor | `.cursor/skills/` (or project-local `skills/`) |
|
|
79
|
+
| Gemini CLI | `~/.gemini/skills/` |
|
|
80
|
+
| OpenAI Codex | `~/.codex/skills/` |
|
|
81
|
+
|
|
82
|
+
Port once, use everywhere.
|
|
83
|
+
|
|
84
|
+
## Health checks and reloads
|
|
85
|
+
|
|
86
|
+
`hyperframes_health` rereads every `SKILL.md`, verifies readable files, valid YAML frontmatter, names matching their directories, and nonempty descriptions/bodies, then queries the host's `skills.get`. The effective name, description, body and resource directory must match this plugin instance's loaded snapshot. Existing files alone do not prove successful or still-active registration.
|
|
87
|
+
|
|
88
|
+
Health checks do not mutate files or registrations. After changing a file or repairing one that failed initial loading, reload the plugin (or restart DSH). The result reports `changed`, `not_registered` or `registration_failed` until then. A previously loaded file that was temporarily missing becomes healthy again if its exact original content is restored and its registration remains active.
|
|
89
|
+
|
|
90
|
+
Each item retains `name / ok / detail` and adds `code / fileOk / registered / registryChecked / reloadRequired`. `registered` means the registry still matches the loaded version, so a changed file can have `registered: true` and `ok: false`. Missing or failed registry lookup produces `registry_unavailable`; a disposed plugin produces `disposed`. The public `checkBundledSkills()` is disk-only, while the original non-throwing `parseSkillFile()` helper remains available.
|
|
91
|
+
|
|
92
|
+
## Development and shared implementation
|
|
93
|
+
|
|
94
|
+
`src/index.ts` declares only package identity, skill names and the resource directory. Parsing, validation, registration and health logic live in `src/skill-bundle.ts`. The canonical source is in `dsh-hyperframes`; Remotion carries an identical version-controlled copy. Each package builds and ships its own `lib/skill-bundle.js`, with no cross-package runtime dependency and no sibling checkout required for building or installation.
|
|
95
|
+
|
|
96
|
+
With dependencies already installed:
|
|
97
|
+
|
|
98
|
+
```bash
|
|
99
|
+
node node_modules/typescript/bin/tsc -p tsconfig.json
|
|
100
|
+
node --test "test/*.test.mjs"
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
When developing the sibling repositories together, edit the shared module and regression tests in HyperFrames, then synchronize:
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
# Run in dsh-hyperframes; updates only three shared files in sibling dsh-remotion
|
|
107
|
+
node scripts/sync-skill-bundle.mjs
|
|
108
|
+
node scripts/sync-skill-bundle.mjs --check
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Both suites compare shared source and regression tests to prevent drift. A standalone checkout skips only that cross-repository comparison. Tests cover invalid YAML, unreadable files, empty bodies, rejected/inactive registrations, file changes and repairs, disposal races and cleanup failures, without invoking video or speech services.
|
|
112
|
+
|
|
113
|
+
## License
|
|
114
|
+
|
|
115
|
+
MIT for the porting arrangement; skill content copyright remains with HeyGen.
|
package/docs/USAGE.md
ADDED
|
@@ -0,0 +1,119 @@
|
|
|
1
|
+
# dsh-hyperframes 使用说明
|
|
2
|
+
|
|
3
|
+
[返回简介](../README.md) · [更新记录](../CHANGELOG.md) · [验证记录](VALIDATION.md)
|
|
4
|
+
|
|
5
|
+
## 安装
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
dsh plugin --profile web add dsh-hyperframes
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
重启后说「把这个网址做成 HyperFrames 视频」即可触发。
|
|
12
|
+
|
|
13
|
+
## 卸载
|
|
14
|
+
|
|
15
|
+
```bash
|
|
16
|
+
dsh plugin --profile web remove dsh-hyperframes
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
卸载后重启 Web 服务。如需彻底清理，可再手动删除自己 profile `cordis.patch.yml` 中覆盖的插件行。
|
|
20
|
+
|
|
21
|
+
## 视频工作台
|
|
22
|
+
|
|
23
|
+
在桌面或 Web 的「设置 → HyperFrames」中操作：
|
|
24
|
+
|
|
25
|
+
1. 新建视频，选择标题卡、产品介绍或图文轮播，填写标题/正文、画幅和 3–30 秒时长，明确保存。
|
|
26
|
+
2. 上传 PNG/JPEG、一个背景音频（MP3/WAV）、一个静音背景视频（MP4）的副本。每个文件最多 20 MB、总计 40 MB；轮播按上传顺序，每张至少两秒。
|
|
27
|
+
3. 首次点击「准备渲染环境」。此时下载固定版本官方 CLI 0.8.114；Windows 下载官方专用渲染浏览器，其他系统优先复用已安装的 Chrome；可以继续编辑工程。下载失败保留工程，查看运行记录后重试。需先安装 FFmpeg 并加入 PATH，重启 DSH 后生效。
|
|
28
|
+
4. 启动官方 Studio，检查画面。停止本次预览后再编辑或导出；不会自动打开或占用前台窗口。
|
|
29
|
+
5. 导出 MP4、在工作台播放并下载。工程更新后保留旧成品并显示旧修订提醒；再次导出即可生成新成片。
|
|
30
|
+
|
|
31
|
+
「备份可编辑工程」包含源代码、项目数据和素材。解压后按 README 使用 npm install、npm run preview / render；原模板代码 MIT，渲染器保留自己的许可证。
|
|
32
|
+
|
|
33
|
+
工程、素材、运行目录和依赖缓存默认位于 DSH_HOME/data/dsh-hyperframes，两个插件分别保存。使用同一个 DSH_HOME 的 Web 与桌面 profile 共享这些已保存工程。不会改写原始素材或用户已有视频工程。关闭设置后，当前输入和任务状态保留在本次页面；刷新页面会提示未保存输入，已保存工程长期保留。任务可取消，关闭 DSH 会停止本插件任务。备份 ZIP 目前不支持在设置页导回。
|
|
34
|
+
|
|
35
|
+
智能体工具：hyperframes_project（list/create/get/update）；hyperframes_render（prepare/preview/render/job/cancel）。渲染与更新需要工程 id 和当前 revision；查询/取消使用 job id。工具不会默认下载依赖。
|
|
36
|
+
|
|
37
|
+
## 使用限制
|
|
38
|
+
|
|
39
|
+
本轮为轻量模板编辑，尚不提供时间轴编辑、字幕转写、TTS 或云端渲染。外部链接不能作为素材路径；请先保存到本地再上传。默认 24 FPS，成品上限 200 MB。预览仅监听 127.0.0.1，属于本机服务；多用户机器仍需考虑同机访问。
|
|
40
|
+
|
|
41
|
+
## 技能清单
|
|
42
|
+
|
|
43
|
+
| 技能 | 用途 |
|
|
44
|
+
| :-- | :-- |
|
|
45
|
+
| `hyperframes` | 总纲：HTML 视频合成（视觉风格/调色板/字幕/音频响应/转场）|
|
|
46
|
+
| `hyperframes-core` | 核心概念与组件模型 |
|
|
47
|
+
| `hyperframes-animation` | 动画：GSAP/Anime.js/Lottie/Three.js/WAAPI 适配 |
|
|
48
|
+
| `hyperframes-audio` | 音频：配音、音频响应视觉 |
|
|
49
|
+
| `hyperframes-keyframes` | 关键帧动画 |
|
|
50
|
+
| `hyperframes-creative` | 创意模板与风格 |
|
|
51
|
+
| `hyperframes-cli` | `npx hyperframes` 命令行（init/check/preview/render/timeline/publish/cloud/transcribe/tts/doctor…）|
|
|
52
|
+
| `hyperframes-registry` | `hyperframes add` 注册表组件安装与接线 |
|
|
53
|
+
| `hyperframes-studio` | Studio 时间轴规范：轨道分层、字幕轨、安全区 |
|
|
54
|
+
| `embedded-captions` | 内嵌字幕 |
|
|
55
|
+
| `faceless-explainer` | 无脸讲解视频 |
|
|
56
|
+
| `figma` | Figma 素材接入 |
|
|
57
|
+
| `general-video` | 通用视频制作 |
|
|
58
|
+
| `media-use` | 媒体素材使用规范 |
|
|
59
|
+
| `motion-graphics` | 动态图形 |
|
|
60
|
+
| `music-to-video` | 音乐驱动视频 |
|
|
61
|
+
| `pr-to-video` | PR 转视频 |
|
|
62
|
+
| `product-launch-video` | 产品发布视频 |
|
|
63
|
+
| `remotion-to-hyperframes` | Remotion 项目迁移 |
|
|
64
|
+
| `slideshow` | 幻灯片视频 |
|
|
65
|
+
| `talking-head-recut` | 口播重剪 |
|
|
66
|
+
|
|
67
|
+
## 依赖
|
|
68
|
+
|
|
69
|
+
Node.js 22.19+ (22.x) / 24+ + FFmpeg（`npx hyperframes`）。
|
|
70
|
+
|
|
71
|
+
## 移植说明
|
|
72
|
+
|
|
73
|
+
技能同步自官方仓库 `heygen-com/hyperframes` v0.8.82（2026-09-28）：官方打包的完整 `skills/` 目录，共 21 个技能。相较 v0.8.20，新增 `hyperframes-studio`（Studio 时间轴规范），`hyperframes-core` 的 brief/storyboard/script 等文档改由 `hyperframes` 技能承载，`media-use` 与 `music-to-video` 大幅重构（新增内置动态原语），`embedded-captions` 等脚本随官方升级。旧版五件套中的 `gsap`、`website-to-hyperframes` 已被上游合并进新技能体系。
|
|
74
|
+
|
|
75
|
+
## 跨平台使用
|
|
76
|
+
|
|
77
|
+
技能采用开放的 Agent Skills（SKILL.md）格式，**不止 DSH 能用**——把 `skills/` 下的目录复制到其他 agent 的技能目录即可：
|
|
78
|
+
|
|
79
|
+
| Agent | 技能目录 |
|
|
80
|
+
| :-- | :-- |
|
|
81
|
+
| Claude Code | `~/.claude/skills/` |
|
|
82
|
+
| Cursor | `.cursor/skills/`（或项目内 `skills/`）|
|
|
83
|
+
| Gemini CLI | `~/.gemini/skills/` |
|
|
84
|
+
| OpenAI Codex | `~/.codex/skills/` |
|
|
85
|
+
|
|
86
|
+
一次移植，处处可用。
|
|
87
|
+
|
|
88
|
+
## 技能自检与重载
|
|
89
|
+
|
|
90
|
+
运行 `hyperframes_health` 会重新读取每个 `SKILL.md`，验证文件可读、YAML frontmatter 合法、名称与目录一致、描述与正文非空，再通过宿主 `skills.get` 确认实际生效的名称、描述、正文和资源目录与本次加载内容相符。文件存在但未注册、注册失败或后来被移除时，自检都会失败。
|
|
91
|
+
|
|
92
|
+
自检不修改文件或注册表。修改技能文件，或修复加载时损坏的技能后，应重载插件（也可重启 DSH）。它会报告 `changed`、`not_registered` 或 `registration_failed`，不会把磁盘修复直接当成运行时修复。若原先已成功加载，只是文件暂时丢失，恢复与加载时完全相同的内容即可重新通过检查。
|
|
93
|
+
|
|
94
|
+
每项结果保留 `name / ok / detail`，并增加 `code / fileOk / registered / registryChecked / reloadRequired`：`registered` 表示注册表仍匹配加载时的版本，因此文件变更时它可以为 true 而 `ok` 为 false。缺少或无法查询宿主注册表时返回 `registry_unavailable`；插件卸载后返回 `disposed`。`checkBundledSkills()` 仅检查磁盘文件，不推断运行时状态；原有不抛错的 `parseSkillFile()` 解析入口保持可用。
|
|
95
|
+
|
|
96
|
+
## 开发与共享实现
|
|
97
|
+
|
|
98
|
+
`src/index.ts` 只声明包名、技能清单和目录，解析、校验、注册与自检集中在包内 `src/skill-bundle.ts`。规范源位于 `dsh-hyperframes/src/skill-bundle.ts`，Remotion 保存相同的受版本控制副本；两包都编译并分发自己的 `lib/skill-bundle.js`，没有跨包运行时依赖，也不需要另一个仓库即可构建或安装。
|
|
99
|
+
|
|
100
|
+
依赖预先安装后，可直接离线构建和测试：
|
|
101
|
+
|
|
102
|
+
```bash
|
|
103
|
+
node node_modules/typescript/bin/tsc -p tsconfig.json
|
|
104
|
+
node --test "test/*.test.mjs"
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
两个仓库并列开发时，在 HyperFrames 修改公共模块与公共回归测试，再同步：
|
|
108
|
+
|
|
109
|
+
```bash
|
|
110
|
+
# 在 dsh-hyperframes 中执行；只更新相邻 dsh-remotion 的三个公共文件
|
|
111
|
+
node scripts/sync-skill-bundle.mjs
|
|
112
|
+
node scripts/sync-skill-bundle.mjs --check
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
两包测试都会检查公共源码与回归测试是否一致，防止副本漂移；单独检出时只跳过跨仓库比对，其余测试正常运行。测试覆盖损坏 YAML、不可读文件、空正文、注册异常/失效、内容变更与修复、卸载及清理异常，全程不调用视频或语音服务。
|
|
116
|
+
|
|
117
|
+
## License
|
|
118
|
+
|
|
119
|
+
MIT（移植编排）；技能内容版权归 HeyGen。
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
# dsh-hyperframes 验证记录
|
|
2
|
+
|
|
3
|
+
[0.5.1 中英文界面验收](validation-language-2026-10-03.md)。
|
|
4
|
+
|
|
5
|
+
本页整理原 README 的历史验证说明，保留当时的版本、日期与范围。自动测试、启动检查、浏览器操作和真实服务验收分别记录，不能相互替代。更详细的版本验收文件仍保留在仓库中。
|
|
6
|
+
|
|
7
|
+
## 0.5.0 视频工作台（2026-10-03）
|
|
8
|
+
|
|
9
|
+
- Windows、Node 24.16.0：39 项测试全部通过，无跳过。覆盖工程修订冲突、素材限制、快照、路径与请求校验、渲染失败、取消及退出清理。
|
|
10
|
+
- 官方 Harness 0.2.0-rc.2（639ed01）Web：实际完成新建、保存、上传图片/音频/背景视频、准备环境、启动/停止官方 Studio、导出、播放及下载源工程和 MP4。中文/英文和 390px 窄窗口均检查。
|
|
11
|
+
- 官方 HyperFrames 0.8.114：严格渲染实际生成 6 秒、720×1280、24 FPS、144 帧的 H.264/AAC MP4。检查了两页中文和不同图片，浏览器播放到结尾。Studio 显示背景视频、两个场景及音频轨；停止后本次监听端口关闭。
|
|
12
|
+
- 完成时成品自动出现在工作台；渲染失败不产生成功收据。曾在真实渲染中发现嵌套场景覆盖动画时间轴，修复后重新通过严格导出。
|
|
13
|
+
- 生产依赖审计使用官方 npm registry，结果为 0 项漏洞；不把自动测试或网页验收当作原生桌面窗口操作验收。
|
|
14
|
+
- 官方公开 npm 安装的 Harness 0.2.1-alpha.1：18 个独立插件同载的注册与输出检查通过（109 个工具、35 个技能、TypeScript/Python PTC 声明）；本工作台再次实际导出同一 6 秒 MP4，保存的工程和环境正常恢复。
|
|
15
|
+
|
|
16
|
+
边界：这一版本的新工作台尚未在原生桌面窗口中逐项操作；Linux/macOS 的真实浏览器渲染、任意长文本与用户自有素材的最终成片不属于本次验收。
|
|
17
|
+
|
|
18
|
+
## 原中文记录
|
|
19
|
+
|
|
20
|
+
验证宿主：官方源码构建的 Harness `0.2.0-rc.1`（commit `407e65c8`）+ Node `24.16.0`（2026-09-28）。23 项插件测试在隔离环境全部通过；同一个宿主里 18 个插件共同加载，注册 21 个技能、1 个工具，工具 schema 与健康检查契约通过。本轮未启用真实端口与外部服务。
|
|
21
|
+
|
|
22
|
+
## Original English record
|
|
23
|
+
|
|
24
|
+
Validation host: Harness `0.2.0-rc.1` built from official sources (commit `407e65c8`) with Node `24.16.0` on 2026-09-28. All 23 plugin tests pass in an isolated environment; all 18 plugins mount together in one host registering 21 skills and 1 tools, with tool schemas and health-check contracts passing. No live ports or external services were exercised in this round.
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# 0.5.1：中英文界面验收
|
|
2
|
+
|
|
3
|
+
2026-10-03，Windows / Node 24.16.0。采用 E 盘独立 DSH_HOME、合成资料与无密钥 profile；用户资料、账号、密钥、桌面窗口与 VPN 保持原状。
|
|
4
|
+
|
|
5
|
+
- 自动测试：39 项全部通过。
|
|
6
|
+
- 可见 Web 操作：英文界面超长标题保存被拒绝，提示说明 72 字符上限并保留输入；改为合法中文标题后成功保存。中文界面恢复同一修订的项目和正文。
|
|
7
|
+
- 宿主：官方 DSH 0.2.1-alpha.1 Web；官方 RC2 与 alpha SDK 同载 18 组件，110 工具、35 插件技能、19 输出样例注册与 schema 检查通过。无账号的健康结果不代表真实连接。
|
|
8
|
+
- 边界：本轮没有重新渲染 MP4，渲染和 Studio 的实际验收见 0.5.0 记录。原始引擎日志保持原文。
|
|
9
|
+
|
|
10
|
+
中英文共用同一份资料；界面翻译不会改写标题、正文、路径、引用或项目文件。系统文件选择控件和文件对话框跟随 Windows / 浏览器语言。未知技术诊断与原始引擎日志保留原文；英文界面提供操作恢复引导。
|
|
11
|
+
|
|
12
|
+
此记录不代表原生桌面窗口内的新功能已逐项操作通过。发布包完整性、GitHub CI 与公开 npm 全新安装在发布时另行核对。
|
|
13
|
+
|
|
14
|
+
## English scope
|
|
15
|
+
|
|
16
|
+
The Chinese and English UI share the same data. UI translation preserves original content, paths and project files. Visible interactions were performed in an isolated official alpha Web profile; both RC2 and alpha SDK registration/schema checks passed. Native file controls use the OS/browser language, and original diagnostic logs are retained. Browser results do not certify native desktop interaction or real-service delivery.
|