Synesthesia AI Video Director：用本地 AI 将音乐变为电影级视觉叙事

痛点故事

深夜，音乐人 Jordan 终于录完了新单曲的 stems 和 lyrics。脑海里有了画面——副歌时应该是逆光剪影，过渡段切到潮湿的城市场景。但一想到要逐帧构思视频提示词、手动生成上百个片段、再用剪辑软件拼合成片，这位独立创作者沉默了。商单排到三周后，AI 视频工具要么贵、要么在云端跑还要审核内容。

直到他发现了 Synesthesia AI Video Director——一个 100% 本地运行、 Gradio 驱动的 AI 音乐视频创作工具。他只需要上传三个文件：人声干轨、完整乐队伴奏、歌词文本，填入一个粗略概念，剩下的全交给 AI。

背景：为什么做这个

AI 视频生成工具在 2024-2025 年迎来了爆发，但大多数面向图文生成，视频生成要么依赖云端 API（贵、有审查），要么需要复杂的 ComfyUI 工作流配置。音乐视频（Music Video）尤其特殊：镜头切换需要与人声节奏精确对齐，镜头内容需要与歌词意境保持叙事一致性——这两个需求在现有的 T2V 工具里都需要大量人工干预。

RowanUnderwood 在 Reddit 上分享了创作动机：他厌倦了为每个镜头手动写提示词，于是决定把所有环节自动化。这个项目把三个独立工具串联起来：本地 LLM（写提示词）→ AI 视频引擎（生成画面）→ 视频编辑器（最终合成），而用户只需要关心创作本身。

核心功能：从音频到成片的全链路自动化

Synesthesia 的工作流分为六个阶段，全部在 Gradio Web UI 中完成：

1. 项目创建（Tab 1: Project）

上传人声干轨（vocals.wav）、乐队伴奏（band.wav）、歌词文件（.txt），系统自动检测静音区间，生成初步时间轴。

2. 故事板生成（Tab 2: Storyboard）

输入一个粗略概念（如 "cyberpunk love story in a neon rain"), 系统调用本地 LLM（支持 LM Studio 或 llama.cpp），根据歌词和时间轴生成分镜剧本（Storyboard），包含每个镜头的画面描述和相机运动指令。可手动微调到帧级别，也可全权交给 AI。

3. 视频生成（Tab 3: Video）

每个镜头可设置生成"次数"（takes），点击 Generate 后，LLM 生成视频提示词，通过 LTX Desktop API 批量渲染。支持分辨率选择（540p/720p/1080p）和风格预设（Character Bible、Style Presets）。

4. 最终合成（Tab 4: Assembly）

将生成的镜头和伴奏音频自动拼接，丢弃不满意的 takes 到"Cuttin Room Floor"，最终导出完整 MV。

5. GPU 监控

内置 pynvml 监控显存使用率，渲染时间超出预期时发出警告。

6. 设置与帮助（Tab 5-6）

配置 LLM 地址、视频后端、渲染参数、电费成本等。

技术架构拆解

整体架构：分层模块化

ui/ (6 tabs)
├── app.py — Gradio 构建入口
├── tab1_project.py — 项目上传 & 音频分析
├── tab2_storyboard.py — LLM 驱动分镜生成
├── tab3_video.py — 视频渲染调度
├── tab4_assembly.py — 最终合成
├── tab5_settings.py — 全局配置
└── tab6_help.py — 帮助文档

核心逻辑层
├── llm_logic.py — LLM 提示工程、剧本/分镜生成逻辑
├── models.py — LLMBridge（连接 LM Studio API）、视频后端调度
├── video.py — LTX Desktop API 封装、视频提示词转换（→Zimage）
├── timeline.py — 音频分段时间轴构建（pydub）
├── assembly.py — 视频合成（moviepy）
└── utils.py — 工具函数、Logo Base64、HTML header

配置层
└── config.py — 全局常量（API 地址、VRAM 阈值、电费参数）

关键技术栈

组件	技术选型	说明
Web UI	Gradio 4.x	快速构建，跨平台
本地 LLM	LM Studio / llama.cpp	支持任意 GGUF 模型，qwen3-8b 推荐
音频处理	pydub	人声检测、静音区间识别
视频合成	moviepy	镜头拼接、音频混合
GPU 监控	pynvml	显存实时监控
视频生成	LTX Desktop（推荐）/ Wan2GP	底层均为 HTTP API 调用

AI/ML 组件分析

LLM Bridge：models.py 中的 LLMBridge 类，通过 OpenAI-compatible API (/v1/chat/completions) 与本地 LLM 通信，支持模型列表查询和流式响应。系统提示词工程极为关键：视频提示词需要遵循特定格式（包含主体、光照、构图、风格），剧本生成则需要将歌词情感与镜头类型（vocals/action/intercut）对应。

音频分析：timeline.py 使用 pydub 对人声轨道做静音检测，结合 ffprobe 获取帧率信息，构建 Shot_ID → Start_Time → End_Time 映射表。分镜逻辑根据歌词情感标签（happy/sad/dramatic）分配镜头类型。

视频生成接口：video.py 直接调用 LTX Desktop 的 REST API，构建多线程批量调度。代码中包含了向 Zimage（图片首帧）格式转换的提示词逻辑，用于生成更可控的首帧画面。

代码质量评估

架构设计：模块边界清晰，UI 与逻辑分离，每个 Tab 对应独立文件
错误处理：多处 try-except，但部分 API 超时设置较长（LLM 调用 600s）
Windows 兼容性：包含 sys.platform 判断和 asyncio Proactor 补丁，针对 WinError 10054 有专门处理
扩展性：支持切换视频后端（Wan2GP）、LLM 模型，提供全局配置注入
测试覆盖：无测试文件
文档质量：README 详细，但代码内注释较少

上手门槛：从零到第一支 MV

门槛一：硬件要求

LTX Desktop（推荐方案）：需要 RTX 4090/5090 等高端显卡，显存 20GB+。低于 22GB 显存需修改 runtime_policy.py 绕过检测。磁盘占用 160GB+。

Wan2GP（低显存备选）：6GB+ VRAM 即可运行 Wan2.1 1.3B 模型，但需额外配置 HTTP 桥接服务。

门槛二：依赖安装

安装 Python 3.8+，FFmpeg 加入 PATH
安装 LM Studio，加载 qwen3-8b 模型，启动服务（http://127.0.0.1:1234）
启动 LTX Desktop（http://127.0.0.1:8000）
pip install -r requirements.txt
Windows 双击 run.bat，Linux/macOS 执行 python app.py
浏览器打开 http://localhost:7860

门槛三：提示词工程

生成质量高度依赖 LLM 模型选择和系统提示词设计。README 建议 qwen3-8b，这是经过测试的中等规模模型，兼顾速度和生成质量。

争议与局限

1. 平台锁定问题

项目深度依赖 LTX Desktop（Windows 专用），Linux/macOS 用户需要额外折腾。文档未覆盖 API 模式跨平台使用说明。

2. 显存瓶颈

20GB+ VRAM 的要求意味着大多数消费者级 GPU（RTX 3060 12GB、RTX 4070 12GB）无法本地运行。Wan2GP 提供了 6GB 低显存方案，但生成质量可能下降。

3. 视频生成速度

在 RTX 5090 上，3 分钟 540p 视频第一遍渲染需要约 1 小时。768p/1080p 的时间成本会成倍增加。

4. 无容器化支持

项目没有 Dockerfile 或 docker-compose，所有依赖都需要手动安装，环境复现困难。

5. 视频提示词的 LLM 依赖

提示词生成质量完全取决于本地 LLM。如果模型选择不当或上下文窗口不足（<32K），生成的视频提示词可能缺乏细节。

行业意义

Synesthesia 代表了 AI 内容创作工具的一个新兴方向：端到端自动化 + 本地化。在此之前，大多数 AI 音乐视频工具要么是云端商业服务，要么是需要在 ComfyUI 中手动配置的工作流。

对独立音乐人：极大降低 MV 制作门槛，一个人可以在几小时内完成一支有叙事逻辑的 MV
对 AI 视频领域：探索了音频-视频-叙事三模态联合生成的可行性
对开发者：展示了如何用 Gradio + 本地 LLM 构建复杂的多步骤 AI 应用

从增长趋势看，2024-2025 年 AI 视频生成赛道竞争激烈（Runway → Pika → Sora → Kling → Veo2），但专注于音乐视频自动化的本地工具仍然稀缺，给 Synesthesia 留下了细分市场的机会窗口。

快速体验指南

步骤	操作	预计时间
1	安装 LM Studio，加载 qwen3-8b	15 分钟
2	安装 LTX Desktop，启动服务	10 分钟
3	`git clone` + `pip install -r requirements.txt`	5 分钟
4	运行 `run.bat`，浏览器打开 Gradio UI	1 分钟
5	上传人声/伴奏/歌词，输入概念，点击 Generate	30-60 分钟

Synesthesia AI Video Director：用本地 AI 将音乐变为电影级视觉叙事

痛点故事

背景：为什么做这个

核心功能：从音频到成片的全链路自动化

Synesthesia 的工作流分为六个阶段，全部在 Gradio Web UI 中完成：

1. 项目创建（Tab 1: Project）

上传人声干轨（vocals.wav）、乐队伴奏（band.wav）、歌词文件（.txt），系统自动检测静音区间，生成初步时间轴。

2. 故事板生成（Tab 2: Storyboard）

3. 视频生成（Tab 3: Video）

4. 最终合成（Tab 4: Assembly）

将生成的镜头和伴奏音频自动拼接，丢弃不满意的 takes 到"Cuttin Room Floor"，最终导出完整 MV。

5. GPU 监控

内置 pynvml 监控显存使用率，渲染时间超出预期时发出警告。

6. 设置与帮助（Tab 5-6）

配置 LLM 地址、视频后端、渲染参数、电费成本等。

技术架构拆解

整体架构：分层模块化

ui/ (6 tabs)
├── app.py — Gradio 构建入口
├── tab1_project.py — 项目上传 & 音频分析
├── tab2_storyboard.py — LLM 驱动分镜生成
├── tab3_video.py — 视频渲染调度
├── tab4_assembly.py — 最终合成
├── tab5_settings.py — 全局配置
└── tab6_help.py — 帮助文档

核心逻辑层
├── llm_logic.py — LLM 提示工程、剧本/分镜生成逻辑
├── models.py — LLMBridge（连接 LM Studio API）、视频后端调度
├── video.py — LTX Desktop API 封装、视频提示词转换（→Zimage）
├── timeline.py — 音频分段时间轴构建（pydub）
├── assembly.py — 视频合成（moviepy）
└── utils.py — 工具函数、Logo Base64、HTML header

配置层
└── config.py — 全局常量（API 地址、VRAM 阈值、电费参数）

关键技术栈

组件	技术选型	说明
Web UI	Gradio 4.x	快速构建，跨平台
本地 LLM	LM Studio / llama.cpp	支持任意 GGUF 模型，qwen3-8b 推荐
音频处理	pydub	人声检测、静音区间识别
视频合成	moviepy	镜头拼接、音频混合
GPU 监控	pynvml	显存实时监控
视频生成	LTX Desktop（推荐）/ Wan2GP	底层均为 HTTP API 调用

AI/ML 组件分析

代码质量评估

架构设计：模块边界清晰，UI 与逻辑分离，每个 Tab 对应独立文件
错误处理：多处 try-except，但部分 API 超时设置较长（LLM 调用 600s）
Windows 兼容性：包含 sys.platform 判断和 asyncio Proactor 补丁，针对 WinError 10054 有专门处理
扩展性：支持切换视频后端（Wan2GP）、LLM 模型，提供全局配置注入
测试覆盖：无测试文件
文档质量：README 详细，但代码内注释较少

上手门槛：从零到第一支 MV

门槛一：硬件要求

LTX Desktop（推荐方案）：需要 RTX 4090/5090 等高端显卡，显存 20GB+。低于 22GB 显存需修改 runtime_policy.py 绕过检测。磁盘占用 160GB+。

Wan2GP（低显存备选）：6GB+ VRAM 即可运行 Wan2.1 1.3B 模型，但需额外配置 HTTP 桥接服务。

门槛二：依赖安装

安装 Python 3.8+，FFmpeg 加入 PATH
安装 LM Studio，加载 qwen3-8b 模型，启动服务（http://127.0.0.1:1234）
启动 LTX Desktop（http://127.0.0.1:8000）
pip install -r requirements.txt
Windows 双击 run.bat，Linux/macOS 执行 python app.py
浏览器打开 http://localhost:7860

门槛三：提示词工程

生成质量高度依赖 LLM 模型选择和系统提示词设计。README 建议 qwen3-8b，这是经过测试的中等规模模型，兼顾速度和生成质量。

争议与局限

1. 平台锁定问题

项目深度依赖 LTX Desktop（Windows 专用），Linux/macOS 用户需要额外折腾。文档未覆盖 API 模式跨平台使用说明。

2. 显存瓶颈

20GB+ VRAM 的要求意味着大多数消费者级 GPU（RTX 3060 12GB、RTX 4070 12GB）无法本地运行。Wan2GP 提供了 6GB 低显存方案，但生成质量可能下降。

3. 视频生成速度

在 RTX 5090 上，3 分钟 540p 视频第一遍渲染需要约 1 小时。768p/1080p 的时间成本会成倍增加。

4. 无容器化支持

项目没有 Dockerfile 或 docker-compose，所有依赖都需要手动安装，环境复现困难。

5. 视频提示词的 LLM 依赖

提示词生成质量完全取决于本地 LLM。如果模型选择不当或上下文窗口不足（<32K），生成的视频提示词可能缺乏细节。

行业意义

对独立音乐人：极大降低 MV 制作门槛，一个人可以在几小时内完成一支有叙事逻辑的 MV
对 AI 视频领域：探索了音频-视频-叙事三模态联合生成的可行性
对开发者：展示了如何用 Gradio + 本地 LLM 构建复杂的多步骤 AI 应用

快速体验指南

步骤	操作	预计时间
1	安装 LM Studio，加载 qwen3-8b	15 分钟
2	安装 LTX Desktop，启动服务	10 分钟
3	`git clone` + `pip install -r requirements.txt`	5 分钟
4	运行 `run.bat`，浏览器打开 Gradio UI	1 分钟
5	上传人声/伴奏/歌词，输入概念，点击 Generate	30-60 分钟