[](http://pepy.tech/project/pyvidplayer2)
# pyvidplayer2 (please report all bugs!)
Languages: English | [中文](https://github.com/anrayliu/pyvidplayer2/blob/main/README.cn.md)
Introducing pyvidplayer2, the successor to pyvidplayer. It's better in
pretty much every way, and finally allows an easy and reliable way to play videos in Python.
All the features from the original library have been ported over, with the exception of `alt_resize()`. Since pyvidplayer2 has a completely revamped foundation, the unreliability of `set_size()` has been quashed, and a fallback function is now redundant.
# Features (see examples folder)
- Easy to implement (4 lines of code)
- Very little dependencies (cv2 is optional!)
- Fast and reliable
- Low CPU usage
- No audio/video sync issues
- Unlocked frame rate
- Can play a huge variety of video formats
- Play variable frame rate videos (VFR)
- Adjust playback speed
- Reverse playback
- Subtitle support (.srt, .ass, etc)
- Play multiple videos in parallel
- Built in GUI and queue system
- Support for Pygame, PygameCE, Pyglet, Tkinter, PySide6 and PyQT6
- Post process effects
- Webcam feed
- Stream videos from Youtube
- Play videos from memory
- Specify which audio devices to use
- Frame-by-frame iteration
# Installation
## Windows
```
pip install pyvidplayer2
```
Note: FFMPEG (just the essentials is fine) must be installed and accessible via the system PATH. Here's an online article on how to do this (windows):
https://phoenixnap.com/kb/ffmpeg-windows.
FFPROBE may also be needed for certain features - this should come bundled with with FFMPEG download.
## Linux
Before running `pip install pyvidplayer2`, you must first install the required development packages.
- Ubuntu/Debian example: `sudo apt install build-essential python3-dev portaudio19-dev libjack-jackd2-dev`
- The Python and PortAudio development packages prevent missing Python.h and missing portaudio.h errors, respectively.
- Installing `libjack-jackd2-dev` manually prevents `portaudio19-dev` from downgrading to libjack0 and removing wine etc (<https://bugs.launchpad.net/ubuntu/+source/portaudio19/+bug/132002>).
- In some circumstances, such as if you are using the kxstudio repo with Linux Mint, incompatible packages may be removed (See <https://github.com/anrayliu/pyvidplayer2/issues/36> for the latest updates on this issue):
```
The following additional packages will be installed:
libjack-dev libjack0 libportaudiocpp0
Suggested packages:
jackd1 portaudio19-doc
The following packages will be REMOVED:
libasound2-plugins:i386 libjack-jackd2-0 libjack-jackd2-0:i386 wine-stable wine-stable-i386:i386 winehq-stable
The following NEW packages will be installed:
libjack-dev libjack0 libportaudiocpp0 portaudio19-dev
```
# Dependencies
```
numpy
FFmpeg and FFprobe (not a Python package)
```
## Optional Packages
```
opencv_python (comes installed for all-around improvements)
pygame (graphics and audio library, comes installed)
PyAudio (audio library, comes installed)
pysubs2 (for subtitles, comes installed)
yt_dlp (for streaming Youtube videos)
imageio (for videos in bytes)
pyglet (graphics library)
PySide6 (graphics library)
PyQt6 (graphics library)
```
# Quickstart
Refer to the examples folder for more basic guides, and documentation.md contains more detailed information.
## Super Quick Demo
```
from pyvidplayer2 import Video
Video("video.mp4").preview()
```
## Pygame Integration
```
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/plays video
elif key == "m":
vid.toggle_mute() #mutes/unmutes 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) # around 60 fps
# close video when done
vid.close()
pygame.quit()
```
# Known Bugs (as of v0.9.24)
- Youtube videos will sometimes freeze or stutter (rare)
- Video seeking is slow when reading from bytes
- Rotated videos when playing from bytes will appear in their original direction
# Documentation
Documentation also available in repository as documentation.md.
# Video(path, chunk_size=10, max_threads=1, max_chunks=1, subs=None, post_process=PostProcessing.none, interp="linear", use_pygame_audio=False, reverse=False, no_audio=False, speed=1, youtube=False, max_res=1080, as_bytes=False, audio_track=0, vfr=False, pref_lang="en", audio_index=None)
Main object used to play videos. Videos can be read from disk, memory or streamed from Youtube. The object uses FFMPEG to extract chunks of audio from videos and then feeds it into a Pyaudio stream. It uses OpenCV to display the appropriate video frames. Videos can only be played simultaneously if they're using Pyaudio (see `use_pygame_audio` below). Pygame or Pygame CE are the only graphics libraries to support subtitles. YTDLP is required to stream videos from Youtube. IMAGEIO and PyAV are required to play videos from memory. This particular object uses Pygame for graphics, but see bottom for other supported libraries. Actual class name is `VideoPygame`.
## Parameters
- `path: str | bytes` - Path to video file. Supports almost all file types such as mkv, mp4, mov, avi, 3gp, etc. Can also provide the video in bytes (see `as_bytes` below). If streaming from Youtube (see `youtube` below), provide the URL here.
- `chunk_size: float` - How much audio is extracted at a time, in seconds. Increasing this value will slow the initial loading of video, but is necessary to prevent stuttering. Recommended to keep over 60 if streaming from Youtube (see `youtube` below).
- `max_threads: int` - Maximum number of chunks that can be extracted at any given time. Do not change if streaming from Youtube (see `youtube` below).
- `max_chunks: int` - Maximum number of chunks allowed to be extracted and reserved. Do not change if streaming from Youtube (see `youtube` below).
- `subs: pyvidplayer2.Subtitles` - Pass a `Subtitles` object here for the video to display subtitles.
- `post_process: function(numpy.ndarray) -> numpy.ndarray` - Post processing function that is applied whenever a frame is rendered. This is PostProcessing.none by default, which means no alterations are taking place. Post processing functions should accept a NumpPy image (see `frame_data` below) and return the processed image.
- `interp: str | int` - Interpolation technique used when resizing frames with OpenCV. Does nothing if OpenCv is not installed. Accepts `"nearest"`, `"linear"`, `"cubic"`, `"lanczos4"` and `"area"`. Nearest is the fastest technique but produces the worst results. Lanczos4 produces the best results but is so much more intensive that it's usually not worth it. Area is a technique that produces the best results when downscaling. This parameter can also accept OpenCV constants as in `cv2.INTER_LINEAR`.
- `use_pygame_audio: bool` - Specifies whether to use Pyaudio or Pygame to play audio. Pyaudio is almost always the best option, so this is mostly obsolete. Using Pygame audio will not allow videos to be played in parallel.
- `reverse: bool` - Specifies whether to play the video in reverse. Warning: Doing so will load every video frame into memory, so videos longer than a few minutes can temporarily brick your computer. Subtitles are currently unaffected by reverse playback.
- `no_audio: bool` - Specifies whether the given video has no audio tracks. Setting this to `True` can also be used to disable all existing audio tracks.
- `speed: float | int` - Float from 0.5 to 10.0 that multiplies the playback speed. Note that if for example, speed=2, the video will play twice as fast. However, every single video frame will still be processed. Therefore, the frame rate of your program must be at least twice that of the video's frame rate to prevent dropped frames. So for example, for a 24 fps video, the video will have to be updated (see `draw` below) at least, but ideally more than 48 times a second to achieve true x2 speed.
- `youtube: bool` - Specifies whether to stream a Youtube video. Path must be a valid Youtube video URL. The python packages yt_dlp and opencv-python are required for this feature. They can be installed through pip. Setting this to `True` will force `chunk_size` to be at least 60 and `max_threads` to be 1. Cannot play active livestreams.
- `max_res: int` - Only used when streaming Youtube videos. Sets the highest possible resolution when choosing video quality. 4320p is the highest Youtube supports. Note that actual video quality is not guaranteed to match `max_res`.
- `as_bytes: bool` - Specifies whether `path` is a video in byte form. The python packages imageio and av are required for this feature. It can be installed through pip.
- `audio_track: int` - Selects which audio track to use. 0 will play the first, 1 will play the second, and so on.
- `vfr: bool` - Used to play variable frame rate videos properly. If `False`, a constant frame rate will be assumed. If `True`, presentation timestamps will be extracted for each frame (see `timestamps` below). This still works for constant frame rate videos, but extracting the timestamps will mean a longer initial load.
- `pref_lang: str` - Only used when streaming Youtube videos. Used to select a language track if video has multiple.
- `audio_index: int` - Used to specify which audio output device to use. Can be specific to each video, and is automatically calculated if argument is not provided. To get a list of devices and their indices, use libraries like sounddevice (see audio_devices_demo.py in examples folder).
## Attributes
- `path: str | bytes` - Same as given argument.
- `name: str` - Name of file without the directory and extension. Will be an empty string if video is given in byte form (see `as_bytes` above).
- `ext: str` - Type of video (mp4, mkv, mov, etc). Will be `"webm"` if streaming from Youtube (see `youtube` above). Will be an empty string if video is given in byte form (see `as_bytes` above).
- `frame: int` - Current frame index. Starts from 0.
- `frame_rate: float` - Float that indicates how many frames are in one second.
- `max_fr: float` - Only used if `vfr = True`. Gives the maximum frame rate throughout the video.
- `min_fr: float` - Only used if `vfr = True`. Gives the minimum frame rate throughout the video.
- `avg_fr: float` - Only used if `vfr = True`. Gives the average frame rate of all the extracted presentation timestamps.
- `timestamps: [float]` - List of presentation timestamps for each frame.
- `frame_count: int` - How many total frames there are. May not be 100% accurate. For a more accurate (but slower) frame count,set `vfr = True` and use `len(video.timestamps)`.
- `frame_delay: float` - Time between frames in order to maintain frame rate (in fractions of a second).
- `duration: float` - Length of video in seconds.
- `original_size: (int, int)` - Tuple containing the width and height of each original frame. Unaffected by resizing.
- `current_size: (int, int)` - Tuple containing the width and height of each frame being rendered. Affected by resizing.
- `aspect_ratio: float` - Width divided by height of original size.
- `chunk_size: float` - Same as given argument. May change if `youtube` is `True` (see `youtube` above).
- `max_chunks: int` - Same as given argument.
- `max_threads: int` - Same as given argument. May change if `youtube` is `True` (see `youtube` above).
- `frame_data: numpy.ndarray` - Current video frame as a NumPy `ndarray`.
- `frame_surf: pygame.Surface` - Current video frame as a Pygame `Surface`.
- `active: bool` - Whether the video is currently playing. This is unaffected by pausing and resuming.
- `buffering: bool` - Whether the video is waiting for audio to extract.
- `paused: bool`
- `volume: float`
- `muted: bool`
- `speed: float | int` - Same as given argument.
- `subs: pyvidplayer2.Subtitles` - Same as given argument.
- `post_func: function(numpy.ndarray) -> numpy.ndarray` - Same as given argument. Can be changed with `set_post_func`.
- `interp: int` - Same as given argument. Can be changed with `set_interp`. Will be converted to an integer if given a string. For example, if `"linear"` is given during initialization, this will be converted to cv2.INTER_LINEAR.
- `use_pygame_audio: bool` - Same as given argument. May be automatically set to default sound backend.
- `reverse: bool` - Same as given argument.
- `no_audio: bool` - Same as given argument. May change if no audio is automatically detected.
- `youtube: bool` - Same as given argument.
- `max_res: int` - Same as given argument.
- `as_bytes: bool` - Same as given argument. May change if bytes are automatically detected.
- `audio_track: int` - Same as given argument.
- `vfr: bool` - Same as given argument.
- `pref_lang: str` - Same as given argument.
- `audio_index: int` - Same as given argument.
## Methods
- `play() -> None` - Sets `active` to `True`.
- `stop() -> None` - Resets video and sets `active` to `False`.
- `resize(size: (int, int)) -> None`
- `change_resolution(height: int) -> None` - Given a height, the video will scale it's dimensions while maintaining aspect ratio.
- `close() -> None` - Releases resources. Always recommended to call when done.
- `restart() -> None`
- `get_speed() -> float | int`
- `set_volume(volume: float) -> None` - Adjusts the volume of the video, from 0.0 (min) to 1.0 (max).
- `get_volume() -> float`
- `get_paused() -> bool`
- `toggle_pause() -> None` - Pauses if the video is playing, and resumes if the video is paused.
- `pause() -> None`
- `resume() -> None`
- `set_audio_path(index: int)` - Sets the audio track used (see `audio_track` above).
- `toggle_mute() -> None`
- `mute() -> None`
- `unmute() -> None`
- `set_interp(interp: str | int) -> None` - Changes the interpolation technique that OpenCV uses. Works the same as the `interp` parameter (see `interp` above). Does nothing if OpenCV is not installed.
- `set_post_func(func: function(numpy.ndarray) -> numpy.ndarray) -> None` - Changes the post processing function. Works the same as the `post_func` parameter (see `post_func` above).
- `get_pos(): float` - Returns the current position in seconds.
- `seek(time: float | int, relative: bool = True) -> None` - Changes the current position in the video. If relative is `True`, the given time will be added or subtracted to the current time. Otherwise, the current position will be set to the given time exactly. Time must be given in seconds, and seeking will be accurate to one hundredth of a second. Note that
frames and audio within the video will not yet be updated after calling seek.
- `seek_frame(index: int, relative: bool = False) -> None` - Same as `seek` but seeks to a specific frame instead of a time stamp. For example, index 0 will seek to the first frame, index 1 will seek to the second frame, and so on.
- `update() -> bool` - Allows video to perform required operations. `draw` already calls this method, so it's usually not used. Returns `True` if a new frame is ready to be displayed.
- `draw(surf: pygame.Surface, pos: (int, int), force_draw: bool = True) -> bool` - Draws the current video frame onto the given surface, at the given position. If `force_draw` is `True`, a surface will be drawn every time this is called. Otherwise, only new frames will be drawn. This reduces CPU usage but will cause flickering if anything is drawn under or above the video. This method also returns whether a frame was drawn.
- `preview(show_fps: bool = False, max_fps: int = 60) -> None` - Opens a window and plays the video. This method will hang until the video finishes. `max_fps` enforces how many times a second the video is updated. If `show_fps` is `True`, a counter will be displayed showing the actual number of new frames being rendered every second.
## Supported Graphics Libraries
- Pygame or Pygame CE (`Video`) <- default and best supported
- Tkinter (`VideoTkinter`)
- Pyglet (`VideoPyglet`)
- PySide6 (`VideoPySide`)
- PyQT6 (`VideoPyQT`)
To use other libraries instead of Pygame, use their respective video object. Each preview method will use their respective graphics API to create a window and draw frames. See the examples folder for details. Note that `Subtitles`, `Webcam`, and `VideoPlayer` only work with Pygame installed. Preview methods for other graphics libraries also do not accept any arguments.
## As a Generator
Video objects can be iterated through as a generator, returning each subsequent frame. Frames will be given in reverse if video is reversed, and post processing and resizing will still take place. After iterating through frames, `play()` will resume the video from where the last frame left off. Returned frames will be in BGR format.
```
for frame in Video("example.mp4"):
print(frame)
```
## In a Context Manager
Video objects can also be opened using context managers which will automatically call `close()` (see `close()` above) when out of use.
```
with Video("example.mp4") as vid:
vid.preview()
```
# VideoPlayer(video, rect, interactable=False, loop=False, preview_thumbnails=0, font_size=10)
VideoPlayers are GUI containers for videos. They are useful for scaling a video to fit an area or looping videos. Only supported for Pygame.
## Parameters
- `video: pyvidplayer2.VideoPygame` - Video object to play.
- `rect: (int, int, int, int)` - An x, y, width, and height of the VideoPlayer. The top left corner will be the x, y coordinate.
- `interactable: bool` - Enables the GUI.
- `loop: bool` - Specifies whether the contained video will restart after it finishes. If the queue is not empty, the entire queue will loop, not just the current video.
- `preview_thumbnails: int` - Number of preview thumbnails loaded and saved in memory. When seeking, a preview window will show the closest loaded frame. The higher this number is, the more frames are loaded, increasing the preview accuracy but also increasing initial load time and memory usage. Because of this, this value is defaulted to 0, which turns seek previewing off.
- `font_size: int` - Sets font size for GUI elements.
## Attributes
- `video: pyvidplayer2.VideoPygame` - Same as given argument.
- `frame_rect: (int, int, int, int)` - Same as given argument.
- `vid_rect: (int, int, int, int)` - Location and dimensions (x, y, width, height) of the video fitted into `frame_rect` while maintaining aspect ratio. Black bars will appear in any unused space.
- `interactable: bool` - Same as given argument.
- `loop: bool` - Same as given argument.
- `queue_: list[pyvidplayer2.VideoPygame | str]` - Videos to play after the current one finishes.
- `preview_thumbnails: int` - Same as given argument.
## Methods
- `zoom_to_fill() -> None` - Zooms in the video so that `frame_rect` is entirely filled in while maintaining aspect ratio.
- `zoom_out() -> None` - Reverts `zoom_to_fill()`.
- `toggle_zoom() -> None` - Switches between zoomed in and zoomed out.
- `queue(input: pyvidplayer2.VideoPygame | str) -> None` - Accepts a path to a video or a Video object and adds it to the queue. Passing a path will not load the video until it becomes the active video. Passing a Video object will cause it to silently load its first audio chunk, so changing videos will be as seamless as possible.
- `get_queue(): list[pyvidplayer2.VideoPygame]` - Returns list of queued video objects.
- `resize(size: (int, int)) -> None` - Resizes the video player. The contained video will automatically readjust to fit the player.
- `move(pos: (int, int), relative: bool = False) -> None` - Moves the VideoPlayer. If `relative` is `True`, the given coordinates will be added onto the current coordinates. Otherwise, the current coordinates will be set to the given coordinates.
- `update(events: list[pygame.event.Event], show_ui: bool = None, fps: int = 0) -> bool` - Allows the VideoPlayer to make calculations. It must be given the returns of `pygame.event.get()`. The GUI automatically shows up when your mouse hovers over the video player, so setting `show_ui` to `False` can be used to override that. The `fps` parameter can enforce be used to enforce a frame rate to your app. This method also returns whether the UI was shown.
- `draw(surface: pygame.Surface) -> None` - Draws the VideoPlayer onto the given Pygame surface.
- `close() -> None` - Releases resources. Always recommended to call when done.
- `skip() -> None` - Moves onto the next video in the queue.
- `get_video() -> pyvidplayer2.VideoPygame` - Returns currently playing video.
# Subtitles(path, colour="white", highlight=(0, 0, 0, 128), font=pygame.font.SysFont("arial", 30), encoding="utf-8-sig", offset=50, delay=0)
Object used for handling subtitles. Only supported for Pygame.
## Parameters
- `path: str` - Path to subtitle file. This can be any file pysubs2 can read including .srt, .ass, .vtt, and others.
- `colour: str | (int, int, int)` - Colour of text as an RGB value or a string recognized by Pygame.
- `highlight: str | (int, int, int, int)` - Background colour of text. Accepts RGBA, so it can be made completely transparent.
- `font: pygame.font.Font | pygame.font.SysFont` - Pygame `Font` or `SysFont` object used to render surfaces. This includes the size of the text.
- `encoding: str` - Encoding used to open subtitle files.
- `offset: float` - The higher this number is, the closer the subtitle is to the top of the screen.
- `delay: float` - Delays all subtitles by this many seconds.
## Attributes
- `path: str` - Same as given argument.
- `encoding: str` - Same as given argument.
- `start: float` - Starting timestamp of current subtitle.
- `end: float` - Ending timestamp of current subtitle.
- `text: str` - Current subtitle text.
- `surf: pygame.Surface` - Current text in a Pygame `Surface`.
- `colour: str | (int, int, int)` - Same as given argument.
- `highlight: str | (int, int, int, int)` - Same as given argument.
- `font: pygame.font.Font | pygame.font.SysFont` - Same as given argument.
- `offset: float` - Same as given argument.
- `delay: float` - Same as given argument.
## Methods
- `set_font(font: pygame.font.Font | pygame.font.SysFont) -> None` - Same as `font` parameter (see `font` above).
- `get_font() -> pygame.font.Font | pygame.font.SysFont`
# Webcam(post_process=PostProcessing.none, interp="linear", fps=30, cam_id=0)
Object used for displaying a webcam feed. Only supported for Pygame.
## Parameters
- `post_process: function(numpy.ndarray) -> numpy.ndarray` - Post processing function that is applied whenever a frame is rendered. This is PostProcessing.none by default, which means no alterations are taking place. Post processing functions should accept a NumpPy image (see `frame_data` below) and return the processed image.
- `interp: str | int` - Interpolation technique used by OpenCV when resizing frames. Does nothing if OpenCV is not installed. Accepts `"nearest"`, `"linear"`, `"cubic"`, `"lanczos4"` and `"area"`. Nearest is the fastest technique but produces the worst results. Lanczos4 produces the best results but is so much more intensive that it's usually not worth it. Area is a technique that produces the best results when downscaling. This parameter can also accept OpenCV constants as in `cv2.INTER_LINEAR`.
- `fps: int` - Maximum number of frames captured from the webcam per second.
- `cam_id: int` - Specifies which webcam to use if there are more than one. 0 means the first, 1 means the second, and so on.
## Attributes
- `post_process: function(numpy.ndarray) -> numpy.ndarray` - Same as given argument.
- `interp: int` - Same as given argument.
- `fps: int` - Same as given argument.
- `original_size: (int, int)` - Tuple containing the width and height of each frame captured. Unaffected by resizing.
- `current_size: (int, int)` - Tuple containing the width and height of each frame being rendered. Affected by resizing.
- `aspect_ratio: float` - Width divided by height of original size.
- `active: bool` - Whether the webcam is currently playing.
- `frame_data: numpy.ndarray` - Current video frame as a NumPy `ndarray`. Will be in BGR format.
- `frame_surf: pygame.Surface` - Current video frame as a Pygame `Surface`.
- `cam_id: int` - Same as given argument.
## Methods
- `play() -> None`
- `stop() -> None`
- `resize(size: (int, int)) -> None`
- `change_resolution(height: int) -> None` - Given a height, the video will scale its width while maintaining aspect ratio.
- `set_interp(interp: str | int) -> None` - Changes the interpolation technique that OpenCV uses. Works the same as the `interp` parameter (see `interp` above). Does nothing if OpenCV is not installed.
- `set_post_func(func: function(numpy.ndarray) -> numpy.ndarray) -> None` - Changes the post processing function. Works the same as the `post_func` parameter (see `post_func` above).
- `close() -> None` - Releases resources. Always recommended to call when done.
- `get_pos() -> float` - Returns how long the webcam has been active. Is not reset if webcam is stopped.
- `update() -> bool` - Allows webcam to perform required operations. `draw` already calls this method, so it's usually not used. Returns `True` if a new frame is ready to be displayed.
- `draw(surf: pygame.Surface, pos: (int, int), force_draw: bool = True) -> bool` - Draws the current video frame onto the given surface, at the given position. If `force_draw` is `True`, a surface will be drawn every time this is called. Otherwise, only new frames will be drawn. This reduces CPU usage but will cause flickering if anything is drawn under or above the video. This method also returns whether a frame was drawn.
- `preview() -> None` - Opens a window and plays the webcam. This method will hang until the window is closed. Videos are played at whatever fps the webcam object is set to.
# PostProcessing
Used to apply various filters to video playback. Mostly for fun. Works across all graphics libraries. Requires OpenCV.
- `none` - Default. Nothing happens.
- `blur` - Slightly blurs frames.
- `sharpen` - An okay-looking sharpen. Looks pretty bad for small resolutions.
- `greyscale` - Removes colour from frame.
- `noise` - Adds a static-like filter. Very resource intensive.
- `letterbox` - Adds black bars above and below the frame to look more cinematic.
- `cel_shading` - Thickens borders for a comic book style filter.
# Misc
```
print(pyvidplayer2.get_version_info())
```
Returns a dictionary with the version of pyvidplayer2, FFMPEG, and Pygame. Version can also be accessed directly
with `pyvidplayer2._version.__version__` or `pyvidplayer2.VERSION`.
When there are no suitable exceptions, `pyvidplayer2.Pyvidplayer2Error` may be raised.
Raw data
{
"_id": null,
"home_page": "https://github.com/anrayliu/pyvidplayer2",
"name": "pyvidplayer2",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "pygame, video, playback, tkinter, pyqt, pyside, pyglet",
"author": "Anray Liu",
"author_email": "Anray Liu <anrayliu@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/0f/97/91f2bd6c465371ccc1453323956571a5cbc1faa03f14ce0bdce058bb32b7/pyvidplayer2-0.9.24.tar.gz",
"platform": "windows",
"description": "[](http://pepy.tech/project/pyvidplayer2)\r\n\r\n# pyvidplayer2 (please report all bugs!)\r\nLanguages: English | [\u4e2d\u6587](https://github.com/anrayliu/pyvidplayer2/blob/main/README.cn.md)\r\n\r\n\r\nIntroducing pyvidplayer2, the successor to pyvidplayer. It's better in\r\npretty much every way, and finally allows an easy and reliable way to play videos in Python.\r\n\r\nAll the features from the original library have been ported over, with the exception of `alt_resize()`. Since pyvidplayer2 has a completely revamped foundation, the unreliability of `set_size()` has been quashed, and a fallback function is now redundant.\r\n\r\n# Features (see examples folder)\r\n- Easy to implement (4 lines of code)\r\n- Very little dependencies (cv2 is optional!)\r\n- Fast and reliable\r\n- Low CPU usage\r\n- No audio/video sync issues\r\n- Unlocked frame rate\r\n- Can play a huge variety of video formats\r\n- Play variable frame rate videos (VFR)\r\n- Adjust playback speed\r\n- Reverse playback\r\n- Subtitle support (.srt, .ass, etc)\r\n- Play multiple videos in parallel\r\n- Built in GUI and queue system\r\n- Support for Pygame, PygameCE, Pyglet, Tkinter, PySide6 and PyQT6\r\n- Post process effects\r\n- Webcam feed\r\n- Stream videos from Youtube\r\n- Play videos from memory\r\n- Specify which audio devices to use\r\n- Frame-by-frame iteration\r\n\r\n# Installation\r\n\r\n## Windows\r\n```\r\npip install pyvidplayer2\r\n```\r\nNote: FFMPEG (just the essentials is fine) must be installed and accessible via the system PATH. Here's an online article on how to do this (windows):\r\nhttps://phoenixnap.com/kb/ffmpeg-windows.\r\nFFPROBE may also be needed for certain features - this should come bundled with with FFMPEG download.\r\n\r\n## Linux\r\nBefore running `pip install pyvidplayer2`, you must first install the required development packages.\r\n- Ubuntu/Debian example: `sudo apt install build-essential python3-dev portaudio19-dev libjack-jackd2-dev`\r\n - The Python and PortAudio development packages prevent missing Python.h and missing portaudio.h errors, respectively.\r\n - Installing `libjack-jackd2-dev` manually prevents `portaudio19-dev` from downgrading to libjack0 and removing wine etc (<https://bugs.launchpad.net/ubuntu/+source/portaudio19/+bug/132002>).\r\n - In some circumstances, such as if you are using the kxstudio repo with Linux Mint, incompatible packages may be removed (See <https://github.com/anrayliu/pyvidplayer2/issues/36> for the latest updates on this issue):\r\n```\r\nThe following additional packages will be installed:\r\n libjack-dev libjack0 libportaudiocpp0\r\nSuggested packages:\r\n jackd1 portaudio19-doc\r\nThe following packages will be REMOVED:\r\n libasound2-plugins:i386 libjack-jackd2-0 libjack-jackd2-0:i386 wine-stable wine-stable-i386:i386 winehq-stable\r\nThe following NEW packages will be installed:\r\n libjack-dev libjack0 libportaudiocpp0 portaudio19-dev\r\n```\r\n\r\n# Dependencies\r\n\r\n```\r\nnumpy\r\nFFmpeg and FFprobe (not a Python package)\r\n```\r\n\r\n## Optional Packages\r\n\r\n```\r\nopencv_python (comes installed for all-around improvements)\r\npygame (graphics and audio library, comes installed)\r\nPyAudio (audio library, comes installed)\r\npysubs2 (for subtitles, comes installed)\r\nyt_dlp (for streaming Youtube videos)\r\nimageio (for videos in bytes)\r\npyglet (graphics library)\r\nPySide6 (graphics library)\r\nPyQt6 (graphics library)\r\n```\r\n\r\n# Quickstart\r\n\r\nRefer to the examples folder for more basic guides, and documentation.md contains more detailed information.\r\n\r\n## Super Quick Demo\r\n```\r\nfrom pyvidplayer2 import Video\r\nVideo(\"video.mp4\").preview()\r\n```\r\n\r\n## Pygame Integration\r\n```\r\nimport pygame\r\nfrom pyvidplayer2 import Video\r\n\r\n\r\n# create video object\r\n\r\nvid = Video(\"video.mp4\")\r\n\r\nwin = pygame.display.set_mode(vid.current_size)\r\npygame.display.set_caption(vid.name)\r\n\r\n\r\nwhile vid.active:\r\n key = None\r\n for event in pygame.event.get():\r\n if event.type == pygame.QUIT:\r\n vid.stop()\r\n elif event.type == pygame.KEYDOWN:\r\n key = pygame.key.name(event.key)\r\n\r\n if key == \"r\":\r\n vid.restart() #rewind video to beginning\r\n elif key == \"p\":\r\n vid.toggle_pause() #pause/plays video\r\n elif key == \"m\":\r\n vid.toggle_mute() #mutes/unmutes video\r\n elif key == \"right\":\r\n vid.seek(15) #skip 15 seconds in video\r\n elif key == \"left\":\r\n vid.seek(-15) #rewind 15 seconds in video\r\n elif key == \"up\":\r\n vid.set_volume(1.0) #max volume\r\n elif key == \"down\":\r\n vid.set_volume(0.0) #min volume\r\n\r\n # only draw new frames, and only update the screen if something is drawn\r\n\r\n if vid.draw(win, (0, 0), force_draw=False):\r\n pygame.display.update()\r\n\r\n pygame.time.wait(16) # around 60 fps\r\n\r\n\r\n# close video when done\r\n\r\nvid.close()\r\npygame.quit()\r\n```\r\n\r\n# Known Bugs (as of v0.9.24)\r\n\r\n- Youtube videos will sometimes freeze or stutter (rare)\r\n- Video seeking is slow when reading from bytes\r\n- Rotated videos when playing from bytes will appear in their original direction\r\n\r\n\r\n# Documentation \r\n\r\nDocumentation also available in repository as documentation.md.\r\n\r\n# Video(path, chunk_size=10, max_threads=1, max_chunks=1, subs=None, post_process=PostProcessing.none, interp=\"linear\", use_pygame_audio=False, reverse=False, no_audio=False, speed=1, youtube=False, max_res=1080, as_bytes=False, audio_track=0, vfr=False, pref_lang=\"en\", audio_index=None)\r\n\r\nMain object used to play videos. Videos can be read from disk, memory or streamed from Youtube. The object uses FFMPEG to extract chunks of audio from videos and then feeds it into a Pyaudio stream. It uses OpenCV to display the appropriate video frames. Videos can only be played simultaneously if they're using Pyaudio (see `use_pygame_audio` below). Pygame or Pygame CE are the only graphics libraries to support subtitles. YTDLP is required to stream videos from Youtube. IMAGEIO and PyAV are required to play videos from memory. This particular object uses Pygame for graphics, but see bottom for other supported libraries. Actual class name is `VideoPygame`.\r\n\r\n## Parameters\r\n - `path: str | bytes` - Path to video file. Supports almost all file types such as mkv, mp4, mov, avi, 3gp, etc. Can also provide the video in bytes (see `as_bytes` below). If streaming from Youtube (see `youtube` below), provide the URL here.\r\n - `chunk_size: float` - How much audio is extracted at a time, in seconds. Increasing this value will slow the initial loading of video, but is necessary to prevent stuttering. Recommended to keep over 60 if streaming from Youtube (see `youtube` below).\r\n - `max_threads: int` - Maximum number of chunks that can be extracted at any given time. Do not change if streaming from Youtube (see `youtube` below).\r\n - `max_chunks: int` - Maximum number of chunks allowed to be extracted and reserved. Do not change if streaming from Youtube (see `youtube` below).\r\n - `subs: pyvidplayer2.Subtitles` - Pass a `Subtitles` object here for the video to display subtitles.\r\n - `post_process: function(numpy.ndarray) -> numpy.ndarray` - Post processing function that is applied whenever a frame is rendered. This is PostProcessing.none by default, which means no alterations are taking place. Post processing functions should accept a NumpPy image (see `frame_data` below) and return the processed image.\r\n - `interp: str | int` - Interpolation technique used when resizing frames with OpenCV. Does nothing if OpenCv is not installed. Accepts `\"nearest\"`, `\"linear\"`, `\"cubic\"`, `\"lanczos4\"` and `\"area\"`. Nearest is the fastest technique but produces the worst results. Lanczos4 produces the best results but is so much more intensive that it's usually not worth it. Area is a technique that produces the best results when downscaling. This parameter can also accept OpenCV constants as in `cv2.INTER_LINEAR`.\r\n - `use_pygame_audio: bool` - Specifies whether to use Pyaudio or Pygame to play audio. Pyaudio is almost always the best option, so this is mostly obsolete. Using Pygame audio will not allow videos to be played in parallel. \r\n - `reverse: bool` - Specifies whether to play the video in reverse. Warning: Doing so will load every video frame into memory, so videos longer than a few minutes can temporarily brick your computer. Subtitles are currently unaffected by reverse playback.\r\n - `no_audio: bool` - Specifies whether the given video has no audio tracks. Setting this to `True` can also be used to disable all existing audio tracks.\r\n - `speed: float | int` - Float from 0.5 to 10.0 that multiplies the playback speed. Note that if for example, speed=2, the video will play twice as fast. However, every single video frame will still be processed. Therefore, the frame rate of your program must be at least twice that of the video's frame rate to prevent dropped frames. So for example, for a 24 fps video, the video will have to be updated (see `draw` below) at least, but ideally more than 48 times a second to achieve true x2 speed.\r\n - `youtube: bool` - Specifies whether to stream a Youtube video. Path must be a valid Youtube video URL. The python packages yt_dlp and opencv-python are required for this feature. They can be installed through pip. Setting this to `True` will force `chunk_size` to be at least 60 and `max_threads` to be 1. Cannot play active livestreams.\r\n - `max_res: int` - Only used when streaming Youtube videos. Sets the highest possible resolution when choosing video quality. 4320p is the highest Youtube supports. Note that actual video quality is not guaranteed to match `max_res`.\r\n - `as_bytes: bool` - Specifies whether `path` is a video in byte form. The python packages imageio and av are required for this feature. It can be installed through pip.\r\n - `audio_track: int` - Selects which audio track to use. 0 will play the first, 1 will play the second, and so on.\r\n - `vfr: bool` - Used to play variable frame rate videos properly. If `False`, a constant frame rate will be assumed. If `True`, presentation timestamps will be extracted for each frame (see `timestamps` below). This still works for constant frame rate videos, but extracting the timestamps will mean a longer initial load.\r\n - `pref_lang: str` - Only used when streaming Youtube videos. Used to select a language track if video has multiple.\r\n - `audio_index: int` - Used to specify which audio output device to use. Can be specific to each video, and is automatically calculated if argument is not provided. To get a list of devices and their indices, use libraries like sounddevice (see audio_devices_demo.py in examples folder).\r\n\r\n## Attributes\r\n - `path: str | bytes` - Same as given argument.\r\n - `name: str` - Name of file without the directory and extension. Will be an empty string if video is given in byte form (see `as_bytes` above).\r\n - `ext: str` - Type of video (mp4, mkv, mov, etc). Will be `\"webm\"` if streaming from Youtube (see `youtube` above). Will be an empty string if video is given in byte form (see `as_bytes` above).\r\n - `frame: int` - Current frame index. Starts from 0.\r\n - `frame_rate: float` - Float that indicates how many frames are in one second.\r\n - `max_fr: float` - Only used if `vfr = True`. Gives the maximum frame rate throughout the video.\r\n - `min_fr: float` - Only used if `vfr = True`. Gives the minimum frame rate throughout the video.\r\n - `avg_fr: float` - Only used if `vfr = True`. Gives the average frame rate of all the extracted presentation timestamps.\r\n - `timestamps: [float]` - List of presentation timestamps for each frame.\r\n - `frame_count: int` - How many total frames there are. May not be 100% accurate. For a more accurate (but slower) frame count,set `vfr = True` and use `len(video.timestamps)`.\r\n - `frame_delay: float` - Time between frames in order to maintain frame rate (in fractions of a second).\r\n - `duration: float` - Length of video in seconds.\r\n - `original_size: (int, int)` - Tuple containing the width and height of each original frame. Unaffected by resizing.\r\n - `current_size: (int, int)` - Tuple containing the width and height of each frame being rendered. Affected by resizing.\r\n - `aspect_ratio: float` - Width divided by height of original size.\r\n - `chunk_size: float` - Same as given argument. May change if `youtube` is `True` (see `youtube` above).\r\n - `max_chunks: int` - Same as given argument.\r\n - `max_threads: int` - Same as given argument. May change if `youtube` is `True` (see `youtube` above).\r\n - `frame_data: numpy.ndarray` - Current video frame as a NumPy `ndarray`.\r\n - `frame_surf: pygame.Surface` - Current video frame as a Pygame `Surface`.\r\n - `active: bool` - Whether the video is currently playing. This is unaffected by pausing and resuming.\r\n - `buffering: bool` - Whether the video is waiting for audio to extract.\r\n - `paused: bool`\r\n - `volume: float`\r\n - `muted: bool`\r\n - `speed: float | int` - Same as given argument.\r\n - `subs: pyvidplayer2.Subtitles` - Same as given argument.\r\n - `post_func: function(numpy.ndarray) -> numpy.ndarray` - Same as given argument. Can be changed with `set_post_func`.\r\n - `interp: int` - Same as given argument. Can be changed with `set_interp`. Will be converted to an integer if given a string. For example, if `\"linear\"` is given during initialization, this will be converted to cv2.INTER_LINEAR.\r\n - `use_pygame_audio: bool` - Same as given argument. May be automatically set to default sound backend.\r\n - `reverse: bool` - Same as given argument.\r\n - `no_audio: bool` - Same as given argument. May change if no audio is automatically detected.\r\n - `youtube: bool` - Same as given argument.\r\n - `max_res: int` - Same as given argument.\r\n - `as_bytes: bool` - Same as given argument. May change if bytes are automatically detected.\r\n - `audio_track: int` - Same as given argument.\r\n - `vfr: bool` - Same as given argument. \r\n - `pref_lang: str` - Same as given argument.\r\n - `audio_index: int` - Same as given argument.\r\n \r\n## Methods\r\n - `play() -> None` - Sets `active` to `True`.\r\n - `stop() -> None` - Resets video and sets `active` to `False`.\r\n - `resize(size: (int, int)) -> None`\r\n - `change_resolution(height: int) -> None` - Given a height, the video will scale it's dimensions while maintaining aspect ratio.\r\n - `close() -> None` - Releases resources. Always recommended to call when done.\r\n - `restart() -> None`\r\n - `get_speed() -> float | int`\r\n - `set_volume(volume: float) -> None` - Adjusts the volume of the video, from 0.0 (min) to 1.0 (max).\r\n - `get_volume() -> float`\r\n - `get_paused() -> bool`\r\n - `toggle_pause() -> None` - Pauses if the video is playing, and resumes if the video is paused.\r\n - `pause() -> None`\r\n - `resume() -> None`\r\n - `set_audio_path(index: int)` - Sets the audio track used (see `audio_track` above).\r\n - `toggle_mute() -> None`\r\n - `mute() -> None`\r\n - `unmute() -> None`\r\n - `set_interp(interp: str | int) -> None` - Changes the interpolation technique that OpenCV uses. Works the same as the `interp` parameter (see `interp` above). Does nothing if OpenCV is not installed.\r\n - `set_post_func(func: function(numpy.ndarray) -> numpy.ndarray) -> None` - Changes the post processing function. Works the same as the `post_func` parameter (see `post_func` above). \r\n - `get_pos(): float` - Returns the current position in seconds.\r\n - `seek(time: float | int, relative: bool = True) -> None` - Changes the current position in the video. If relative is `True`, the given time will be added or subtracted to the current time. Otherwise, the current position will be set to the given time exactly. Time must be given in seconds, and seeking will be accurate to one hundredth of a second. Note that \r\n frames and audio within the video will not yet be updated after calling seek.\r\n - `seek_frame(index: int, relative: bool = False) -> None` - Same as `seek` but seeks to a specific frame instead of a time stamp. For example, index 0 will seek to the first frame, index 1 will seek to the second frame, and so on.\r\n - `update() -> bool` - Allows video to perform required operations. `draw` already calls this method, so it's usually not used. Returns `True` if a new frame is ready to be displayed.\r\n - `draw(surf: pygame.Surface, pos: (int, int), force_draw: bool = True) -> bool` - Draws the current video frame onto the given surface, at the given position. If `force_draw` is `True`, a surface will be drawn every time this is called. Otherwise, only new frames will be drawn. This reduces CPU usage but will cause flickering if anything is drawn under or above the video. This method also returns whether a frame was drawn.\r\n - `preview(show_fps: bool = False, max_fps: int = 60) -> None` - Opens a window and plays the video. This method will hang until the video finishes. `max_fps` enforces how many times a second the video is updated. If `show_fps` is `True`, a counter will be displayed showing the actual number of new frames being rendered every second.\r\n\r\n## Supported Graphics Libraries\r\n - Pygame or Pygame CE (`Video`) <- default and best supported\r\n - Tkinter (`VideoTkinter`)\r\n - Pyglet (`VideoPyglet`)\r\n - PySide6 (`VideoPySide`)\r\n - PyQT6 (`VideoPyQT`)\r\n\r\nTo use other libraries instead of Pygame, use their respective video object. Each preview method will use their respective graphics API to create a window and draw frames. See the examples folder for details. Note that `Subtitles`, `Webcam`, and `VideoPlayer` only work with Pygame installed. Preview methods for other graphics libraries also do not accept any arguments.\r\n\r\n## As a Generator\r\n\r\nVideo objects can be iterated through as a generator, returning each subsequent frame. Frames will be given in reverse if video is reversed, and post processing and resizing will still take place. After iterating through frames, `play()` will resume the video from where the last frame left off. Returned frames will be in BGR format.\r\n```\r\nfor frame in Video(\"example.mp4\"):\r\n print(frame)\r\n```\r\n\r\n## In a Context Manager\r\n\r\nVideo objects can also be opened using context managers which will automatically call `close()` (see `close()` above) when out of use.\r\n```\r\nwith Video(\"example.mp4\") as vid:\r\n vid.preview()\r\n```\r\n\r\n\r\n# VideoPlayer(video, rect, interactable=False, loop=False, preview_thumbnails=0, font_size=10)\r\n\r\nVideoPlayers are GUI containers for videos. They are useful for scaling a video to fit an area or looping videos. Only supported for Pygame.\r\n\r\n## Parameters\r\n - `video: pyvidplayer2.VideoPygame` - Video object to play.\r\n - `rect: (int, int, int, int)` - An x, y, width, and height of the VideoPlayer. The top left corner will be the x, y coordinate.\r\n - `interactable: bool` - Enables the GUI.\r\n - `loop: bool` - Specifies whether the contained video will restart after it finishes. If the queue is not empty, the entire queue will loop, not just the current video.\r\n - `preview_thumbnails: int` - Number of preview thumbnails loaded and saved in memory. When seeking, a preview window will show the closest loaded frame. The higher this number is, the more frames are loaded, increasing the preview accuracy but also increasing initial load time and memory usage. Because of this, this value is defaulted to 0, which turns seek previewing off.\r\n - `font_size: int` - Sets font size for GUI elements.\r\n\r\n## Attributes \r\n - `video: pyvidplayer2.VideoPygame` - Same as given argument.\r\n - `frame_rect: (int, int, int, int)` - Same as given argument.\r\n - `vid_rect: (int, int, int, int)` - Location and dimensions (x, y, width, height) of the video fitted into `frame_rect` while maintaining aspect ratio. Black bars will appear in any unused space.\r\n - `interactable: bool` - Same as given argument.\r\n - `loop: bool` - Same as given argument.\r\n - `queue_: list[pyvidplayer2.VideoPygame | str]` - Videos to play after the current one finishes.\r\n - `preview_thumbnails: int` - Same as given argument.\r\n\r\n## Methods\r\n - `zoom_to_fill() -> None` - Zooms in the video so that `frame_rect` is entirely filled in while maintaining aspect ratio.\r\n - `zoom_out() -> None` - Reverts `zoom_to_fill()`.\r\n - `toggle_zoom() -> None` - Switches between zoomed in and zoomed out.\r\n - `queue(input: pyvidplayer2.VideoPygame | str) -> None` - Accepts a path to a video or a Video object and adds it to the queue. Passing a path will not load the video until it becomes the active video. Passing a Video object will cause it to silently load its first audio chunk, so changing videos will be as seamless as possible.\r\n - `get_queue(): list[pyvidplayer2.VideoPygame]` - Returns list of queued video objects.\r\n - `resize(size: (int, int)) -> None` - Resizes the video player. The contained video will automatically readjust to fit the player.\r\n - `move(pos: (int, int), relative: bool = False) -> None` - Moves the VideoPlayer. If `relative` is `True`, the given coordinates will be added onto the current coordinates. Otherwise, the current coordinates will be set to the given coordinates.\r\n - `update(events: list[pygame.event.Event], show_ui: bool = None, fps: int = 0) -> bool` - Allows the VideoPlayer to make calculations. It must be given the returns of `pygame.event.get()`. The GUI automatically shows up when your mouse hovers over the video player, so setting `show_ui` to `False` can be used to override that. The `fps` parameter can enforce be used to enforce a frame rate to your app. This method also returns whether the UI was shown.\r\n - `draw(surface: pygame.Surface) -> None` - Draws the VideoPlayer onto the given Pygame surface.\r\n - `close() -> None` - Releases resources. Always recommended to call when done.\r\n - `skip() -> None` - Moves onto the next video in the queue.\r\n - `get_video() -> pyvidplayer2.VideoPygame` - Returns currently playing video.\r\n\r\n\r\n# Subtitles(path, colour=\"white\", highlight=(0, 0, 0, 128), font=pygame.font.SysFont(\"arial\", 30), encoding=\"utf-8-sig\", offset=50, delay=0)\r\n\r\nObject used for handling subtitles. Only supported for Pygame.\r\n\r\n## Parameters\r\n - `path: str` - Path to subtitle file. This can be any file pysubs2 can read including .srt, .ass, .vtt, and others.\r\n - `colour: str | (int, int, int)` - Colour of text as an RGB value or a string recognized by Pygame.\r\n - `highlight: str | (int, int, int, int)` - Background colour of text. Accepts RGBA, so it can be made completely transparent.\r\n - `font: pygame.font.Font | pygame.font.SysFont` - Pygame `Font` or `SysFont` object used to render surfaces. This includes the size of the text.\r\n - `encoding: str` - Encoding used to open subtitle files.\r\n - `offset: float` - The higher this number is, the closer the subtitle is to the top of the screen.\r\n - `delay: float` - Delays all subtitles by this many seconds.\r\n\r\n## Attributes\r\n - `path: str` - Same as given argument.\r\n - `encoding: str` - Same as given argument.\r\n - `start: float` - Starting timestamp of current subtitle.\r\n - `end: float` - Ending timestamp of current subtitle.\r\n - `text: str` - Current subtitle text.\r\n - `surf: pygame.Surface` - Current text in a Pygame `Surface`.\r\n - `colour: str | (int, int, int)` - Same as given argument.\r\n - `highlight: str | (int, int, int, int)` - Same as given argument.\r\n - `font: pygame.font.Font | pygame.font.SysFont` - Same as given argument.\r\n - `offset: float` - Same as given argument.\r\n - `delay: float` - Same as given argument.\r\n\r\n## Methods \r\n - `set_font(font: pygame.font.Font | pygame.font.SysFont) -> None` - Same as `font` parameter (see `font` above).\r\n - `get_font() -> pygame.font.Font | pygame.font.SysFont`\r\n\r\n\r\n# Webcam(post_process=PostProcessing.none, interp=\"linear\", fps=30, cam_id=0)\r\n\r\nObject used for displaying a webcam feed. Only supported for Pygame.\r\n\r\n## Parameters\r\n - `post_process: function(numpy.ndarray) -> numpy.ndarray` - Post processing function that is applied whenever a frame is rendered. This is PostProcessing.none by default, which means no alterations are taking place. Post processing functions should accept a NumpPy image (see `frame_data` below) and return the processed image.\r\n - `interp: str | int` - Interpolation technique used by OpenCV when resizing frames. Does nothing if OpenCV is not installed. Accepts `\"nearest\"`, `\"linear\"`, `\"cubic\"`, `\"lanczos4\"` and `\"area\"`. Nearest is the fastest technique but produces the worst results. Lanczos4 produces the best results but is so much more intensive that it's usually not worth it. Area is a technique that produces the best results when downscaling. This parameter can also accept OpenCV constants as in `cv2.INTER_LINEAR`.\r\n - `fps: int` - Maximum number of frames captured from the webcam per second.\r\n - `cam_id: int` - Specifies which webcam to use if there are more than one. 0 means the first, 1 means the second, and so on.\r\n\r\n## Attributes\r\n - `post_process: function(numpy.ndarray) -> numpy.ndarray` - Same as given argument.\r\n - `interp: int` - Same as given argument.\r\n - `fps: int` - Same as given argument.\r\n - `original_size: (int, int)` - Tuple containing the width and height of each frame captured. Unaffected by resizing.\r\n - `current_size: (int, int)` - Tuple containing the width and height of each frame being rendered. Affected by resizing.\r\n - `aspect_ratio: float` - Width divided by height of original size.\r\n - `active: bool` - Whether the webcam is currently playing.\r\n - `frame_data: numpy.ndarray` - Current video frame as a NumPy `ndarray`. Will be in BGR format.\r\n - `frame_surf: pygame.Surface` - Current video frame as a Pygame `Surface`.\r\n - `cam_id: int` - Same as given argument.\r\n\r\n## Methods\r\n - `play() -> None`\r\n - `stop() -> None`\r\n - `resize(size: (int, int)) -> None`\r\n - `change_resolution(height: int) -> None` - Given a height, the video will scale its width while maintaining aspect ratio.\r\n - `set_interp(interp: str | int) -> None` - Changes the interpolation technique that OpenCV uses. Works the same as the `interp` parameter (see `interp` above). Does nothing if OpenCV is not installed.\r\n - `set_post_func(func: function(numpy.ndarray) -> numpy.ndarray) -> None` - Changes the post processing function. Works the same as the `post_func` parameter (see `post_func` above). \r\n - `close() -> None` - Releases resources. Always recommended to call when done.\r\n - `get_pos() -> float` - Returns how long the webcam has been active. Is not reset if webcam is stopped.\r\n - `update() -> bool` - Allows webcam to perform required operations. `draw` already calls this method, so it's usually not used. Returns `True` if a new frame is ready to be displayed.\r\n - `draw(surf: pygame.Surface, pos: (int, int), force_draw: bool = True) -> bool` - Draws the current video frame onto the given surface, at the given position. If `force_draw` is `True`, a surface will be drawn every time this is called. Otherwise, only new frames will be drawn. This reduces CPU usage but will cause flickering if anything is drawn under or above the video. This method also returns whether a frame was drawn.\r\n - `preview() -> None` - Opens a window and plays the webcam. This method will hang until the window is closed. Videos are played at whatever fps the webcam object is set to.\r\n\r\n\r\n# PostProcessing\r\n\r\nUsed to apply various filters to video playback. Mostly for fun. Works across all graphics libraries. Requires OpenCV.\r\n\r\n - `none` - Default. Nothing happens.\r\n - `blur` - Slightly blurs frames.\r\n - `sharpen` - An okay-looking sharpen. Looks pretty bad for small resolutions.\r\n - `greyscale` - Removes colour from frame.\r\n - `noise` - Adds a static-like filter. Very resource intensive.\r\n - `letterbox` - Adds black bars above and below the frame to look more cinematic.\r\n - `cel_shading` - Thickens borders for a comic book style filter.\r\n\r\n# Misc\r\n\r\n```\r\nprint(pyvidplayer2.get_version_info())\r\n```\r\n\r\nReturns a dictionary with the version of pyvidplayer2, FFMPEG, and Pygame. Version can also be accessed directly\r\nwith `pyvidplayer2._version.__version__` or `pyvidplayer2.VERSION`.\r\n\r\nWhen there are no suitable exceptions, `pyvidplayer2.Pyvidplayer2Error` may be raised.\r\n",
"bugtrack_url": null,
"license": null,
"summary": "Reliable, easy, and fast video playback in Python",
"version": "0.9.24",
"project_urls": {
"Documentation": "https://github.com/anrayliu/pyvidplayer2/blob/main/documentation.md",
"Homepage": "https://github.com/anrayliu/pyvidplayer2",
"Issues": "https://github.com/anrayliu/pyvidplayer2/issues",
"Repository": "https://github.com/anrayliu/pyvidplayer2.git"
},
"split_keywords": [
"pygame",
" video",
" playback",
" tkinter",
" pyqt",
" pyside",
" pyglet"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e225fc35d861c302c2dc4c7415d6b77e1a4f7d624bb61eb163b85441b4c09bf3",
"md5": "fae089aa5b65acd418b2b944d79fcc38",
"sha256": "2e44bf68d9c9385b2d63edd41fbf3b22a99f918f3a5342b8b73485ac713ae50d"
},
"downloads": -1,
"filename": "pyvidplayer2-0.9.24-py3-none-any.whl",
"has_sig": false,
"md5_digest": "fae089aa5b65acd418b2b944d79fcc38",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 40178,
"upload_time": "2024-10-18T02:29:36",
"upload_time_iso_8601": "2024-10-18T02:29:36.043677Z",
"url": "https://files.pythonhosted.org/packages/e2/25/fc35d861c302c2dc4c7415d6b77e1a4f7d624bb61eb163b85441b4c09bf3/pyvidplayer2-0.9.24-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0f9791f2bd6c465371ccc1453323956571a5cbc1faa03f14ce0bdce058bb32b7",
"md5": "f9856534657ed00a96fc3f9263e297bd",
"sha256": "483324380d1b2a27aba18dab7d053b373c1c852663c2cbb32290100f5c7a54f4"
},
"downloads": -1,
"filename": "pyvidplayer2-0.9.24.tar.gz",
"has_sig": false,
"md5_digest": "f9856534657ed00a96fc3f9263e297bd",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 36778,
"upload_time": "2024-10-18T02:29:37",
"upload_time_iso_8601": "2024-10-18T02:29:37.422384Z",
"url": "https://files.pythonhosted.org/packages/0f/97/91f2bd6c465371ccc1453323956571a5cbc1faa03f14ce0bdce058bb32b7/pyvidplayer2-0.9.24.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-18 02:29:37",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "anrayliu",
"github_project": "pyvidplayer2",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "pyvidplayer2"
}
JSON
