Comprehensive video playback library for Python.
This library is under active development. If you encounter a bug or a video that cannot be played, please open an issues page.
- 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
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)
Still requires one graphics library and one audio library of your choice.
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.
Refer to the examples folder for more basic examples.
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. If you still have questions, open an issues page.
For a list of known bugs, refer to this page. If you see an issue not listed, please open a new issue.