MoviePy write_videofile报错TypeError:需实数，不能为NoneType

问题现象 #

Python环境下使用MoviePy库开发自动化视频合成程序，音频轨道渲染流程可正常完成，但启动视频画面渲染环节时立即抛出TypeError: must be real number, not NoneType错误，错误触发点为代码中调用finalVideo.write_videofile()导出最终MP4文件的代码行。

程序核心逻辑 #

• 遍历指定目录下的音频片段、图片素材，拼接为带间隔的音频轨和图片画面层
• 加载库存素材视频作为背景，循环至与画面层等长
• 加载背景音乐循环后与原音频混合为最终音轨
• 将背景视频、图片画面层合成为最终视频并绑定音轨，调用write_videofile完成导出

已完成排查操作 #

• 异常出现于运行环境从Python 3.10降级切换为Python 3.9之后，此前Python3.10环境下程序可正常运行
• 已在MoviePy的config_defaults.py配置文件中正确设置IMAGEMAGICK_BINARY = r'C:\Program Files\ImageMagick-7.1.0-Q16-HDRI\magick.exe'
• 已将MoviePy库升级至最新正式版本1.0.3

错误根因 #

根据错误回溯栈信息，异常最终触发于moviepy/video/io/ffmpeg_writer.py文件的FFMPEG_VideoWriter初始化环节，执行'-r', '%.02f' % fps语句时检测到fps参数为NoneType类型，不符合语句要求的实数类型，因此抛出类型错误。
该问题是Python 3.9环境搭配MoviePy 1.0.3版本的已知兼容bug：当合成剪辑中包含未显式设置fps的ImageClip对象时，CompositeVideoClip的fps属性传递逻辑失效，最终生成的视频对象fps值为None，导出时无法自动推断出合法帧率。

修复方案 #

按优先级依次操作即可解决问题：

1. 所有图片剪辑创建时显式设置fps
   创建ImageClip实例时不要省略fps参数，从素材源头避免属性丢失：

# 原易出错写法
img_clip = ImageClip("demo.jpg").set_duration(2)
# 修正后写法
img_clip = ImageClip("demo.jpg").set_duration(2).set_fps(25)

2. 合成最终视频后校验fps属性
   完成所有剪辑合成、绑定音轨后，在导出前主动检查并补全fps值：

# 合成完finalVideo对象后添加以下代码
if finalVideo.fps is None:
    finalVideo.fps = 25

3. 导出方法中显式传入fps参数
   调用write_videofile时不要依赖自动推断，主动指定fps参数：

finalVideo.write_videofile(
    "final_output.mp4",
    fps=25, # 可根据需求替换为24/30等常用帧率，和前面设置的剪辑fps保持一致即可
    codec="libx264",
    audio_codec="aac"
)

注：ImageMagick配置不影响该错误触发，无需重复调整ImageMagick相关配置项。

内容的提问来源于stack exchange，提问作者THEMOUNTAINSANDTHESKIES