pyvidplayer2

Featureful library for embedding videos into Python apps.

The latest version (v0.9.37) is a release candidate. This project currently uses pre-1.0 versioning in the form of 0.9.x. After v1.0, it will follow standard Semantic Versioning.

Features

• Easy integration: Add a video to an existing app with just 4 lines of code
• Lightweight: Almost every dependency is optional
• Feature-rich: Seamless loops, custom playback speed, reverse playback, parallel playback, and more
• Full audio support: Adjust audio track, output device, volume, and more
• Full subtitle support: Parse subtitles from files or embedded subtitle tracks
• Play any format: Supports almost every codec and container, VFR videos, even GIFs
• YouTube integration: Stream videos and subtitles directly from YouTube
• Low-level control: Frame-by-frame iteration and inspection
• High compatibility: Integrates with 7 graphics libraries (some features limited to Pygame)
• Extra features: Built-in video player GUI, post-processing effects, and webcam features

Installation

pip install pyvidplayer2

In addition, FFmpeg and FFprobe must be downloaded and accessible via PATH. Windows users can go to the official website to download FFmpeg (includes FFprobe). Add the bin folder location to the PATH environment variable. There's plenty of tutorials online for this. Linux and MacOS users can use their package manager of choice.

Legacy Installations

Versions prior to v0.9.31 have a PyAudio dependency. To build the wheel for it, some system packages must be present. Install them with your package manager before running pip install pyvidplayer2.

• Ubuntu/Debian: sudo apt install python3-dev libjack-jackd2-dev portaudio19-dev
• Fedora/RHEL: sudo dnf install python3-devel portaudio-devel
• MacOS: brew install portaudio

Dependencies

numpy
FFmpeg and FFprobe (binaries, not Python packages)

Still requires one graphics library and one audio library of your choice.

Optional Packages

opencv_python       (efficiency improvements and more features, comes installed)
pygame/pygame-ce    (graphics and audio library)
sounddevice         (better audio library, comes installed)
pysubs2             (for subtitles)
yt_dlp[default]     (for streaming Youtube videos)
decord              (for videos in bytes, best option)
imageio[pyav]       (for videos in bytes)
pyglet              (graphics library)
PySide6             (graphics library)
PyQt6               (graphics library)
tkinter             (graphics library, installed as a sys package or with Python installer, not pip)
raylib              (graphics library)
wxPython            (graphics library)

Use pip install pyvidplayer2[all] to install all packages required for running the unit tests. Not required or recommended for regular users.

Documentation

Refer to this page for detailed information. To get started quickly, you can browse the many code examples. If you prefer natural language, try asking DeepWiki. If you still have questions, open an issues page.

Quickstart

Refer to the examples folder for more basic examples.

Pygame Integration

Refer to the examples folder for integrations with other graphics libraries.

import pygame
from pyvidplayer2 import Video


# Create video object

vid = Video("video.mp4")

win = pygame.display.set_mode(vid.current_size)
pygame.display.set_caption(vid.name)


while vid.active:
    key = None
    for event in pygame.event.get():
        if event.type == pygame.QUIT:
            vid.stop()
        elif event.type == pygame.KEYDOWN:
            key = pygame.key.name(event.key)

    if key == "r":
        vid.restart()           # Rewind video to beginning
    elif key == "p":
        vid.toggle_pause()      # Pause/play video
    elif key == "m":
        vid.toggle_mute()       # Mute/unmute video
    elif key == "right":
        vid.seek(15)            # Skip 15 seconds in video
    elif key == "left":
        vid.seek(-15)           # Rewind 15 seconds in video
    elif key == "up":
        vid.set_volume(1.0)     # Max volume
    elif key == "down":
        vid.set_volume(0.0)     # Min volume

    # Only draw new frames, and only update the screen if something is drawn

    if vid.draw(win, (0, 0), force_draw=False):
        pygame.display.update()

    pygame.time.wait(16)


# Close video when done

vid.close()
pygame.quit()