CLAUDE.md

本文件为 Claude Code (claude.ai/code) 在本仓库中工作时提供指引。

项目概述

文本转视频生成流水线。接收描述视频结构（封面、场景、结束语）的 JSON 输入，输出带 TTS 旁白、字幕和模板视觉样式的 MP4 视频。

常用命令

pnpm build          # 构建所有包 (turbo)
pnpm typecheck      # 类型检查所有包
pnpm lint           # Lint 所有包

# 运行视频渲染
node apps/cli/dist/index.js render test/fixtures/sample-knowledge.json -t knowledge -p bilibili

# Web UI 开发服务器
cd apps/web && pnpm dev

架构

pnpm workspaces + Turborepo 的 monorepo 结构。

apps/cli/          CLI 入口 (Commander)
apps/web/          Next.js 15 WebUI + API 路由
packages/shared/   Zod schema、类型定义、常量、LLM 客户端
packages/core/     流水线编排与 6 个阶段
packages/tts/      TTS provider 注册表 + 4 个 provider
packages/templates/ 4 个模板的 Remotion React 组件

流水线数据流

输入始终是结构化 JSON (VideoInputSchema)。流水线在 packages/core/src/stages/ 中依次执行 6 个阶段：

parse — 通过 VideoInputSchema 验证 JSON，转换为内部 ParsedContent（cover → scene-0，outro → 最后一个 scene）
tts — 按场景调用 TTS provider，生成逐场景音频文件 + word timestamps
assets — 解析图片资源（本地 path > 远程 url > 关键词 query），复制背景图/字体
compose — 转换为带帧时间轴的 ComposedProject，word timestamps 转为场景内相对时间
render — 打包 Remotion bundle，将资源复制到 publicDir，通过 renderMedia 渲染
export — 输出最终 MP4 到指定目录

核心类型链：VideoInput → ParsedContent → ComposedProject → Remotion props。

Remotion 约束

Remotion 通过其 webpack dev server 提供所有静态资源。组件中绝不能使用文件系统绝对路径 — 必须使用 staticFile(filename)。render 阶段会将所有资源（音频、图片、背景图）复制到统一的 publicDir，通过 props 传递文件名。

音频按场景独立播放：每个 <Sequence> 包含自己的 <Audio> 组件，不使用全局音频轨道。

TTS Provider 体系

Provider 通过 registerProvider() 在 packages/tts/src/providers/ 中注册。每个 provider 实现 TTSProvider 接口（synthesize、listVoices、align）。新增 provider 的方式：在 providers/ 下创建文件并在 index.ts 中 import。

模板系统

4 个模板（news、knowledge、opinion、marketing），每个在 packages/templates/src/<name>/index.tsx 中有对应的场景组件。共享基础组件位于 packages/templates/src/base/。Root.tsx 将 sceneType === "cover"|"outro" 路由到内置的 CoverScene/OutroScene；content 类型场景路由到对应模板组件。

配置

.env（monorepo 根目录）— 所有 provider 的 API Key（CLI 启动时加载，Next.js 通过 next.config.ts 加载）
config/default.yaml — TTS provider、模型、模板配色、输出设置
CLI 按以下顺序读取配置：--config 参数 → pipeline.config.yaml → config/default.yaml

核心 Schema

全部在 packages/shared/src/types/ 中用 Zod 定义：

VideoInputSchema — 用户输入格式（title、subtitle、cover、scenes[]、outro、globalStyle）
SceneSchema — 内部场景，含 sceneType: "cover"|"content"|"outro"
ComposedSceneSchema — compose 后的场景，含帧时间轴、audioPath、已解析的图片
PipelineInputSchema — 顶层流水线输入（text、template、platform、ttsProvider）

CLAUDE.md 3.7 KB Vēsture Neapstrādāts