15 KiB

Raw Blame History

B-Roll素材获取

**本文引用的文件** - [backend/media_fetcher.py](file://backend/media_fetcher.py) - [assets/1_processed/broll_fetch_results.json](file://assets/1_processed/broll_fetch_results.json) - [main.py](file://main.py) - [PROJECT_README.md](file://PROJECT_README.md) - [frontend/src/render-props-types.ts](file://frontend/src/render-props-types.ts) - [requirements.txt](file://requirements.txt) - [backend/extractor.py](file://backend/extractor.py) - [backend/scripter.py](file://backend/scripter.py) - [.gitignore](file://.gitignore)

简介

本技术文档聚焦于B-Roll素材自动获取功能，围绕 backend/media_fetcher.py 展开，说明其如何通过 Pexels API 根据脚本内容智能检索匹配的背景视频片段。文档涵盖：

关键词提取与翻译：从日语解说脚本中识别关键主题（如“家庭”“退休”“教育”），并映射为英文搜索词。
视频筛选标准：分辨率、时长、版权许可等要求及下载管理机制。
代码示例路径：API请求构造、响应处理与本地缓存策略。
broll_fetch_results.json 结构说明及其在后续渲染阶段的引用方式。
故障排查：API密钥失效、网络超时、素材质量不佳等问题的应对。
扩展方案：替换其他素材源（如Pixabay、Coverr等）的思路。

项目结构

该仓库采用“Python后端 + Node.js/Remotion 前端”的混合架构。与B-Roll素材获取直接相关的目录与文件如下：

backend/media_fetcher.py：B-Roll素材抓取器，负责调用Pexels API、关键词翻译、下载与缓存。
assets/1_processed/broll_fetch_results.json：已抓取素材的结果索引，供渲染阶段引用。
main.py：主流程编排，串联PDF提取、脚本生成、B-Roll抓取、图表数据构建、渲染属性生成与渲染。
frontend/src/render-props-types.ts：渲染属性的数据契约，定义了assets.broll的结构。
requirements.txt：Python依赖清单，包含requests等网络与媒体处理相关库。
backend/extractor.py、backend/scripter.py：分别负责PDF与视频提取、脚本生成（当前为占位实现，未来用于提供关键词）。
.gitignore：忽略输出视频与环境变量文件，保留JSON元数据。

graph TB
A["main.py<br/>主流程编排"] --> B["backend/media_fetcher.py<br/>B-Roll抓取器"]
A --> C["assets/1_processed/broll_fetch_results.json<br/>抓取结果索引"]
A --> D["frontend/src/render-props-types.ts<br/>渲染属性契约"]
B --> E["Pexels API"]
B --> F["本地缓存目录<br/>assets/1_processed/broll/"]

图示来源

章节来源

核心组件

MediaFetcher 类：封装Pexels API交互、关键词翻译、视频下载与缓存逻辑。
fetch_broll 函数：便捷入口，从脚本中抽取关键词并触发抓取。
broll_fetch_results.json：记录每个关键词对应的英文名与本地视频列表，包含时长与摄影师信息。
渲染属性契约：定义 assets.broll 的键值映射，供前端渲染使用。

章节来源

架构总览

下图展示了B-Roll抓取在整体流水线中的位置与数据流。

sequenceDiagram
participant CLI as "命令行入口<br/>main.py"
participant Gen as "脚本生成器<br/>backend/scripter.py"
participant MF as "B-Roll抓取器<br/>backend/media_fetcher.py"
participant PEX as "Pexels API"
participant FS as "本地存储<br/>assets/1_processed/broll/"
participant RP as "渲染属性<br/>render_props.json"
participant FE as "前端渲染<br/>Remotion"
CLI->>Gen : 生成日语脚本
CLI->>MF : 提供脚本并请求B-Roll
MF->>MF : 抽取关键词并翻译为英文
MF->>PEX : 发送搜索请求
PEX-->>MF : 返回视频资源列表
MF->>FS : 下载并保存视频
MF-->>CLI : 返回本地路径映射
CLI->>RP : 写入render_props.json
FE-->>CLI : 使用render_props.json进行渲染

图示来源

详细组件分析

MediaFetcher 类设计与职责

负责初始化与校验PEXELS_API_KEY，设置基础URL。
提供 fetch_broll(keywords, max_per_keyword) 接口，返回关键词到视频URL的映射。
提供 _translate_keyword(japanese_keyword) 占位方法，未来接入Gemini进行日英翻译并缓存。
提供 _download_video(url, output_path) 占位方法，未来实现下载、进度条、格式校验与缓存。

classDiagram
class MediaFetcher {
+api_key : string
+base_url : string
+__init__(api_key)
+fetch_broll(keywords, max_per_keyword) Dict
+_translate_keyword(japanese_keyword) string
+_download_video(url, output_path) string
}

图示来源

backend/media_fetcher.py

章节来源

backend/media_fetcher.py

关键词提取与翻译策略

输入：来自脚本生成器的脚本对象，包含分段文本。
提取：遍历脚本的分段，从每段文本中抽取关键词（占位实现，未来可结合NLP或LLM）。
翻译：将日文关键词翻译为英文（占位实现，建议使用Gemini Pro），并缓存翻译结果以减少重复调用。
映射：将英文关键词作为Pexels搜索词，限制每关键词最多返回若干个视频。

flowchart TD
Start(["开始"]) --> LoadScript["加载脚本对象"]
LoadScript --> Iterate["遍历脚本分段"]
Iterate --> Extract["抽取关键词占位"]
Extract --> Translate["翻译为英文Gemini并缓存"]
Translate --> Search["调用Pexels搜索接口"]
Search --> Filter["按分辨率/时长/许可筛选"]
Filter --> Download["下载到本地缓存目录"]
Download --> Index["写入broll_fetch_results.json"]
Index --> End(["结束"])

图示来源

章节来源

视频筛选标准与下载管理

分辨率与时长：建议在搜索后对返回结果按分辨率与目标时长范围进行过滤，优先选择高分辨率且时长接近目标的素材。
版权许可：Pexels默认许可适合商用，但应确保符合项目用途；必要时可在筛选中排除非CC0或非商业许可的素材。
下载与缓存：
- 将视频下载至 assets/1_processed/broll/ 目录，命名规则建议包含关键词与唯一标识，便于去重与复用。
- 在 broll_fetch_results.json 中记录每个关键词的英文名、本地文件路径、时长与摄影师信息，便于渲染阶段引用。
- 使用缓存避免重复下载同一素材，可基于哈希或URL指纹判断是否已存在。

flowchart TD
A["Pexels搜索结果"] --> B["按分辨率筛选"]
B --> C["按时长范围筛选"]
C --> D["按许可筛选"]
D --> E["下载到本地缓存"]
E --> F["更新broll_fetch_results.json"]
F --> G["返回本地路径映射"]

图示来源

章节来源

API请求构造与响应处理

请求构造：使用 requests 库发送HTTP GET请求到 Pexels 搜索接口，携带认证头与查询参数（关键词、数量上限等）。
响应处理：解析JSON，提取视频URL、时长、分辨率、许可等字段；对不符合条件的条目进行过滤。
错误处理：捕获网络异常、超时、HTTP状态码错误；对空结果或失败重试进行降级处理。

章节来源

broll_fetch_results.json 结构与渲染引用

结构要点：
- 键为日文关键词（如“家族”“老後”“教育”）。
- 字段 english：英文关键词。
- 字段 videos：数组，包含多个视频条目，每项含 filepath、duration、photographer。
渲染引用：
- 渲染属性 assets.broll 期望为“关键词 -> 路径”的映射；当前broll_fetch_results.json以关键词为根节点，渲染阶段需将其转换为 assets.broll 的扁平映射，或将渲染阶段直接读取该JSON并按需转换。
- 前端契约中 assets.broll 为 Record<string, string>，即“关键词 -> 视频路径”。

erDiagram
KEYWORDS {
string 日文关键词 PK
string 英文关键词
}
VIDEOS {
string filepath
number duration
string photographer
}
KEYWORDS ||--o{ VIDEOS : "包含"

图示来源

章节来源

代码示例路径（不展示具体代码）

初始化与校验API密钥与基础URL
- 参考路径：backend/media_fetcher.py
fetch_broll 接口与占位实现
- 参考路径：backend/media_fetcher.py
_translate_keyword 占位方法
- 参考路径：backend/media_fetcher.py
_download_video 占位方法
- 参考路径：backend/media_fetcher.py
主流程中调用 fetch_broll
- 参考路径：main.py
渲染属性契约中 assets.broll 的定义
- 参考路径：frontend/src/render-props-types.ts

依赖关系分析

外部依赖：
- requests：用于HTTP请求与下载。
- ffmpeg-python：用于视频处理（当前媒体抓取模块为占位，未来可能在此集成）。
内部依赖：
- main.py 编排调用 media_fetcher.fetch_broll。
- frontend/src/render-props-types.ts 定义渲染阶段消费的数据结构。
- .gitignore 控制资产目录的版本控制行为，避免大文件入库。

graph LR
REQ["requests"] --> MF["backend/media_fetcher.py"]
FFPY["ffmpeg-python"] --> MF
MF --> MAIN["main.py"]
MF --> TYPES["frontend/src/render-props-types.ts"]
GIT[".gitignore"] --> MF

图示来源

章节来源

性能考量

并发与限速：Pexels搜索接口可能有限额，建议对关键词并发请求进行节流，避免触发速率限制。
缓存策略：对翻译结果与下载的视频建立本地缓存，命中则跳过网络请求，显著降低延迟与成本。
过滤前置：在下载前完成分辨率与时长过滤，减少无效IO。
断点续传：对于大文件下载，可考虑断点续传以提升稳定性。

故障排查指南

API密钥失效
- 现象：初始化时报错或请求返回未授权。
- 处理：检查 .env 文件是否正确配置PEXELS_API_KEY；确认密钥有效且有访问权限。
- 参考路径：backend/media_fetcher.py
网络超时或连接失败
- 现象：请求抛出超时或连接异常。
- 处理：增加重试次数与指数退避；检查代理与防火墙；在网络稳定后再试。
素材质量不佳
- 现象：分辨率过低、时长不符、许可不满足需求。
- 处理：在筛选阶段严格限定分辨率与时长；优先选择高评分与合适许可的素材；必要时回退到备用关键词。
渲染阶段找不到B-Roll路径
- 现象：渲染报错提示缺少assets.broll映射。
- 处理：确认 broll_fetch_results.json 已生成且路径正确；若渲染阶段使用扁平映射，请在生成 render_props.json 时将该JSON转换为 assets.broll 的键值对。
- 参考路径：assets/1_processed/broll_fetch_results.json
- 参考路径：frontend/src/render-props-types.ts

章节来源

结论

当前 B-Roll 素材获取功能处于占位实现阶段，核心流程已在 main.py 中串联，MediaFetcher 类已预留Pexels API集成、翻译与下载的扩展点。通过明确的筛选标准与本地缓存策略，可有效提升素材质量与系统性能。broll_fetch_results.json 作为中间产物，为渲染阶段提供了稳定的素材索引；未来建议在渲染阶段直接消费该JSON或转换为扁平映射，以契合前端契约。

附录

扩展方案：替换其他素材源
- Pixabay：提供免费与付费素材，支持相似的搜索与过滤能力；需适配其API与许可条款。
- Coverr：专注免费短视频，适合短时长B-Roll；注意其许可与可用性。
- 自建素材库：将已有素材归档到 assets/1_processed/broll/，并在 broll_fetch_results.json 中维护索引，便于统一管理与渲染引用。
开发建议
- 在 media_fetcher.py 中逐步实现 _translate_keyword 与 _download_video。
- 在 main.py 中启用实际的 backend.extractor 与 backend.scripter，以提供真实脚本与关键词。
- 在渲染阶段完善对 broll_fetch_results.json 的转换逻辑，确保 assets.broll 符合前端契约。

15 KiB Raw Blame History Unescape Escape

B-Roll素材获取

目录

简介

项目结构

核心组件

架构总览

详细组件分析

MediaFetcher 类设计与职责

关键词提取与翻译策略

视频筛选标准与下载管理

API请求构造与响应处理

broll_fetch_results.json 结构与渲染引用

代码示例路径（不展示具体代码）

依赖关系分析

性能考量

故障排查指南

结论

附录

15 KiB

Raw Blame History