pyqt-multimedia

PyQt/PySide Multimedia

Audio and video playback, camera capture, and media recording in PyQt6/PySide6.

Overview

Qt Multimedia provides classes for audio, video, and camera functionality:

QMediaPlayer - Audio/video playback
QVideoWidget - Video display
QAudioOutput - Audio output management
QCamera - Camera capture
QMediaCaptureSession - Camera/recording session management
QMediaRecorder - Audio/video recording
QMediaFormat - Encoding format configuration

Backend by platform:

Linux: GStreamer
Windows: DirectShow/WMF
macOS: AVFoundation

Audio Playback

Basic Audio Player

from PyQt6.QtMultimedia import QMediaPlayer, QAudioOutput
from PyQt6.QtWidgets import QApplication, QPushButton, QVBoxLayout, QWidget, QSlider, QLabel
from PyQt6.QtCore import Qt, QUrl
import sys

class AudioPlayer(QWidget):
    def __init__(self):
        super().__init__()
        self.player = QMediaPlayer()
        self.audio_output = QAudioOutput()
        self.player.setAudioOutput(self.audio_output)
        
        self.play_btn = QPushButton("Play")
        self.volume_slider = QSlider(Qt.Orientation.Horizontal)
        self.volume_slider.setRange(0, 100)
        
        layout = QVBoxLayout()
        layout.addWidget(self.play_btn)
        layout.addWidget(self.volume_slider)
        self.setLayout(layout)
        
        self.play_btn.clicked.connect(self.player.play)
        self.volume_slider.valueChanged.connect(
            lambda v: self.audio_output.setVolume(v / 100)
        )
        
    def load_file(self, filepath):
        self.player.setSource(QUrl.fromLocalFile(filepath))

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = AudioPlayer()
    window.show()
    sys.exit(app.exec())

Video Playback

Video Player with Controls

from PyQt6.QtMultimedia import QMediaPlayer, QAudioOutput
from PyQt6.QtMultimediaWidgets import QVideoWidget
from PyQt6.QtWidgets import (
    QApplication, QWidget, QVBoxLayout, QHBoxLayout,
    QPushButton, QSlider, QLabel
)
from PyQt6.QtCore import Qt, QUrl

class VideoPlayer(QWidget):
    def __init__(self):
        super().__init__()
        self.player = QMediaPlayer()
        self.audio_output = QAudioOutput()
        self.player.setAudioOutput(self.audio_output)
        
        self.video_widget = QVideoWidget()
        self.player.setVideoOutput(self.video_widget)
        
        self.play_btn = QPushButton("Play")
        self.position_slider = QSlider(Qt.Orientation.Horizontal)
        self.time_label = QLabel("00:00 / 00:00")
        
        layout = QVBoxLayout()
        layout.addWidget(self.video_widget)
        layout.addWidget(self.play_btn)
        layout.addWidget(self.position_slider)
        layout.addWidget(self.time_label)
        self.setLayout(layout)
        
        self.play_btn.clicked.connect(self.player.play)
        self.player.positionChanged.connect(self.position_changed)
        self.player.durationChanged.connect(self.duration_changed)
        
    def load_video(self, filepath):
        self.player.setSource(QUrl.fromLocalFile(filepath))
        
    def position_changed(self, position):
        self.position_slider.setValue(position)
        
    def duration_changed(self, duration):
        self.position_slider.setRange(0, duration)

if __name__ == "__main__":
    app = QApplication(sys.argv)
    window = VideoPlayer()
    window.show()
    sys.exit(app.exec())

Key methods:

play(), pause(), stop() - Playback control
setPosition(ms), seek(seconds) - Position control
playbackState() - Returns PlayingState, PausedState, or StoppedState

Camera Capture

Camera Viewer

from PyQt6.QtMultimedia import QCamera, QMediaDevices
from PyQt6.QtMultimediaWidgets import QVideoWidget
from PyQt6.QtWidgets import QApplication, QWidget, QVBoxLayout, QPushButton

class CameraViewer(QWidget):
    def __init__(self):
        super().__init__()
        cameras = QMediaDevices.videoInputs()
        if not cameras:
            print("No cameras available")
            return
            
        self.camera = QCamera(cameras[0])
        self.video_widget = QVideoWidget()
        
        layout = QVBoxLayout()
        layout.addWidget(self.video_widget)
        self.setLayout(layout)
        
        self.camera.setVideoOutput(self.video_widget)
        self.camera.start()
        
    def closeEvent(self, event):
        self.camera.stop()
        super().closeEvent(event)

Photo Capture with QMediaCaptureSession

from PyQt6.QtMultimedia import QCamera, QMediaCaptureSession, QImageCapture
from PyQt6.QtMultimediaWidgets import QVideoWidget
from PyQt6.QtWidgets import QWidget, QVBoxLayout, QPushButton

class CameraCapture(QWidget):
    def __init__(self):
        super().__init__()
        self.camera = QCamera()
        self.capture_session = QMediaCaptureSession()
        self.capture_session.setCamera(self.camera)
        
        self.video_widget = QVideoWidget()
        self.capture_session.setVideoOutput(self.video_widget)
        
        self.image_capture = QImageCapture()
        self.capture_session.setImageCapture(self.image_capture)
        
        self.capture_btn = QPushButton("Capture Photo")
        self.capture_btn.clicked.connect(self.capture_photo)
        
        layout = QVBoxLayout()
        layout.addWidget(self.video_widget)
        layout.addWidget(self.capture_btn)
        self.setLayout(layout)
        
        self.camera.start()
        
    def capture_photo(self):
        self.image_capture.captureToFile()

Audio/Video Recording

Media Recorder

from PyQt6.QtMultimedia import QCamera, QMediaCaptureSession, QMediaRecorder
from PyQt6.QtMultimediaWidgets import QVideoWidget
from PyQt6.QtWidgets import QWidget, QVBoxLayout, QPushButton, QLabel
from PyQt6.QtCore import QUrl

class MediaRecorder(QWidget):
    def __init__(self):
        super().__init__()
        self.camera = QCamera()
        self.capture_session = QMediaCaptureSession()
        self.capture_session.setCamera(self.camera)
        
        self.video_widget = QVideoWidget()
        self.capture_session.setVideoOutput(self.video_widget)
        
        self.recorder = QMediaRecorder()
        self.capture_session.setRecorder(self.recorder)
        
        self.record_btn = QPushButton("Start Recording")
        self.status_label = QLabel("Ready")
        
        layout = QVBoxLayout()
        layout.addWidget(self.video_widget)
        layout.addWidget(self.record_btn)
        layout.addWidget(self.status_label)
        self.setLayout(layout)
        
        self.record_btn.clicked.connect(self.toggle_recording)
        self.recorder.recorderStateChanged.connect(self.update_status)
        
    def toggle_recording(self):
        if self.recorder.recorderState() == QMediaRecorder.RecorderState.RecordingState:
            self.recorder.stop()
        else:
            self.recorder.setOutputLocation(QUrl.fromLocalFile("output.mp4"))
            self.recorder.record()
            
    def update_status(self, state):
        states = {
            QMediaRecorder.RecorderState.StoppedState: "Stopped",
            QMediaRecorder.RecorderState.RecordingState: "Recording",
            QMediaRecorder.RecorderState.PausedState: "Paused"
        }
        self.status_label.setText(states.get(state, "Unknown"))

GStreamer Backend (Linux)

# Ubuntu/Debian - core plugins
sudo apt-get install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev \
    gstreamer1.0-plugins-good gstreamer1.0-plugins-bad gstreamer1.0-plugins-ugly

# Additional codec support
sudo apt-get install gstreamer1.0-libav

Common Issues

Issue	Solution
No audio/video output	Check `QMediaDevices.audioOutputs()` and `videoOutputs()`
No cameras found	Check `QMediaDevices.videoInputs()`
Format not supported	Install codec pack (Windows) or GStreamer plugins (Linux)
Playback fails	Check `player.error()` for specific error code

Best Practices

# ✅ Check device availability first
from PyQt6.QtMultimedia import QMediaDevices
if not QMediaDevices.audioInputs():
    print("No microphone available")

# ✅ Set output location before recording
recorder.setOutputLocation(QUrl.fromLocalFile(path))
recorder.record()

# ✅ Clean up on close
def closeEvent(self, event):
    self.camera.stop()
    self.recorder.stop()
    super().closeEvent(event)

Deep Dives

For detailed implementations, see the reference files:

Media Pipeline (references/media-pipeline.md) - QMediaPlayer + QVideoWidget, QCamera + QMediaCaptureSession, QMediaRecorder setup
Codecs & Platforms (references/codecs-platforms.md) - Platform-specific codec support, installation guides, format compatibility

References

Qt Multimedia: https://doc.qt.io/qt-6/qtmultimedia-index.html
PySide6 Multimedia: https://doc.qt.io/qt-6/multimedia.html
GStreamer: https://gstreamer.freedesktop.org/