本文详解 MoviePy 2.1+ 中 HeadBlur 的正确用法，解决因参数设置不当导致模糊失效的问题，并提供可落地的垂直视频居中+动态模糊背景完整方案。
本文详解 moviepy 2.1+ 中 `headblur` 的正确用法，解决因参数设置不当导致模糊失效的问题，并提供可落地的垂直视频居中+动态模糊背景完整方案。
在 MoviePy 2.0+ 版本中，旧版 blur() 已被弃用，取而代之的是更精细但易误用的 HeadBlur 效果——它本质是一个以指定坐标为中心、按半径和强度进行局部高斯模糊的动态滤镜，并非全帧静态模糊。这也是用户代码中 radius=20 完全无视觉变化的根本原因：该值远小于视频尺寸（如 960×540），且未设置关键参数 intensity，导致模糊核退化为近似均值填充（即“发灰”而非“模糊”）。
要实现「水平原始视频居中显示 + 全屏动态模糊背景」的垂直视频效果（如 1080×1920），推荐采用两步合成法：先将原视频缩放并居中置于纯色背景上，再对整个背景层应用 HeadBlur，最后叠加原视频。注意：HeadBlur 的 fx/fy 应固定为背景中心坐标（非时间函数），radius 需足够大（≥背景宽高较大值），intensity 控制模糊程度（建议 30–80）：
from moviepy import VideoFileClip, ColorClip, CompositeVideoClip
from moviepy.video.fx import HeadBlur
# 1. 加载原始视频（假设为 960×540 横屏）
video = VideoFileClip("input.mp4")
# 2. 创建竖屏背景（1080×1920），填充黑色（可替换为其他颜色）
background = ColorClip(size=(1080, 1920), color=(0, 0, 0), duration=video.duration)
# 3. 计算居中缩放后的尺寸（保持宽高比，高度填满）
scaled_video = video.resize(height=1920 * 0.7) # 主视频占背景高度约70%
scaled_video = scaled_video.set_position(("center", "center"))
# 4. 对背景应用 HeadBlur：固定中心点 + 大半径 + 合理强度
center_x = background.w / 2
center_y = background.h / 2
blurred_bg = background.with_effects([
HeadBlur(
fx=lambda t: center_x, # 固定X中心，非时间函数！
fy=lambda t: center_y, # 固定Y中心
radius=2000, # ≥ max(background.w, background.h)
intensity=50 # 强度 30~80，值越大越模糊
)
])
# 5. 合成：模糊背景 + 居中原始视频
final = CompositeVideoClip([blurred_bg, scaled_video])
final.write_videofile(
"output_vertical_blurred.mp4",
codec="libx264",
audio_codec="aac",
fps=video.fps,
threads=4
)⚠️ 关键注意事项：
-
fx/fy必须返回绝对像素坐标（如background.w/2），而非时间相关函数（原问题中x1(t)错误地尝试做动态位移）； -
radius过小（如 20）会导致模糊区域极小，视觉不可见；过大（如 9999）虽安全，但会增加计算开销，建议设为max(w, h) * 1.2； -
intensity是模糊质量的核心——默认为 0（无模糊），需显式设置（30 轻微模糊，70 明显虚化，>100 可能出现边缘伪影）； - 若需真正全帧均匀高斯模糊（非圆形区域），MoviePy 2.x 原生暂不支持，可改用
vfx.mask_and_blur组合或导出帧后用 OpenCV 处理。
总结：HeadBlur 并非“全图模糊工具”，而是“可控焦点模糊工具”。理解其设计意图（模拟镜头焦点偏移/人像虚化），合理配置中心点、半径与强度，才能精准达成背景虚化需求。对于本例的竖屏包装场景，上述两步合成法稳定可靠，兼顾性能与效果。
