feat: 滤镜调色引擎 - 8种预设 + 基础调色 + 分段应用 #300

2026-07-14T08:35:41+08:00

xiaoxia commented

2026-07-14 08:35:41 +08:00

功能说明

在统一渲染管道中加入画面色彩调整能力，基于 FFmpeg eq + colorbalance + hue 滤镜组合实现。

核心能力

基础调色 5 参数

亮度（brightness）：-100 ~ +100
对比度（contrast）：-100 ~ +100
饱和度（saturation）：0 ~ 200
色温（temperature）：-100 ~ +100（蓝→暖黄）
色调（hue）：-180 ~ +180 度

8 种风格预设

预设	风格特点
清新	提亮、高饱和、偏冷
日系	低对比、低饱和、偏暖黄
复古	低饱和、偏黄、暖色调
电影	高对比、低饱和、偏冷蓝
胶片	中对比、饱和适中、偏暖
黑白	饱和度=0，对比度略高
暖色	高色温、偏红黄
冷色	低色温、偏蓝青

使用模式

预设 + 自定义覆盖：先加载预设基础参数，再用自定义参数覆盖调整
分段应用：每个 clip 独立配置 color_grade，不同片段可应用不同滤镜
性能优化：所有参数为默认值时跳过滤镜，零性能开销

降级策略

参数越界自动钳制到合法范围
配置解析失败自动降级为无效果，不阻断渲染

滤镜实现

eq 滤镜：亮度 + 对比度 + 饱和度
colorbalance 滤镜：色温（红/绿/蓝三通道阴影/中间调/高光平衡）
hue 滤镜：色调旋转
滤镜顺序：eq → colorbalance → hue

系统集成

从 clip.config.color_grade 读取配置，零侵入数据模型
在 clip 预处理环节（scale/crop 之后，setpts 之前）插入调色滤镜
直通模式（-vf）和 filter_complex 模式均已接入
调色有效果时自动失效 stream copy（需要重编码）

测试覆盖

预设常量：8 种预设完整性、参数范围、色温方向
from_dict 解析：None/空/enabled/preset/自定义/字符串/无效值
resolve_params：默认值/预设应用/自定义覆盖/5 参数边界钳制
has_effect：disabled/默认值/单参数变化/预设/抵消无效果
参数映射：brightness/contrast/saturation/temperature/hue 全验证
build_filter：单参数/多参数组合/标签/滤镜顺序/所有预设有效性
分段调色：不同预设差异/确定性/自定义覆盖影响/有无调色差异

70 个新增单测 + 84 个现有测试，共 154 个全绿，零回归

文件变更

新增：apps/worker/video_processing/color_grade_engine.py（调色引擎核心）
修改：apps/worker/video_processing/unified_render_service.py（接入调色，直通+filter_complex 双路径）
新增：tests/unit/test_color_grade_engine.py（70 个单测）

3 files changed, 999 insertions(+)

## 功能说明在统一渲染管道中加入画面色彩调整能力，基于 FFmpeg eq + colorbalance + hue 滤镜组合实现。 ## 核心能力 ### 基础调色 5 参数 - **亮度**（brightness）：-100 ~ +100 - **对比度**（contrast）：-100 ~ +100 - **饱和度**（saturation）：0 ~ 200 - **色温**（temperature）：-100 ~ +100（蓝→暖黄） - **色调**（hue）：-180 ~ +180 度 ### 8 种风格预设 | 预设 | 风格特点 | |------|----------| | 清新 | 提亮、高饱和、偏冷 | | 日系 | 低对比、低饱和、偏暖黄 | | 复古 | 低饱和、偏黄、暖色调 | | 电影 | 高对比、低饱和、偏冷蓝 | | 胶片 | 中对比、饱和适中、偏暖 | | 黑白 | 饱和度=0，对比度略高 | | 暖色 | 高色温、偏红黄 | | 冷色 | 低色温、偏蓝青 | ### 使用模式 - **预设 + 自定义覆盖**：先加载预设基础参数，再用自定义参数覆盖调整 - **分段应用**：每个 clip 独立配置 color_grade，不同片段可应用不同滤镜 - **性能优化**：所有参数为默认值时跳过滤镜，零性能开销 ### 降级策略 - 参数越界自动钳制到合法范围 - 配置解析失败自动降级为无效果，不阻断渲染 ## 滤镜实现 - **eq 滤镜**：亮度 + 对比度 + 饱和度 - **colorbalance 滤镜**：色温（红/绿/蓝三通道阴影/中间调/高光平衡） - **hue 滤镜**：色调旋转 - **滤镜顺序**：eq → colorbalance → hue ## 系统集成 - 从 `clip.config.color_grade` 读取配置，零侵入数据模型 - 在 clip 预处理环节（scale/crop 之后，setpts 之前）插入调色滤镜 - 直通模式（-vf）和 filter_complex 模式均已接入 - 调色有效果时自动失效 stream copy（需要重编码） ## 测试覆盖 - 预设常量：8 种预设完整性、参数范围、色温方向 - from_dict 解析：None/空/enabled/preset/自定义/字符串/无效值 - resolve_params：默认值/预设应用/自定义覆盖/5 参数边界钳制 - has_effect：disabled/默认值/单参数变化/预设/抵消无效果 - 参数映射：brightness/contrast/saturation/temperature/hue 全验证 - build_filter：单参数/多参数组合/标签/滤镜顺序/所有预设有效性 - 分段调色：不同预设差异/确定性/自定义覆盖影响/有无调色差异 **70 个新增单测 + 84 个现有测试，共 154 个全绿，零回归** ## 文件变更 - 新增：`apps/worker/video_processing/color_grade_engine.py`（调色引擎核心） - 修改：`apps/worker/video_processing/unified_render_service.py`（接入调色，直通+filter_complex 双路径） - 新增：`tests/unit/test_color_grade_engine.py`（70 个单测） 3 files changed, 999 insertions(+)

xiaoxia commented

2026-07-14 09:17:33 +08:00

✅ 代码审计通过

仅3个文件/999行，非常聚焦。

审查要点确认：

✅ 5参数调色（亮度/对比度/饱和度/色温/色调）+ 8种风格预设，参数范围全部钳制
✅ ColorGradeConfig 优先级清晰：自定义参数 > 预设参数 > 默认值
✅ has_effect() 优化：无效果时跳过滤镜，不浪费性能
✅ from_dict 容错好：类型错误/未知预设都优雅降级
✅ 568行测试覆盖：预设完整性、配置解析、滤镜生成、边界值
✅ 集成点干净：每个clip独立调色，在scale之后、fps之前插入

架构亮点： eq + colorbalance + hue 三级滤镜组合，参数映射公式清晰，易扩展

## ✅ 代码审计通过仅3个文件/999行，非常聚焦。 **审查要点确认：** - ✅ 5参数调色（亮度/对比度/饱和度/色温/色调）+ 8种风格预设，参数范围全部钳制 - ✅ ColorGradeConfig 优先级清晰：自定义参数 > 预设参数 > 默认值 - ✅ has_effect() 优化：无效果时跳过滤镜，不浪费性能 - ✅ from_dict 容错好：类型错误/未知预设都优雅降级 - ✅ 568行测试覆盖：预设完整性、配置解析、滤镜生成、边界值 - ✅ 集成点干净：每个clip独立调色，在scale之后、fps之前插入 **架构亮点：** eq + colorbalance + hue 三级滤镜组合，参数映射公式清晰，易扩展

xiaoxia added 2 commits 2026-07-14 09:36:08 +08:00

feat: 滤镜调色引擎 - 8种预设 + 基础调色 + 分段应用 f991da2b33

新增 ColorGradeEngine，在统一渲染管道中加入画面色彩调整能力：

核心能力：
- 基础调色5参数：亮度(-100~100)、对比度(-100~100)、饱和度(0~200)、色温(-100~100)、色调(-180~180)
- 8种风格预设：清新、日系、复古、电影、胶片、黑白、暖色、冷色
- 预设+自定义覆盖模式：先加载预设参数，再用自定义值覆盖
- 分段应用：每个 clip 独立配置 color_grade，不同片段不同风格
- 降级策略：参数越界自动钳制到合法范围，解析失败不阻断渲染
- 性能优化：无效果（所有参数=默认值）时跳过滤镜，零开销

滤镜实现：
- eq 滤镜：亮度(brightness) + 对比度(contrast) + 饱和度(saturation)
- colorbalance 滤镜：色温（红/绿/蓝三通道平衡）
- hue 滤镜：色调调整
- 滤镜顺序：eq → colorbalance → hue

系统集成：
- 每个 clip 的 config.color_grade 读取配置
- 在 clip 预处理环节（scale/crop 之后，setpts 之前）插入调色滤镜链
- 直通模式(-vf)和 filter_complex 模式均已接入
- 调色有效果时自动失效 stream copy（需重编码）

测试覆盖：
- 预设常量：8种预设完整性、参数范围校验、色温方向验证
- from_dict：None/空/enabled/preset/自定义/字符串值/无效值
- resolve_params：默认值/预设应用/自定义覆盖/5参数边界钳制
- has_effect：disabled/默认值/单参数变化/预设/抵消无效果
- 参数映射：brightness/contrast/saturation/temperature/hue 全部验证
- build_filter：单参数/多参数组合/标签/滤镜顺序/所有预设有效性
- 分段调色：不同预设不同滤镜/确定性/自定义覆盖影响/有无调色差异

70个新增单测 + 84个现有测试，共154个全绿，零回归

chore: rebase到develop + 格式化代码

CI/CD Pipeline / Validate Code Quality And Tests (pull_request) Successful in 35s

Details

CI/CD Pipeline / Unit Tests (pull_request) Successful in 1m20s

Details

CI/CD Pipeline / Integration Tests (pull_request) Successful in 2m3s

Details

CI/CD Pipeline / Frontend Lint (pull_request) Successful in 6m56s

Details

CI/CD Pipeline / Build & Push Staging (Watchtower auto-deploy) (pull_request) Has been skipped

Details

CI/CD Pipeline / Build Production Runtime Images (pull_request) Has been skipped

Details

CI/CD Pipeline / Staging E2E Tests (pull_request) Has been skipped

Details

CI/CD Pipeline / Staging API Integration Tests (pull_request) Has been skipped

Details

CI/CD Pipeline / Deploy Production (pull_request) Has been skipped

Details

CI/CD Pipeline / Production Browser E2E (pull_request) Has been skipped

Details

e47583a3c3

xiaoxia force-pushed feat/color-grading-engine from 15f9e4761e to e47583a3c3

2026-07-14 09:36:08 +08:00

Compare

xiaoxia merged commit e430d83f78 into develop

2026-07-14 09:51:03 +08:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: xiaoxia/xiaoxia-saas#300