如何在QML MediaPlayer中设置字幕？setSubtitleText无法调用

QVideoSink::setSubtitleText() 在Qt 6.2、6.3、6.4三个版本中，虽然是C++层公开接口，但没有添加Q_INVOKABLE元标记，也没有暴露为QML可访问属性，QML元对象系统根本识别不到这个方法，访问拿到undefined、调用报类型错误是必然结果。
另外你的测试代码存在访问路径问题：MediaPlayer的videoOutput属性需要手动绑定你自己创建的VideoOutput实例才会有有效值，你现在能打印出QVideoSink实例只是拿到了内部未文档化的私有对象，不是稳定访问路径，版本变动就可能失效。

方案1：升级Qt版本到6.5及以上（推荐） #

从Qt 6.5开始，Qt Multimedia不仅给setSubtitleText加了Q_INVOKABLE标记允许QML直接调用，还提供了更简便的字幕使用方式，不需要手动钻取videoSink对象：

• 内嵌字幕/外挂字幕文件直接给MediaPlayer的subtitleTracks属性赋值即可自动加载渲染
• 手动设置自定义字幕文本时，直接给VideoOutput的subtitleText属性赋值即可，连对象判空步骤都可以省略：

MediaPlayer {
    id: mediaPlayer
    source: "test.mp4"
    videoOutput: videoOut // 手动绑定VideoOutput实例，不要靠隐式访问
}

VideoOutput {
    id: videoOut
    anchors.fill: parent
}

Button {
    text: "测试字幕"
    onClicked: videoOut.subtitleText = "I'm a subtitle!"
}

如果要直接调用videoSink的方法，也可以正常识别：

Button {
    text: "通过sink设置字幕"
    onClicked: {
        if(videoOut.videoSink) {
            videoOut.videoSink.setSubtitleText("I'm a subtitle!")
        }
    }
}

方案2：低版本Qt（6.2~6.4）兼容方案 #

如果暂时不能升级Qt版本，只需要写一个极简单的C++辅助类，把QVideoSink的setSubtitleText方法包装成QML可调用的接口即可：

1. 编写包装类头文件：

#ifndef QMLVIDEOSINKHELPER_H
#define QMLVIDEOSINKHELPER_H

#include <QObject>
#include <QVideoSink>

class QmlVideoSinkHelper : public QObject
{
    Q_OBJECT
public:
    explicit QmlVideoSinkHelper(QObject *parent = nullptr) : QObject(parent) {}

public slots:
    // 声明为槽函数，QML可直接识别调用
    void setSubtitleText(QVideoSink* sink, const QString& text) {
        if(sink) sink->setSubtitleText(text);
    }
};

#endif // QMLVIDEOSINKHELPER_H

2. 在main.cpp中把辅助类注册到QML上下文：

#include "qmlvideosinkhelper.h"

int main(int argc, char *argv[])
{
    QGuiApplication app(argc, argv);
    QQmlApplicationEngine engine;
    // 注册全局可访问的辅助实例
    engine.rootContext()->setContextProperty("VideoSinkHelper", new QmlVideoSinkHelper());
    // 原有QML加载逻辑保持不变
}

3. QML中直接调用辅助方法即可：

Button {
    text: "低版本设置字幕"
    onClicked: VideoSinkHelper.setSubtitleText(videoOut.videoSink, "I'm a subtitle!")
}

• 不要通过mediaPlayer.videoOutput的路径隐式访问VideoOutput实例，一定要手动给MediaPlayer绑定自己创建的VideoOutput对象，避免访问内部私有对象导致随机崩溃。
• 字幕渲染依赖平台的视频输出后端，部分嵌入式平台的旧版后端可能不支持字幕叠加，使用前需要先确认对应平台的后端适配情况。

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