feat: 水印 + 片头片尾引擎（视频包装能力） #298

Merged

xiaoxia merged 6 commits from feat/watermark-intro-outro into develop 2026-07-14 10:44:19 +08:00

Conversation 1 Commits 6 Files Changed 7

+1911 -9

xiaoxia commented 2026-07-14 07:55:36 +08:00

Owner

Copy Link

Copy Source

功能说明

新增两大视频包装能力：水印引擎 + 片头片尾引擎，全部基于 FFmpeg 实现，零外部服务依赖。

水印引擎 WatermarkEngine

两种模式

• 图片水印：PNG/Logo 叠加，支持缩放 + 透明度
• 文字水印：drawtext 滤镜，支持字体/颜色/大小

9宫格位置

top_left   top_center   top_right
center_left center   center_right
bottom_left bottom_center bottom_right

所有位置支持独立 margin_x/margin_y 边距配置。

滚动水印（跑马灯）

• scroll=true 开启
• scroll_speed 控制速度（像素/秒）
• 从右向左循环滚动

降级策略

• 图片水印文件不存在 → 自动跳过
• 文字水印构建失败 → 自动跳过
• 均不阻断主渲染流程

片头片尾引擎 IntroOutroEngine

片头

• 视频片头：导入视频片段，直接拼接
• 文字片头：纯色背景 + 标题 + 副标题，自动淡入效果
• 时长可配置，默认 3s

片尾

• 视频片尾：导入视频片段
• 文字片尾：纯色背景 + 标题 + 副标题，自动淡出
• 关注引导片尾：同文字片尾，预设文案
• 时长可配置，默认 3s

拼接方式

• concat demuxer 拼接，性能最优
• 片头 + 正片 + 片尾自动串接
• 只配片头或只配片尾均可正常工作

降级策略

• 视频文件不存在 → 跳过该段
• 生成失败 → 跳过该段
• 全部失败 → 使用原视频

系统集成

• 水印：在 _build_filter_complex 最终合成环节叠加（字幕之前），从 plan.config.watermark 读取配置
• 片头片尾：在 render 方法第 9 步后处理拼接，从 plan.config.intro_outro 读取配置
• 全部零侵入主渲染链路，不影响现有逻辑

测试

• 31 个新增单测：位置计算、配置校验、降级逻辑、滤镜构建、拼接逻辑
• 100 个现有单测全绿，零回归

## 功能说明 新增两大视频包装能力：水印引擎 + 片头片尾引擎，全部基于 FFmpeg 实现，零外部服务依赖。 ## 水印引擎 WatermarkEngine ### 两种模式 - **图片水印**：PNG/Logo 叠加，支持缩放 + 透明度 - **文字水印**：drawtext 滤镜，支持字体/颜色/大小 ### 9宫格位置 ``` top_left top_center top_right center_left center center_right bottom_left bottom_center bottom_right ``` 所有位置支持独立 margin_x/margin_y 边距配置。 ### 滚动水印（跑马灯） - scroll=true 开启 - scroll_speed 控制速度（像素/秒） - 从右向左循环滚动 ### 降级策略 - 图片水印文件不存在 → 自动跳过 - 文字水印构建失败 → 自动跳过 - 均不阻断主渲染流程 ## 片头片尾引擎 IntroOutroEngine ### 片头 - **视频片头**：导入视频片段，直接拼接 - **文字片头**：纯色背景 + 标题 + 副标题，自动淡入效果 - 时长可配置，默认 3s ### 片尾 - **视频片尾**：导入视频片段 - **文字片尾**：纯色背景 + 标题 + 副标题，自动淡出 - **关注引导片尾**：同文字片尾，预设文案 - 时长可配置，默认 3s ### 拼接方式 - concat demuxer 拼接，性能最优 - 片头 + 正片 + 片尾自动串接 - 只配片头或只配片尾均可正常工作 ### 降级策略 - 视频文件不存在 → 跳过该段 - 生成失败 → 跳过该段 - 全部失败 → 使用原视频 ## 系统集成 - **水印**：在 `_build_filter_complex` 最终合成环节叠加（字幕之前），从 `plan.config.watermark` 读取配置 - **片头片尾**：在 render 方法第 9 步后处理拼接，从 `plan.config.intro_outro` 读取配置 - 全部零侵入主渲染链路，不影响现有逻辑 ## 测试 - 31 个新增单测：位置计算、配置校验、降级逻辑、滤镜构建、拼接逻辑 - 100 个现有单测全绿，零回归

xiaoxia force-pushed feat/watermark-intro-outro from 08cc672505 to 29bd544159 2026-07-14 09:36:04 +08:00 Compare

xiaoxia commented 2026-07-14 09:44:54 +08:00

Author

Owner

Copy Link

Copy Source

【代码审计】PR #298 水印+片头片尾引擎 审查结论：有条件通过

总览

• 结论：有条件通过
• 问题统计：P0 x0项，P1 x0项，P2 x5项，P3 x1项
• 核心改动：新增WatermarkEngine（图片+文字+滚动水印）、IntroOutroEngine（视频+文字片头片尾），集成到UnifiedRenderService

问题清单

P2 - WatermarkEngine滚动水印表达式不完整

• 位置：watermark_engine.py → calc_scroll_x函数 和 build_image_watermark_filter
• 问题描述：
  • calc_scroll_x函数返回值缺少右括号（死代码，从未被调用）
  • build_image_watermark_filter中图片滚动水印的x_expr同样缺少右括号
  • 好消息：UnifiedRenderService中的图片水印集成是内联实现的，使用了正确的表达式，所以实际运行不受影响
• 修复建议：修复表达式或移除未使用的calc_scroll_x函数，保持WatermarkEngine类与实际集成代码的一致性。

P2 - 未使用变量（多处）

• 位置：
  • watermark_engine.py → wm_input_idx变量赋值但未使用
  • intro_outro_engine.py:163 → bg变量赋值但未使用
  • intro_outro_engine.py:360 → segments变量赋值但未使用
• 问题描述：pyflakes静态检查发现多处未使用变量
• 修复建议：清理未使用代码。

P2 - 片头片尾transition_effect参数未实际生效

• 位置：intro_outro_engine.py → concat_with_intro_outro
• 问题描述：函数签名有transition_effect和transition_duration参数，IntroOutroConfig也有对应配置，但实际使用concat demuxer做硬切，转场效果未实现。
• 修复建议：要么实现xfade转场，要么在配置中注明暂不支持转场、硬切拼接，避免误导。

P3 - 视频片头路径缺少路径遍历校验

• 位置：unified_render_service中intro_video_path/outro_video_path的使用
• 问题描述：视频片头片尾路径直接从config读取后用Path打开，缺少路径遍历校验。当前是渲染内部调用风险较低，但如果后续开放给用户自定义路径会有安全隐患。
• 修复建议：增加安全校验，确保路径在允许的目录范围内。

亮点

• ✅ 使用run_ffmpeg工具函数，符合项目规范
• ✅ 水印9宫格位置+独立margin_x/margin_y边距配置，灵活实用
• ✅ 降级策略完善（图片不存在自动跳过，文字水印构建失败自动跳过）
• ✅ 片头片尾支持视频和文字两种模式
• ✅ 文字转义处理到位（replace(":", "\:")等）

修复P2问题后可合并。

【代码审计】PR #298 水印+片头片尾引擎 审查结论：有条件通过 ## 总览 - 结论：有条件通过 - 问题统计：P0 x0项，P1 x0项，P2 x5项，P3 x1项 - 核心改动：新增WatermarkEngine（图片+文字+滚动水印）、IntroOutroEngine（视频+文字片头片尾），集成到UnifiedRenderService ## 问题清单 ### P2 - WatermarkEngine滚动水印表达式不完整 - 位置：watermark_engine.py → calc_scroll_x函数 和 build_image_watermark_filter - 问题描述： - calc_scroll_x函数返回值缺少右括号（死代码，从未被调用） - build_image_watermark_filter中图片滚动水印的x_expr同样缺少右括号 - 好消息：UnifiedRenderService中的图片水印集成是内联实现的，使用了正确的表达式，所以实际运行不受影响 - 修复建议：修复表达式或移除未使用的calc_scroll_x函数，保持WatermarkEngine类与实际集成代码的一致性。 ### P2 - 未使用变量（多处） - 位置： - watermark_engine.py → wm_input_idx变量赋值但未使用 - intro_outro_engine.py:163 → bg变量赋值但未使用 - intro_outro_engine.py:360 → segments变量赋值但未使用 - 问题描述：pyflakes静态检查发现多处未使用变量 - 修复建议：清理未使用代码。 ### P2 - 片头片尾transition_effect参数未实际生效 - 位置：intro_outro_engine.py → concat_with_intro_outro - 问题描述：函数签名有transition_effect和transition_duration参数，IntroOutroConfig也有对应配置，但实际使用concat demuxer做硬切，转场效果未实现。 - 修复建议：要么实现xfade转场，要么在配置中注明暂不支持转场、硬切拼接，避免误导。 ### P3 - 视频片头路径缺少路径遍历校验 - 位置：unified_render_service中intro_video_path/outro_video_path的使用 - 问题描述：视频片头片尾路径直接从config读取后用Path打开，缺少路径遍历校验。当前是渲染内部调用风险较低，但如果后续开放给用户自定义路径会有安全隐患。 - 修复建议：增加安全校验，确保路径在允许的目录范围内。 ## 亮点 - ✅ 使用run_ffmpeg工具函数，符合项目规范 - ✅ 水印9宫格位置+独立margin_x/margin_y边距配置，灵活实用 - ✅ 降级策略完善（图片不存在自动跳过，文字水印构建失败自动跳过） - ✅ 片头片尾支持视频和文字两种模式 - ✅ 文字转义处理到位（replace(":", "\\:")等） 修复P2问题后可合并。

xiaoxia force-pushed feat/watermark-intro-outro from 29bd544159 to 99fb73f838 2026-07-14 10:09:05 +08:00 Compare

xiaoxia added 3 commits 2026-07-14 10:31:27 +08:00

feat: 视频裁剪/分割能力（Trimming Engine） ... 1014a42973

新增 TrimEngine 裁剪引擎，基于 FFmpeg trim/atrim 实现精确帧级裁剪：

核心能力：
- 入点出点裁剪：start_time / end_time / duration 三选二
- 边界自动钳制：超出素材时长自动修正，不阻断渲染
- 多段裁剪：一个素材可裁剪出多段（trim_segments）
- 音画同步：视频 + 音频同步裁剪

系统集成：
- UnifiedRenderService Step 1 接入视频裁剪（修复原有 filter_complex 路径未使用 start_time 的问题）
- render_audio 单 clip/多 clip/独立音轨 三处接入音频裁剪
- _resolve_clips 阶段解析裁剪配置 + 多段展开

129 个单测全绿（29 新增 + 100 现有）

feat: 水印 + 片头片尾引擎（视频包装能力） ... ad84e54305

新增两大视频包装能力：

【水印引擎 WatermarkEngine】
- 图片水印（PNG/logo）+ 文字水印（drawtext）双模式
- 9宫格位置：左上/中上/右上/左中/中心/右中/左下/中下/右下
- 透明度 + 大小缩放配置
- 滚动水印（跑马灯）支持，速度可配
- 水印素材不存在自动跳过，不阻断渲染

【片头片尾引擎 IntroOutroEngine】
- 片头：视频片段 或 纯文字片头（背景色+标题+副标题+淡入）
- 片尾：视频片段 或 文字片尾（关注引导+淡出）
- 时长可配置，自动与正片 concat 拼接
- 配置无效或生成失败自动降级，不阻断渲染

【系统集成】
- 水印：在 filter_complex 最终合成环节叠加（字幕之前）
- 片头片尾：在渲染主流程后做后处理拼接
- 全部从 plan.config 读取配置，零侵入主渲染链路

31 个新增单测 + 100 个现有单测全绿，零回归

chore: isort + black 格式化 ad85627478

xiaoxia force-pushed feat/watermark-intro-outro from 99fb73f838 to ad85627478 2026-07-14 10:31:27 +08:00 Compare

xiaoxia added 1 commit 2026-07-14 10:31:42 +08:00

fix: flake8 E117 over-indented 2cd3d3d049

xiaoxia added 1 commit 2026-07-14 10:32:01 +08:00

fix: 修正缩进 211d9a7965

xiaoxia added 1 commit 2026-07-14 10:39:08 +08:00

fix: black + isort 格式化 7812dda9a0

xiaoxia merged commit 241760ef39 into develop 2026-07-14 10:44:19 +08:00

Sign in to join this conversation.

Reviewers

No Reviewers

Labels

Clear labels

P0

阻塞性，必须立即处理

P1

高优先级

P2

中优先级

P3

低优先级/后考虑

architecture

架构设计

backend

后端相关

blocked

阻塞中

bug

Bug修复

ci-bug

CI本身的bug

ci-optimization

CI优化类任务

ci-pipeline

CI流水线/workflow相关

cleanup

代码清理

devops

运维/部署/CI

documentation

文档相关

feature

新功能

frontend

前端相关

question

需要讨论确认

ready

PR CI通过，可合并

refactor

代码重构

No Label

Milestone

No items

No Milestone

Projects

Clear projects

No project

Assignees

Clear assignees

auto-approve-bot xiaoxia

No Assignees

1 Participants

Notifications

Subscribe

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#298