Video¶

The Video widget is used to display video files and streams. Depending on your Video core provider, platform, and plugins, you will be able to play different formats. For example, gstreamer is more versatile, and can read many video containers and codecs such as MKV, OGV, AVI, MOV, FLV (if the correct gstreamer plugins are installed). Our VideoBase implementation is used under the hood.

Video loading is asynchronous - many properties are not available until the video is loaded (when the texture is created):

def on_position_change(instance, value):
    print('The position in the video is', value)

def on_duration_change(instance, value):
    print('The duration of the video is', value)

video = Video(source='PandaSneezes.avi')
video.bind(
    position=on_position_change,
    duration=on_duration_change
)

One can define a preview image which gets displayed until the video is started/loaded by passing preview to the constructor:

video = Video(
    source='PandaSneezes.avi',
    preview='PandaSneezes_preview.png'
)

One can display the placeholder image when the video stops by reacting on eos:

def on_eos_change(self, inst, val):
    if val and self.preview:
        self.set_texture_from_resource(self.preview)

video.bind(eos=on_eos_change)

Added in version 3.0.0.

An observable buffering boolean for loading-overlay UX and a provider-specific options dict were added in 3.0.0:

video = Video(
    source='movie.mp4',
    state='play',
    # Provider-specific options forwarded opaquely; each provider
    # documents the keys it honors. AVFoundation example:
    options={'automatically_waits_to_minimize_stalling': False},
)

# Drive a loading overlay from a single rule that covers both the
# initial wait and any mid-stream rebuffer:
video.bind(
    loaded=lambda v, l: overlay.set_visible(
        not l or v.buffering),
    buffering=lambda v, b: overlay.set_visible(
        not v.loaded or b),
)

Static thumbnails can be generated without instantiating a widget via Video.generate_thumbnail():

texture = Video.generate_thumbnail(
    'movie.mp4', time=5.0, size=(320, 180))
if texture is not None:
    thumbnail_image.texture = texture

class kivy.uix.video.Video(**kwargs)[source]¶

Bases: Image

Video class. See module documentation for more information.

buffering¶

Whether playback is currently delayed/stalled while trying to satisfy state='play'. Mirrors kivy.core.video.VideoBase.buffering – True covers both the initial pre-playback wait and any mid-stream rebuffer; always False while paused or stopped. Providers that cannot detect stalls leave it False.

For a single-rule loading overlay:

overlay.visible = not video.loaded or video.buffering

Added in version 3.0.0.

buffering is a BooleanProperty and defaults to False.

duration¶

Duration of the video. The duration defaults to -1, and is set to a real duration when the video is loaded.

duration is a NumericProperty and defaults to -1.

eos¶

Boolean, indicates whether the video has finished playing or not (reached the end of the stream).

eos is a BooleanProperty and defaults to False.

classmethod generate_thumbnail(filename, time, size=None)[source]¶

Generate a thumbnail Texture from the given video file at the given timestamp, without instantiating a Video widget or starting playback. Delegates to the currently selected core video provider.

Parameters:

filename: str: Path or URI to the video. Resolved through resource_find() when it does not look like a URL.
time: float: Timestamp in seconds at which to grab the thumbnail.
size: tuple of (int, int), optional: Target (width, height). When None the source video’s native frame size is used.

Returns:

A Texture, or None if no provider could generate the thumbnail.

Added in version 3.0.0.

loaded¶

Boolean, indicates whether the video is loaded and ready for playback or not.

Added in version 1.6.0.

loaded is a BooleanProperty and defaults to False.

options¶

Provider-specific options forwarded to the underlying core video at construction. Each video provider documents the keys it honors on its own class (the canonical reference for behavior and defaults); the per-provider summary below is a quick lookup for the keys most apps reach for.

Unknown keys for the selected provider are logged as a warning and otherwise left untouched in this dict (so apps that stash extra metadata in options keep working across Kivy / provider upgrades).

Providers that consume options:

AVFoundation (macOS / iOS) – see VideoAVFoundation for full detail:
- automatically_waits_to_minimize_stalling (bool, default True) – forwards to the AVPlayer property of the same name. The default matches AVPlayer’s own and favors uninterrupted playback at the cost of start-up latency. Set to False for snappier start (playback begins as soon as the first decodable frame is available rather than buffering ahead).

Other providers (GStreamer, FFmpeg / ffpyplayer) currently expose no documented options keys: unknown kwargs in options are also unpacked as keyword arguments to the core video for back-compat with apps that put well-known kwargs (e.g. eos='loop') in this dict.

Example:

video = Video(
    source='clip.mp4',
    state='play',
    options={'automatically_waits_to_minimize_stalling': False},
)

Added in version 1.0.4.

Changed in version 3.0.0: In addition to being unpacked as keyword arguments (as before), the full dict is also forwarded to the core video as a single options= kwarg, giving providers a clean, introspectable place to look for provider-specific keys. Documented keys for the AVFoundation provider added in 3.0.0; see above.

Reclassified from ObjectProperty to DictProperty (with allownone=True) so the property now validates that the assigned value is either a dict or None, each instance gets its own dict (no shared mutable default), and top-level mutations (video.options['k'] = v) dispatch on_options instead of only full reassignment.

options is a DictProperty and defaults to {}. None is accepted and normalized to {} before forwarding to the core video.

position¶

Position of the video between 0 and duration. The position defaults to -1 and is set to a real position when the video is loaded.

position is a NumericProperty and defaults to -1.

preview¶

Filename / source of a preview image displayed before video starts.

preview is a StringProperty and defaults to None.

If set, it gets displayed until the video is loaded/started.

Added in version 2.1.0.

seek(percent, precise=True)[source]¶

Change the position to a percentage (strictly, a proportion): of duration.

Parameters:

percent: float or int: Position to seek as a proportion of the total duration, must be between 0-1.
precise: bool, defaults to True: Precise seeking is slower, but seeks to exact requested percent.

Warning

Calling seek() before the video is loaded has no effect.

Added in version 1.2.0.

Changed in version 1.10.1: The precise keyword argument has been added.

state¶

String, indicates whether to play, pause, or stop the video:

# start playing the video at creation
video = Video(source='movie.mkv', state='play')

# create the video, and start later
video = Video(source='movie.mkv')
# and later
video.state = 'play'

state is an OptionProperty and defaults to ‘stop’.

unload()[source]¶: Unload the video. The playback will be stopped.

Added in version 1.8.0.

volume¶

Volume of the video, in the range 0-1. 1 means full volume, 0 means mute.

volume is a NumericProperty and defaults to 1.

« Tree View

Video player »

Version

Quick search

Table Of Contents

Video¶