Striving to be the most comprehensive video playback library for Python.

Note that this library is under active development. If you encounter a bug or a video that cannot be played, please open an issues page.

• Easy to implement (4 lines of code)
• Only essential dependencies are numpy, FFmpeg + FFprobe
• Fast and efficient
• No audio/video sync issues
• Unlocked frame rate
• Nvidia hardware acceleration (AMD coming later)
• Supports GIFs!
• Supports almost any video codec and container
• Play variable frame rate videos (VFR)
• Adjust playback speed
• Reverse playback
• Subtitle support (.srt, .ass, etc)
• Play multiple videos in parallel
• Add multiple subtitles to a video
• Built in GUI and queue system
• Draw videos using Pygame, PygameCE, Pyglet, Tkinter, PySide6, PyQT6, Raylib, or wxPython
• Post process effects
• Webcam feed
• Stream videos from Youtube
• Grab subtitles from Youtube, including automatic generation and translation
• Play videos as byte objects
• Specify output devices
• Frame-by-frame iteration
• Specify different audio tracks
• Seamless video looping

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.

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

numpy
FFmpeg and FFprobe (binaries, not Python packages)

At least one graphics library and one audio library is required.

opencv_python   (efficiency improvements and more features, comes installed)
pygame-ce       (graphics and audio library, comes installed)
sounddevice     (better audio library, comes installed)
pysubs2         (for subtitles, comes installed)
yt_dlp          (for streaming Youtube videos)
decord          (for videos in bytes, best option)
imageio         (for videos in bytes)
av              (required for imageio)
pyglet          (graphics library)
PySide6         (graphics library)
PyQt6           (graphics library)
tkinter         (graphics library, installed as a system 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.

Refer to the examples folder for more basic examples.

from pyvidplayer2 import Video
Video("video.mp4").preview()

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()

To get started quickly, you can browse the many code examples. For more detailed information, read the documentation. If you prefer natural language, try asking DeepWiki. Finally, if you still have questions, open an issues page or email me at anrayliu@gmail.com. I'm more than happy to answer!

For a list of known bugs, refer to this page. If you see an issue not listed, feel free to open a new issue!