cv2.VideoWriter生成的MP4无法在VSCode/Streamlit预览求助

我开发机器学习足球分析系统时，用以下代码保存处理后的视频帧：

from typing import List
import numpy as np
import cv2

def save_video(frames: List[np.ndarray], path: str, fps: int=24) -> None:
    fourcc = cv2.VideoWriter_fourcc(*"avc1")    # codec for compressing the video
    out = cv2.VideoWriter(filename=path, fourcc=fourcc, fps=fps, frameSize=(frames[0].shape[1], frames[0].shape[0]))
    
    for frame in frames:
        out.write(frame)
    
    # close video file and release ressources
    out.release() 

现象：生成的视频能在Windows媒体播放器正常播放，Mac系统下也完全正常，但在VSCode内置视频播放器、Streamlit应用中无法打开或显示；尝试将fourcc改为mp4v后问题依旧。

解决方案 #

1. 修正色彩空间（核心问题）

OpenCV默认处理的帧是BGR格式，但VSCode/Streamlit依赖的Chromium渲染引擎期望RGB格式。保存前转换色彩空间：

def save_video(frames: List[np.ndarray], path: str, fps: int=24) -> None:
    # 将BGR帧转换为RGB（如果你的帧是OpenCV读取/处理的，默认就是BGR）
    frames_rgb = [cv2.cvtColor(frame, cv2.COLOR_BGR2RGB) for frame in frames]
    
    fourcc = cv2.VideoWriter_fourcc(*"avc1")
    # 显式指定isColor=True，避免自动检测出错
    out = cv2.VideoWriter(
        filename=path,
        fourcc=fourcc,
        fps=fps,
        frameSize=(frames_rgb[0].shape[1], frames_rgb[0].shape[0]),
        isColor=True
    )
    
    for frame in frames_rgb:
        out.write(frame)
    
    out.release()

2. 规范视频元数据（针对流式加载）

VSCode和Streamlit需要视频支持流式加载，默认生成的MP4可能把索引信息（moov原子）放在文件末尾，导致播放器无法快速解析。用ffmpeg重新封装（无编码损耗，速度极快）：

ffmpeg -i input.mp4 -c copy -movflags +faststart output_compatible.mp4

如果需要在Python中自动完成，可调用subprocess：

import subprocess

def fix_video_metadata(input_path, output_path):
    subprocess.run([
        "ffmpeg", "-i", input_path,
        "-c", "copy",
        "-movflags", "+faststart",
        output_path
    ], check=True)

# 使用示例
save_video(frames, "temp.mp4")
fix_video_metadata("temp.mp4", "final.mp4")

3. Streamlit加载视频的正确姿势

确保传入正确的文件路径，或直接读取字节流：

import streamlit as st

# 方法1：直接传入文件路径
st.video("final.mp4")

# 方法2：读取字节流（适合临时文件或内存中的视频）
with open("final.mp4", "rb") as video_file:
    st.video(video_file.read())

原因说明 #

Windows媒体播放器对非标准视频的容错性极高，能自动适配BGR色彩空间和非流式元数据；但VSCode、Streamlit基于Chromium内核，对视频编码格式、色彩空间、元数据的规范要求更严格，必须符合Web标准的RGB色彩空间和流式加载要求。

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