本仓库收录数据可视化、榜单与科普类视频项目，当前 18 个项目均基于 Remotion 制作；部分目录保留了早期 HyperFrames 源文件。
项目按主题分类、项目名称与根目录路径见 视频项目索引；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 发展历程 | 中 | 90 秒 | Remotion | out/video.mp4 |
| Japan Economy | 日本 1985—2026 经济指标与日经指数 | 日 | 随旁白生成 | Remotion | out/video.mp4 |
| AI Model Rankings | AI 模型能力、速度与厂商分布 | 英、中、日 | 60 秒 | Remotion | out/video.mp4 |
| Apple | 水果苹果创意介绍 | 中 | 54 秒 | Remotion | out/video.mp4 |
| OpenRouter Rankings | OpenRouter 每周模型使用排名 | 英、中 | 45 秒 | Remotion | out/video.mp4 |
| Population CN | 中国各省出生人口变化 | 中 | 40 秒 | Remotion | out/video.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 |
榜单和数据项目采用 1080 × 1920 竖屏画布；Kakeya Conjecture 使用 1920 × 1080 横屏画布。具体数据来源、内容结构和资源要求见各项目目录内的 README。
- Node.js 22 或更高版本
- FFmpeg
- Chrome 或 Chromium
- npm
所有 Remotion 和 HyperFrames 项目必须使用与内容语言对应的 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'],
});HyperFrames 项目应在 HTML 中通过 Google Fonts 的 <link> 或 @import 引入对应字体，并将其设置为页面和视频元素的全局字体：
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP:wght@400;500;600;700;800;900&display=swap" rel="stylesheet">开发预览、Remotion 渲染和 HyperFrames 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，不要默认认为它会降低分辨率或缩短渲染时间。
普通的 Remotion / HyperFrames 项目统一使用 .github/workflows/render-release.yml 发布。工作流由 <project_key>-<semver> tag 触发，自动解析项目、安装依赖、生成旁白、运行检查、渲染 MP4，并上传 artifact 和 GitHub Release。工作流不会联网刷新业务数据，发布内容来自 tag 中已提交的 snapshot。
| 项目 | Tag 格式 | 工作流 |
|---|---|---|
| 所有 Remotion / HyperFrames 项目 | <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。 - Remotion 多语言版本通过 composition 和语言参数注册，共享资源放在
public/；compositions/中的 HTML 为保留的 HyperFrames 源文件。 - 渲染产物统一写入
out/，不要提交临时预览文件。 - 数据、单位、统计年份和来源必须在项目 README 中说明。
- 新增项目时应提供
package.json、README、Remotion 入口与配置和可执行的检查、预览、渲染脚本，并登记到根目录projects.json；依赖锁统一维护在根目录。
先确认已执行 npm ci，所需旁白和时间轴文件已生成，再检查 Node.js、FFmpeg、Chrome 和可用内存。字体加载问题按上方字体规范排查。
在 Remotion Studio 中分别选择各语言的 composition，检查标题换行、字号、行高与场景边界。类型检查不会发现文字溢出，需要在预览和试渲染中确认。
先查看 render:draft 的实际参数，并减少高成本滤镜、模糊和粒子效果。Solar 的 WebGL 配置与渲染要求见其项目 README。
- HyperFrames 视频制作最佳实践：工程结构、视觉规范、时间轴、数据、音频、多语言与交付检查。
- Remotion vs HyperFrames：编程模型、工作流、渲染部署、选型标准与本仓库建议。
- 使用 Blender Python 生成视频：脚本化建模与动画、后台渲染、帧序列、FFmpeg 编码及 HyperFrames 混合工作流。
- TTS 旁白方案：旁白生成、文件约定、composition 接入、字幕同步、验证流程与 Solar 历史方案。
- 音画同步方案：音频主时钟、cue 数据结构、字幕与场景对齐、同步验证和漂移排查。
新增 Remotion 项目时，提供 src/index.ts、src/Root.tsx、配置文件、依赖锁文件及检查、预览、渲染脚本。补充项目 README，并在上方“项目一览”中登记。提交前完成类型检查、人工布局检查和一次完整渲染。HyperFrames 的历史制作流程见上方专题文档。
榜单数据更新与人口视频边界的回归检查（先安装 population_cn 依赖）：
node --test tests/review-regressions.test.mjs