调用VideoWriter.getBackendName()报错，Linux下OpenCV视频写入异常排查

问题现象 #

相同代码在macOS可正常运行，输出AVFOUNDATION，但在Linux环境调用VideoWriter.backendName时触发断言错误，提示api != 0，且VideoWriter大概率未成功初始化。

测试代码 #

class VideoWriterTest {
    @Test
    fun write() {
        OpenCV.loadLocally()
        println("opencv version=${Core.getVersionString()}")

        val fourcc = VideoWriter.fourcc('a', 'c', 'v', '1')
        val size1 = Size(100.0, 100.0)
        val outputFile= File("temp.mp4")
        outputFile.delete()
        val writer = VideoWriter(outputFile.path, fourcc, 30.0, size1)
        println( writer.backendName)
        assertTrue(writer.isOpened)
    }
}

报错信息 #

opencv version=4.6.0

cv::Exception: OpenCV(4.6.0) /home/runner/work/opencv/opencv/opencv-4.6.0/modules/videoio/src/cap.cpp:666: error: (-215:Assertion failed) api != 0 in function 'getBackendName'

CvException [org.opencv.core.CvException: cv::Exception: OpenCV(4.6.0) /home/runner/work/opencv/opencv/opencv-4.6.0/modules/videoio/src/cap.cpp:666: error: (-215:Assertion failed) api != 0 in function 'getBackendName'
]
    at app//org.opencv.videoio.VideoWriter.getBackendName_0(Native Method)
    at app//org.opencv.videoio.VideoWriter.getBackendName(VideoWriter.java:380)
    at app//com.katalisindonesia.heavi.analytic.service.VideoWriterTest.write(VideoWriterTest.kt:26)

使用依赖：org.openpnp:opencv:4.6.0-0

解决思路 #

1. 先确认VideoWriter是否初始化成功 #

错误根源是VideoWriter在Linux下未成功打开，导致后端API句柄为0，调用getBackendName触发断言。必须先检查初始化状态：

if (!writer.isOpened) {
    println("VideoWriter初始化失败")
    return
}

2. 更换Linux兼容的编码格式 #

acv1编码在Linux环境可能不受支持，换成通用的MP4编码格式：

// 推荐使用MP4V或XVID
val fourcc = VideoWriter.fourcc('M', 'P', '4', 'V')
// val fourcc = VideoWriter.fourcc('X', 'V', 'I', 'D')

3. 显式指定Linux视频后端 #

Linux下OpenCV可能未自动匹配到可用后端（如FFmpeg），手动指定CAP_FFMPEG：

// 构造时添加后端参数
val writer = VideoWriter(outputFile.path, fourcc, 30.0, size1, true, Videoio.CAP_FFMPEG)

4. 安装系统级FFmpeg依赖 #

org.openpnp:opencv依赖系统FFmpeg库，Linux需手动安装：

# Debian/Ubuntu系列
sudo apt-get install ffmpeg libavcodec-dev libavformat-dev libswscale-dev

# RHEL/CentOS系列
sudo yum install ffmpeg ffmpeg-devel

5. 更换完整功能的OpenCV依赖包 #

若org.openpnp的包在Linux下裁剪了视频编码功能，可换用bytedeco的完整包：

<!-- Maven依赖示例 -->
<dependency>
    <groupId>org.bytedeco</groupId>
    <artifactId>opencv-platform</artifactId>
    <version>4.6.0-1.5.7</version>
</dependency>

修改后的测试代码示例 #

class VideoWriterTest {
    @Test
    fun write() {
        OpenCV.loadLocally()
        println("opencv version=${Core.getVersionString()}")

        val fourcc = VideoWriter.fourcc('M', 'P', '4', 'V')
        val size1 = Size(100.0, 100.0)
        val outputFile = File("temp.mp4")
        outputFile.delete()
        
        val writer = VideoWriter(outputFile.path, fourcc, 30.0, size1, true, Videoio.CAP_FFMPEG)
        
        if (writer.isOpened) {
            println(writer.backendName)
            assertTrue(true)
        } else {
            println("VideoWriter初始化失败，请检查编码格式或系统依赖")
            assertTrue(false, "VideoWriter未成功打开")
        }
    }
}

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