本仓库收录数据可视化、榜单与科普类视频项目。每个项目自由选择 Remotion 或 HyperFrames（见 ADR 0002），在 projects.json 的 framework 字段中登记。
项目按主题分类、项目名称与根目录路径见 视频项目索引；projects.json 是项目路径、名称、语言和发布 variant 的唯一机器可读清单。
| 项目 | 内容 | 语言 | 时长 | 框架 | 默认输出 |
|---|---|---|---|---|---|
| Metro de Lima | 秘鲁利马地铁系统介绍 | 西 | 随旁白生成 | Remotion | out/video.mp4 |
| Saint Petersburg Metro | 俄罗斯圣彼得堡地铁系统介绍（俄英双语字幕） | 俄 + 英字幕 | 随旁白生成 | Remotion | out/video.mp4 |
| Sapporo Subway | 日本札幌市营地铁介绍 | 日 | 随旁白生成 | Remotion | out/video.mp4 |
| Cloudflare History | Cloudflare 发展历程 | 中 | 随旁白生成 | HyperFrames | out/video.mp4 |
| Japan Economy | 日本 1985—2026 经济指标与日经指数 | 日 | 随旁白生成 | Remotion | out/video.mp4 |
| AI Model Rankings | AI 模型能力、速度与厂商分布 | 英、中、日 | 60 秒 | Remotion | out/video.mp4 |
| Apple | 水果苹果创意介绍 | 中 | 随旁白生成 | HyperFrames | out/video.mp4 |
| OpenRouter Rankings | OpenRouter 每周模型使用排名 | 英、中 | 45 秒 | Remotion | out/video.mp4 |
| Population CN | 中国各省出生人口变化 | 中 | 40 秒 | Remotion | out/video.mp4 |
| Births JP | 日本各都道府县出生人数（2000–2025） | 中、日 | 随旁白生成 | Remotion | out/births-jp-zh.mp4 |
| QS Universities | QS 世界大学排名 | 中 | 52 秒 | Remotion | out/video.mp4 |
| Solar System | 太阳系科普动画 | 英、中、日、韩 | 随旁白生成 | Remotion | out/video.mp4 |
| Top 500 | 2025 年《财富》世界 500 强 | 中 | 29 秒 | Remotion | out/video.mp4 |
| Kakeya Conjecture | 挂谷猜想科普动画 | 中 | 42 秒 | Remotion | out/video.mp4 |
| Brexit Referendum | 英国脱欧公投回顾 | 英 | 随旁白生成 | Remotion | out/video.mp4 |
| Red Army JP | 日本赤军历史 | 日 | 随旁白生成 | Remotion | out/red-army-ja.mp4 |
| Southern Kurils JP | 南千岛群岛介绍 | 日 | 随旁白生成 | Remotion | out/southern-kurils-ja.mp4 |
| Imperial House Law JP | 皇室典范改正议题 | 日 | 随旁白生成 | Remotion | out/imperial-house-law-ja.mp4 |
| Shandong Universities | 山东本科院校地图速览 | 中 | 随旁白生成 | Remotion | out/shandong-atlas.mp4 |
| Claude MHS | Anthropic Model Hardware Standard 介绍 | 中 | 随旁白生成 | HyperFrames | out/claude-mhs-zh.mp4 |
| Kimi K3.1 Pro | 月之暗面 Kimi K3.1 Pro 模型发布介绍 | 中 | 随旁白生成 | HyperFrames | out/kimi-k3-1-pro-zh.mp4 |
| GPT-6.1 Terra | OpenAI GPT-6.1 Terra 模型发布介绍 | 中 | 随旁白生成 | HyperFrames | out/gpt-6-1-terra-zh.mp4 |
| SZU History | 深圳大学发展史（1983—2026） | 中 | 约 62 秒 | HyperFrames | out/szu-history-zh.mp4 |
| Shenzhen Reclamation | 深圳填海造陆发展史卫星地图解说 | 中 | 约 64 秒 | HyperFrames | out/shenzhen-reclamation-zh.mp4 |
| Shenzhen Metro | 深圳地铁介绍（2004—2026） | 中 | 约 68 秒 | HyperFrames | out/shenzhen-metro-zh.mp4 |
| LA28 Olympics | 洛杉矶 2028 奥运会宣传片（配乐，无旁白） | 中 | 约 32 秒 | HyperFrames | out/la28-olympics-zh.mp4 |
| Shenzhen APEC | 深圳 APEC 2026 宣传片 | 英 + 中英字幕 | 随旁白生成 | HyperFrames | out/shenzhen-apec-en.mp4 |
榜单和数据项目采用 1080 × 1920 竖屏画布；Kakeya Conjecture 使用 1920 × 1080 横屏画布。具体数据来源、内容结构和资源要求见各项目目录内的 README。
- Node.js 22 或更高版本
- FFmpeg
- Chrome 或 Chromium
- npm
所有项目必须使用与内容语言对应的 Google Fonts Noto 网络字体，不能默认依赖渲染机器上的本地字体。默认字体映射如下：
| 内容语言 | Google Noto 字体 | CSS font-family |
|---|---|---|
| 英语、西班牙语及其他拉丁文字 | Noto Sans | "Noto Sans", sans-serif |
| 简体中文 | Noto Sans SC | "Noto Sans SC", sans-serif |
| 繁体中文 | Noto Sans TC | "Noto Sans TC", sans-serif |
| 日语 | Noto Sans JP | "Noto Sans JP", sans-serif |
| 韩语 | Noto Sans KR | "Noto Sans KR", sans-serif |
Remotion 项目应使用 @remotion/google-fonts 加载对应字体，并在开始渲染前等待字体完成加载。示例：
import {loadFont} from '@remotion/google-fonts/NotoSansJP';
export const notoSansJP = loadFont('normal', {
weights: ['400', '500', '600', '700', '800', '900'],
subsets: ['japanese', 'latin'],
});开发预览、Remotion 渲染和 CI 都需要能够访问 fonts.googleapis.com 与 fonts.gstatic.com。应在截图或渲染前确认 document.fonts.ready；字体加载失败时才允许回退到 sans-serif。若要求完全离线或严格可复现的字形，应使用许可允许的字体文件和本地 @font-face，但仍保持对应语言的 Noto 字体族。
依赖由根目录 npm workspace 统一管理。首次使用先在仓库根目录执行：
npm ci
cd data_visualization/ai_model_rankings
# TypeScript 类型检查
npm run check
# 启动本地预览
npm run dev
# 渲染默认英语版本到 out/video.mp4
npm run render预览服务启动后，终端会输出 Remotion Studio 地址。修改 src/ 中的组件、样式或数据后，预览会自动刷新。
各项目的 npm run check 当前均为 tsc --noEmit，不包含布局、内容或音画同步检查。多语言项目使用 npm run render:<语言代码> 单独渲染；npm run render 只生成默认版本。具体输出以 package.json 为准。
仓库根目录的 npm run check 会校验项目清单、共享包，并以最多三个并发任务检查全部 18 个项目。对于尚未生成旁白时长 JSON 的项目，检查器只在类型检查期间创建最小 JSON fixture，并在检查后立即删除；正式渲染仍必须先运行该项目的 voiceover。
跨项目稳定能力放在 packages/ 中。目前 @video/core 提供顺序时间轴、场景进度、淡入淡出和入场动画计算；具体场景布局和视觉组件继续留在各视频项目内。
- 阅读项目 README，确认主题、数据口径、语言和输出文件，并执行
npm ci。 - 项目定义了
voiceover时，先安装 Python 的edge-tts和 FFmpeg，再运行npm run voiceover生成所需音频与时间轴文件。 - 只有需要主动刷新数据时才执行项目的
npm run data:update；发布流程始终使用 Git 中已经审阅并冻结的 snapshot。 - 修改
src/中的组件和数据，运行npm run check。 - 运行
npm run dev，检查关键帧、转场、文字溢出、字幕和音画同步。 - 运行
npm run render:draft试渲染，确认后运行npm run render或对应语言脚本。
render:draft 的参数因项目而异，部分项目仅改变输出文件和日志级别；请查看 package.json，不要默认认为它会降低分辨率或缩短渲染时间。
所有项目统一使用 .github/workflows/render-release.yml 发布。工作流由 <project_key>-<semver> tag 触发，自动解析项目、安装依赖、生成旁白、运行检查、渲染 MP4，并把 MP4 和封面（<project_key>-<version>[-<variant>]-cover.png）上传到 artifact 和 GitHub Release。项目定义 render:still（写出 out/cover.png）时使用专门设计的封面，否则从视频中自动截取一帧，见 发布流程。工作流不会联网刷新业务数据，发布内容来自 tag 中已提交的 snapshot。
| 项目 | Tag 格式 | 工作流 |
|---|---|---|
| 所有项目 | <project_key>-<semver>[-<variant>]，例如 japan_economy-1.0.0、solar-1.0.0-zh |
render-release.yml |
例如发布日本经济和札幌地铁：
git tag japan_economy-1.0.1
git push origin japan_economy-1.0.1
git tag sapporo_subway-1.0.4
git push origin sapporo_subway-1.0.4所有项目都使用通用的 project-version-variant 格式，variant 与项目脚本直接一一对应。Solar 与 Kakeya Conjecture 发布示例：
git tag solar-1.0.0-zh
git push origin solar-1.0.0-zh
git tag kakeya_conjecture-1.0.0
git push origin kakeya_conjecture-1.0.0Solar 的 variant 为 en、zh、ja、ko，可带 variant 单独发版，Action 会直接执行对应的 npm run render:<variant>。Solar 不带 variant 时渲染默认英语版。Kakeya Conjecture 无 variant，直接执行 npm run render。具体声音、复现命令和 CI 限制见 TTS 旁白方案，同步实现见 音画同步方案，发版细节见 发布流程。
- 一个视频项目对应一个顶层目录。
- Remotion 项目入口为
src/index.ts，composition 注册在src/Root.tsx；HyperFrames 项目入口为index.html。 - Remotion 多语言版本通过 composition 和语言参数注册，共享资源放在
public/。 - 跨项目复用的代码放在
packages/：@video/core（时间轴、Remotion 配置）与packages/voiceover（Edge TTS 旁白脚本）。 - 渲染产物统一写入
out/，不要提交临时预览文件。 - 数据、单位、统计年份和来源必须在项目 README 中说明。
- 新增项目时应提供
package.json、README、框架入口和可执行的检查、预览、渲染脚本，并登记到根目录projects.json；依赖锁统一维护在根目录。
先确认已执行 npm ci，所需旁白和时间轴文件已生成，再检查 Node.js、FFmpeg、Chrome 和可用内存。字体加载问题按上方字体规范排查。
在 Remotion Studio 中分别选择各语言的 composition，检查标题换行、字号、行高与场景边界。类型检查不会发现文字溢出，需要在预览和试渲染中确认。
先查看 render:draft 的实际参数，并减少高成本滤镜、模糊和粒子效果。Solar 的 WebGL 配置与渲染要求见其项目 README。
- ADR 0002：按项目自由选择视频框架：Remotion 与 HyperFrames 并存的约定。
- ADR 0001：以 Remotion 作为主力视频框架（部分被 ADR 0002 取代）：框架迁移历史。
- 按内容类型的技术选型：榜单、时序数据、地图、叙事、3D、数学科普、品牌、多语言等类型的画面技术、数据流水线与参考项目。
- TTS 旁白方案：旁白生成、文件约定、Remotion 接入与验证流程。
- 音画同步方案：音频主时钟、时间数据、字幕与场景对齐、同步验证和漂移排查。
- 配乐与音效来源：可用曲库与音效库的许可和署名要求、配乐裁切与拍点表流程。
- 发布流程：tag 格式与 Release 工作流。
- Remotion vs HyperFrames：两种框架的编程模型、渲染部署与选型标准。
- 使用 Blender Python 生成视频：脚本化建模与动画、后台渲染、帧序列与 FFmpeg 编码。
- 改版待办：各项目已知的质量问题与改版、迁移计划。
- HyperFrames 视频制作最佳实践（历史文档）：HyperFrames 时期的制作规范。
新增 Remotion 项目时，提供 src/index.ts、src/Root.tsx、配置文件及检查、预览、渲染脚本；新增 HyperFrames 项目时，提供 index.html、锁定版本的 hyperframes devDependency 及同名脚本，在 projects.json 中写 "framework": "hyperframes"。补充项目 README，并在上方“项目一览”中登记。提交前完成类型检查、人工布局检查和一次完整渲染。
榜单数据更新与人口视频边界的回归检查（先安装 population_cn 依赖）：
node --test tests/review-regressions.test.mjs