integrate pywhispercpp into a GUI product using PyQt

[xiao-xiang]

When I integrate pywhispercpp into a GUI product using PyQt, pywhispercpp blocks the UI when extracting text, and this issue persists even when the operation is placed in a child thread.

[absadiki]

Could you please provide a minimal, reproducible code example that shows the problem?

[xiao-xiang]

import sys
import os
import threading
from PyQt5.QtCore import Qt, QThread, pyqtSignal, pyqtSlot, QObject
from PyQt5.QtGui import QTextCursor
from PyQt5.QtWidgets import (QApplication, QMainWindow, QPushButton, QVBoxLayout,
QHBoxLayout, QTextEdit, QWidget, QProgressBar, QLabel,
QFileDialog, QMessageBox, QComboBox, QGroupBox)
from pywhispercpp.model import Model

class WhisperWorker(QObject):

progress_updated = pyqtSignal(int, str)
text_segment = pyqtSignal(str)  
task_completed = pyqtSignal(str)  
error_occurred = pyqtSignal(str)  
task_started = pyqtSignal() 

def __init__(self, model_path, audio_path):
    super().__init__()
    self.model_path = model_path
    self.audio_path = audio_path
    self._is_running = True

def run(self):
    try:
        self.task_started.emit()
        self.progress_updated.emit(0, "正在加载模型...")

        # 初始化模型
        model = Model(
            self.model_path,
            print_progress=True
        )

        self.progress_updated.emit(10, "模型加载完成，开始识别...")

        # 使用回调函数获取实时结果
        full_text = ""

        def segment_callback(segment):
            if not self._is_running:
                return False  # 停止识别
            text = segment.text
            self.text_segment.emit(text)
            nonlocal full_text
            full_text += text + "\n"
            return True  # 继续识别

        # 执行识别
        model.transcribe(
            self.audio_path
        )

        self.progress_updated.emit(100, "识别完成")
        self.task_completed.emit(full_text)

    except Exception as e:
        self.error_occurred.emit(str(e))

def stop(self):
    """停止任务执行"""
    self._is_running = False

class SpeechToTextApp(QMainWindow):

def __init__(self):
    super().__init__()

    # 设置窗口属性
    self.setWindowTitle("高性能语音转文字工具")
    self.setGeometry(100, 100, 1200, 800)

    # 可用模型列表
    self.models = {
        "tiny.en": "ggml-tiny.en.bin",
        "tiny": "ggml-tiny.bin",
        "base.en": "ggml-base.en.bin",
        "base": "ggml-base.bin",
        "small.en": "ggml-small.en.bin",
        "small": "ggml-small.bin",
        "medium.en": "ggml-medium.en.bin",
        "medium": "ggml-medium.bin",
        "large": "ggml-large.bin"
    }

    # 语言列表
    self.languages = {
        "自动检测": None,
        "中文": "zh",
        "英语": "en",
        "日语": "ja",
        "韩语": "ko",
        "法语": "fr",
        "西班牙语": "es",
        "德语": "de",
        "俄语": "ru",
        "葡萄牙语": "pt",
        "意大利语": "it"
    }

    # 创建中心部件和布局
    self.central_widget = QWidget()
    self.setCentralWidget(self.central_widget)
    self.main_layout = QVBoxLayout(self.central_widget)

    # 创建顶部控制面板
    self.create_control_panel()

    # 创建文本显示区域
    self.create_text_display()

    # 创建状态栏
    self.statusBar().showMessage("就绪")

    # 初始化变量
    self.worker = None
    self.thread = None
    self.current_audio_file = None

    # 显示界面
    self.show()

def create_control_panel(self):
    """创建控制面板"""
    control_frame = QWidget()
    control_layout = QVBoxLayout(control_frame)

    # 第一行：模型选择和文件选择
    top_row = QWidget()
    top_layout = QHBoxLayout(top_row)

    # 模型选择
    model_group = QGroupBox("模型")
    model_layout = QHBoxLayout()
    self.model_combo = QComboBox()
    self.model_combo.addItems(list(self.models.keys()))
    model_layout.addWidget(self.model_combo)
    model_group.setLayout(model_layout)
    top_layout.addWidget(model_group)

    # 语言选择
    lang_group = QGroupBox("语言")
    lang_layout = QHBoxLayout()
    self.language_combo = QComboBox()
    self.language_combo.addItems(list(self.languages.keys()))
    lang_layout.addWidget(self.language_combo)
    lang_group.setLayout(lang_layout)
    top_layout.addWidget(lang_group)

    control_layout.addWidget(top_row)

    # 第二行：文件选择和操作按钮
    bottom_row = QWidget()
    bottom_layout = QHBoxLayout(bottom_row)

    # 文件选择按钮
    self.file_button = QPushButton("选择音频文件")
    self.file_button.clicked.connect(self.select_audio_file)
    bottom_layout.addWidget(self.file_button)

    # 开始识别按钮
    self.recognize_button = QPushButton("开始识别")
    self.recognize_button.clicked.connect(self.start_recognition)
    bottom_layout.addWidget(self.recognize_button)

    # 停止识别按钮
    self.stop_button = QPushButton("停止")
    self.stop_button.setEnabled(False)
    self.stop_button.clicked.connect(self.stop_recognition)
    bottom_layout.addWidget(self.stop_button)

    control_layout.addWidget(bottom_row)

    # 进度条
    progress_row = QWidget()
    progress_layout = QHBoxLayout(progress_row)
    self.progress_bar = QProgressBar()
    self.progress_bar.setRange(0, 100)
    progress_layout.addWidget(self.progress_bar)
    self.status_label = QLabel("准备就绪")
    progress_layout.addWidget(self.status_label)
    control_layout.addWidget(progress_row)

    self.main_layout.addWidget(control_frame)

def create_text_display(self):
    """创建文本显示区域"""
    splitter = QWidget()
    splitter_layout = QHBoxLayout(splitter)

    # 实时识别结果
    self.live_text = QTextEdit()
    self.live_text.setReadOnly(True)
    self.live_text.setPlaceholderText("实时识别结果将显示在这里...")
    splitter_layout.addWidget(self.live_text)

    # 完整识别结果
    self.full_text = QTextEdit()
    self.full_text.setReadOnly(True)
    self.full_text.setPlaceholderText("完整识别结果将显示在这里...")
    splitter_layout.addWidget(self.full_text)

    self.main_layout.addWidget(splitter)

def select_audio_file(self):
    """选择要处理的音频文件"""
    file_path, _ = QFileDialog.getOpenFileName(
        self, "选择音频文件", "",
        ""
    )

    if file_path:
        self.current_audio_file = file_path
        self.status_label.setText(f"已选择文件: {os.path.basename(file_path)}")

def start_recognition(self):
    """开始语音识别过程"""
    if not self.current_audio_file:
        QMessageBox.warning(self, "警告", "请先选择一个音频文件")
        return

    # 禁用开始按钮，启用停止按钮
    self.recognize_button.setEnabled(False)
    self.stop_button.setEnabled(True)

    # 清空结果区域
    self.live_text.clear()
    self.full_text.clear()

    # 获取选择的模型
    selected_model = self.model_combo.currentText()

    # 创建工作线程和工作对象
    self.thread = QThread()
    self.worker = WhisperWorker(selected_model, self.current_audio_file)

    # 将工作对象移到线程中
    self.worker.moveToThread(self.thread)

    # 连接信号和槽
    self.thread.started.connect(self.worker.run)
    self.worker.progress_updated.connect(self.update_progress)
    self.worker.text_segment.connect(self.append_live_text)
    self.worker.task_completed.connect(self.on_task_completed)
    self.worker.error_occurred.connect(self.on_error)
    self.worker.task_started.connect(self.on_task_started)

    # 线程结束时的清理工作
    self.thread.finished.connect(self.thread.deleteLater)
    self.thread.finished.connect(lambda: setattr(self, 'thread', None))
    self.worker.task_completed.connect(self.thread.quit)
    self.worker.task_completed.connect(self.worker.deleteLater)
    self.worker.error_occurred.connect(self.thread.quit)
    self.worker.error_occurred.connect(self.worker.deleteLater)

    # 启动线程
    self.thread.start()

def stop_recognition(self):
    """停止语音识别过程"""
    if self.worker:
        self.worker.stop()
        self.status_label.setText("正在停止...")

@pyqtSlot(int, str)
def update_progress(self, value, message):
    """更新进度条和状态标签"""
    self.progress_bar.setValue(value)
    self.status_label.setText(message)

@pyqtSlot()
def on_task_started(self):
    """任务开始处理"""
    self.statusBar().showMessage("语音识别中...")

@pyqtSlot(str)
def append_live_text(self, text):
    """追加实时识别文本"""
    self.live_text.moveCursor(QTextCursor.End)
    self.live_text.insertPlainText(text)
    self.live_text.moveCursor(QTextCursor.End)

@pyqtSlot(str)
def on_task_completed(self, result):
    """任务完成处理"""
    self.full_text.setPlainText(result)
    self.status_label.setText("识别完成")
    self.statusBar().showMessage("语音识别完成")

    # 恢复按钮状态
    self.recognize_button.setEnabled(True)
    self.stop_button.setEnabled(False)

@pyqtSlot(str)
def on_error(self, error_msg):
    """错误处理"""
    QMessageBox.critical(self, "识别错误", error_msg)
    self.status_label.setText("识别失败")
    self.statusBar().showMessage(f"错误: {error_msg}")

    # 恢复按钮状态
    self.recognize_button.setEnabled(True)
    self.stop_button.setEnabled(False)

def closeEvent(self, event):
    """窗口关闭时清理资源"""
    if self.thread and self.thread.isRunning():
        if self.worker:
            self.worker.stop()
        self.thread.quit()
        self.thread.wait(3000)  # 等待3秒

    event.accept()

if name == "main":
app = QApplication(sys.argv)

# 设置高DPI支持
if hasattr(Qt, 'AA_EnableHighDpiScaling'):
    app.setAttribute(Qt.AA_EnableHighDpiScaling, True)

if hasattr(Qt, 'AA_UseHighDpiPixmaps'):
    app.setAttribute(Qt.AA_UseHighDpiPixmaps, True)

window = SpeechToTextApp()
sys.exit(app.exec_())

[xiao-xiang]

Could you please provide a minimal, reproducible code example that shows the problem?

Sorry, the format of the demo code has changed after pasting, and it needs to be manually adjusted slightly.

[absadiki]

Thanks for sharing your code! But I just asked for a minimal example to reproduce the issue, not your full app. 😅
This helps isolate the problem and makes it easier to test and debug.
Would you mind trimming it down to the smallest version that still causes the issue?

Also, quick note, to format your code you need to wrap it in triple backticks (```python ````).

[xiao-xiang]

I'm sorry, the actual app has tens of thousands of lines of code. The code above is demo code specially generated for your library using AI.

import os
import sys

from PyQt5.QtCore import Qt, QObject, pyqtSignal, QThread, pyqtSlot
from PyQt5.QtGui import QTextCursor
from PyQt5.QtWidgets import QApplication, QMainWindow, QWidget, QVBoxLayout, QHBoxLayout, QGroupBox, QComboBox, \
    QPushButton, QProgressBar, QLabel, QTextEdit, QFileDialog, QMessageBox
from pywhispercpp.model import Model


class WhisperWorker(QObject):
    progress_updated = pyqtSignal(int, str)
    text_segment = pyqtSignal(str)
    task_completed = pyqtSignal(str)
    error_occurred = pyqtSignal(str)
    task_started = pyqtSignal()

    def __init__(self, model_path, audio_path):
        super().__init__()
        self.model_path = model_path
        self.audio_path = audio_path
        self._is_running = True

    def run(self):
        try:
            self.task_started.emit()
            self.progress_updated.emit(0, "正在加载模型...")

            # 初始化模型
            model = Model(
                self.model_path,
                print_progress=True
            )

            self.progress_updated.emit(10, "模型加载完成，开始识别...")

            # 使用回调函数获取实时结果
            full_text = ""

            def segment_callback(segment):
                if not self._is_running:
                    return False  # 停止识别
                text = segment.text
                self.text_segment.emit(text)
                nonlocal full_text
                full_text += text + "\n"
                return True  # 继续识别

            # 执行识别
            model.transcribe(
                self.audio_path
            )

            self.progress_updated.emit(100, "识别完成")
            self.task_completed.emit(full_text)

        except Exception as e:
            self.error_occurred.emit(str(e))

    def stop(self):
        """停止任务执行"""
        self._is_running = False

class SpeechToTextApp(QMainWindow):

    def __init__(self):
        super().__init__()

        # 设置窗口属性
        self.setWindowTitle("高性能语音转文字工具")
        self.setGeometry(100, 100, 1200, 800)

        # 可用模型列表
        self.models = {
            "tiny.en": "ggml-tiny.en.bin",
            "tiny": "ggml-tiny.bin",
            "base.en": "ggml-base.en.bin",
            "base": "ggml-base.bin",
            "small.en": "ggml-small.en.bin",
            "small": "ggml-small.bin",
            "medium.en": "ggml-medium.en.bin",
            "medium": "ggml-medium.bin",
            "large": "ggml-large.bin"
        }

        # 语言列表
        self.languages = {
            "自动检测": None,
            "中文": "zh",
            "英语": "en",
            "日语": "ja",
            "韩语": "ko",
            "法语": "fr",
            "西班牙语": "es",
            "德语": "de",
            "俄语": "ru",
            "葡萄牙语": "pt",
            "意大利语": "it"
        }

        # 创建中心部件和布局
        self.central_widget = QWidget()
        self.setCentralWidget(self.central_widget)
        self.main_layout = QVBoxLayout(self.central_widget)

        # 创建顶部控制面板
        self.create_control_panel()

        # 创建文本显示区域
        self.create_text_display()

        # 创建状态栏
        self.statusBar().showMessage("就绪")

        # 初始化变量
        self.worker = None
        self.thread = None
        self.current_audio_file = None

        # 显示界面
        self.show()

    def create_control_panel(self):
        """创建控制面板"""
        control_frame = QWidget()
        control_layout = QVBoxLayout(control_frame)

        # 第一行：模型选择和文件选择
        top_row = QWidget()
        top_layout = QHBoxLayout(top_row)

        # 模型选择
        model_group = QGroupBox("模型")
        model_layout = QHBoxLayout()
        self.model_combo = QComboBox()
        self.model_combo.addItems(list(self.models.keys()))
        model_layout.addWidget(self.model_combo)
        model_group.setLayout(model_layout)
        top_layout.addWidget(model_group)

        # 语言选择
        lang_group = QGroupBox("语言")
        lang_layout = QHBoxLayout()
        self.language_combo = QComboBox()
        self.language_combo.addItems(list(self.languages.keys()))
        lang_layout.addWidget(self.language_combo)
        lang_group.setLayout(lang_layout)
        top_layout.addWidget(lang_group)

        control_layout.addWidget(top_row)

        # 第二行：文件选择和操作按钮
        bottom_row = QWidget()
        bottom_layout = QHBoxLayout(bottom_row)

        # 文件选择按钮
        self.file_button = QPushButton("选择音频文件")
        self.file_button.clicked.connect(self.select_audio_file)
        bottom_layout.addWidget(self.file_button)

        # 开始识别按钮
        self.recognize_button = QPushButton("开始识别")
        self.recognize_button.clicked.connect(self.start_recognition)
        bottom_layout.addWidget(self.recognize_button)

        # 停止识别按钮
        self.stop_button = QPushButton("停止")
        self.stop_button.setEnabled(False)
        self.stop_button.clicked.connect(self.stop_recognition)
        bottom_layout.addWidget(self.stop_button)

        control_layout.addWidget(bottom_row)

        # 进度条
        progress_row = QWidget()
        progress_layout = QHBoxLayout(progress_row)
        self.progress_bar = QProgressBar()
        self.progress_bar.setRange(0, 100)
        progress_layout.addWidget(self.progress_bar)
        self.status_label = QLabel("准备就绪")
        progress_layout.addWidget(self.status_label)
        control_layout.addWidget(progress_row)

        self.main_layout.addWidget(control_frame)

    def create_text_display(self):
        """创建文本显示区域"""
        splitter = QWidget()
        splitter_layout = QHBoxLayout(splitter)

        # 实时识别结果
        self.live_text = QTextEdit()
        self.live_text.setReadOnly(True)
        self.live_text.setPlaceholderText("实时识别结果将显示在这里...")
        splitter_layout.addWidget(self.live_text)

        # 完整识别结果
        self.full_text = QTextEdit()
        self.full_text.setReadOnly(True)
        self.full_text.setPlaceholderText("完整识别结果将显示在这里...")
        splitter_layout.addWidget(self.full_text)

        self.main_layout.addWidget(splitter)

    def select_audio_file(self):
        """选择要处理的音频文件"""
        file_path, _ = QFileDialog.getOpenFileName(
            self, "选择音频文件", "",
            ""
        )

        if file_path:
            self.current_audio_file = file_path
            self.status_label.setText(f"已选择文件: {os.path.basename(file_path)}")

    def start_recognition(self):
        """开始语音识别过程"""
        if not self.current_audio_file:
            QMessageBox.warning(self, "警告", "请先选择一个音频文件")
            return

        # 禁用开始按钮，启用停止按钮
        self.recognize_button.setEnabled(False)
        self.stop_button.setEnabled(True)

        # 清空结果区域
        self.live_text.clear()
        self.full_text.clear()

        # 获取选择的模型
        selected_model = self.model_combo.currentText()

        # 创建工作线程和工作对象
        self.thread = QThread()
        self.worker = WhisperWorker(selected_model, self.current_audio_file)

        # 将工作对象移到线程中
        self.worker.moveToThread(self.thread)

        # 连接信号和槽
        self.thread.started.connect(self.worker.run)
        self.worker.progress_updated.connect(self.update_progress)
        self.worker.text_segment.connect(self.append_live_text)
        self.worker.task_completed.connect(self.on_task_completed)
        self.worker.error_occurred.connect(self.on_error)
        self.worker.task_started.connect(self.on_task_started)

        # 线程结束时的清理工作
        self.thread.finished.connect(self.thread.deleteLater)
        self.thread.finished.connect(lambda: setattr(self, 'thread', None))
        self.worker.task_completed.connect(self.thread.quit)
        self.worker.task_completed.connect(self.worker.deleteLater)
        self.worker.error_occurred.connect(self.thread.quit)
        self.worker.error_occurred.connect(self.worker.deleteLater)

        # 启动线程
        self.thread.start()

    def stop_recognition(self):
        """停止语音识别过程"""
        if self.worker:
            self.worker.stop()
            self.status_label.setText("正在停止...")

    @pyqtSlot(int, str)
    def update_progress(self, value, message):
        """更新进度条和状态标签"""
        self.progress_bar.setValue(value)
        self.status_label.setText(message)

    @pyqtSlot()
    def on_task_started(self):
        """任务开始处理"""
        self.statusBar().showMessage("语音识别中...")

    @pyqtSlot(str)
    def append_live_text(self, text):
        """追加实时识别文本"""
        self.live_text.moveCursor(QTextCursor.End)
        self.live_text.insertPlainText(text)
        self.live_text.moveCursor(QTextCursor.End)

    @pyqtSlot(str)
    def on_task_completed(self, result):
        """任务完成处理"""
        self.full_text.setPlainText(result)
        self.status_label.setText("识别完成")
        self.statusBar().showMessage("语音识别完成")

        # 恢复按钮状态
        self.recognize_button.setEnabled(True)
        self.stop_button.setEnabled(False)

    @pyqtSlot(str)
    def on_error(self, error_msg):
        """错误处理"""
        QMessageBox.critical(self, "识别错误", error_msg)
        self.status_label.setText("识别失败")
        self.statusBar().showMessage(f"错误: {error_msg}")

        # 恢复按钮状态
        self.recognize_button.setEnabled(True)
        self.stop_button.setEnabled(False)

def closeEvent(self, event):
    """窗口关闭时清理资源"""
    if self.thread and self.thread.isRunning():
        if self.worker:
            self.worker.stop()
        self.thread.quit()
        self.thread.wait(3000)  # 等待3秒

    event.accept()

if __name__ == "__main__":
    app = QApplication(sys.argv)

    # 设置高DPI支持
    if hasattr(Qt, 'AA_EnableHighDpiScaling'):
        app.setAttribute(Qt.AA_EnableHighDpiScaling, True)

    if hasattr(Qt, 'AA_UseHighDpiPixmaps'):
        app.setAttribute(Qt.AA_UseHighDpiPixmaps, True)

    window = SpeechToTextApp()
    sys.exit(app.exec_())

[absadiki]

Thanks for letting me know it was AI-generated, I initially thought the issue was something specific to your app.

I also generated a small GUI using AI and confirmed that the C++ code was indeed blocking the Python thread, which caused the UI to freeze.

I’ve pushed a fix to address this. Could you please pull this branch, test it, and let me know if the UI freeze is resolved?

[xiao-xiang]

Thanks for letting me know it was AI-generated, I initially thought the issue was something specific to your app.

I also generated a small GUI using AI and confirmed that the C++ code was indeed blocking the Python thread, which caused the UI to freeze.

I’ve pushed a fix to address this. Could you please pull this branch, test it, and let me know if the UI freeze is resolved?

Thank you very much. I will test the new branch code later. In addition, regarding FFmpeg, can your library expose parameters to specify the FFmpeg executable? Because similar apps usually include a self-compiled version of FFmpeg. Currently, we need to add our own FFmpeg to the environment variable PATH, which is a bit inconvenient to use.

[absadiki]

I wanted to keep the library's dependencies to a minimum.
In fact, ffmpeg is used merely for convenience and is not required.
You can use your own ffmpeg executable or package it with your application to convert the media file to wav before passing it to the transcribe function.