Video player¶
New in version 1.2.0.
The video player widget can be used to play video and let the user control the play/pause, volume and seek. The widget cannot be customized a lot, due to the complex assembly of lot of base widgets.

Annotations¶
If you want to display some texts at a specific time, duration, you might want to look at annotations. An annotation file have a ”.jsa” extension. The player will automatically load the associated annotation file if exists.
It’s a JSON based file, that provide a list of label dictionnary. The key and value must match one of the VideoPlayerAnnotation. For example, here is a short version of a jsa that you can found in examples/widgets/softboy.jsa:
[
{"start": 0, "duration": 2,
"text": "This is an example of annotation"},
{"start": 2, "duration": 2,
"bgcolor": [0.5, 0.2, 0.4, 0.5],
"text": "You can change the background color"}
]
On our softboy.avi example, it will look like this:

If you want to test how annotations file are working, test with:
python -m kivy.uix.videoplayer examples/widgets/softboy.avi
Fullscreen¶
The video player can play the video in fullscreen, if VideoPlayer.allow_fullscreen is activated, when the user double-tap on the video. By default, if the video is smaller than the Window, it will be not stretched.
You can allow it by passing custom options to Video instance:
player = VideoPlayer(source='myvideo.avi', play=True,
options={'allow_stretch': True})
- class kivy.uix.videoplayer.VideoPlayer(**kwargs)¶
Bases: kivy.uix.gridlayout.GridLayout
VideoPlayer class, see module documentation for more information.
- allow_fullscreen¶
By default, you can double-tap on the video to make it fullscreen. Set this property to False to prevent this behavior.
allow_fullscreen a BooleanProperty, default to True
- annotations¶
If set, it will be used for reading annotations box.
- duration¶
Duration of the video. The duration is default to -1, and set to real duration when the video is loaded.
duration is a NumericProperty, default to -1.
- fullscreen¶
Switch to a fullscreen view. This must be used with care. When activated, the widget will remove itself from its parent, remove all children from the window and add itself to it. When fullscreen is unset, all the previous children are restored, and the widget is readded to its previous parent.
Warning
The re-add operation doesn’t care about it’s children index position within the parent.
fullscreen a BooleanProperty, default to False
- image_loading¶
Image filename used when the video is loading.
- image_overlay_play¶
Image filename used to show an “play” overlay when the video is not yet started.
- image_pause¶
Image filename used for the “Pause” button.
- image_play¶
Image filename used for the “Play” button.
- image_volumehigh¶
Image filename used for the volume icon, when the volume is high.
- image_volumelow¶
Image filename used for the volume icon, when the volume is low.
- image_volumemedium¶
Image filename used for the volume icon, when the volume is medium.
- image_volumemuted¶
Image filename used for the volume icon, when the volume is muted.
- options¶
Optionals parameters can be passed to Video instance with this property.
options a DictProperty, default to {}
- play¶
Boolean, indicates if the video is playing. You can start/stop the video by setting this property.
# start playing the video at creation video = VideoPlayer(source='movie.mkv', play=True) # create the video, and start later video = VideoPlayer(source='movie.mkv') # and later video.play = True
play is a BooleanProperty, default to False.
- position¶
Position of the video between 0 and duration. The position is default to -1, and set to real position when the video is loaded.
position is a NumericProperty, default to -1.
- seek(percent)¶
Change the position to a percentage of duration. Percentage must be a value between 0-1.
Warning
Calling seek() before video is loaded have no impact.
- source¶
Source of the video to read
source a StringProperty, default to None.
- thumbnail¶
Thumbnail of the video to show. If None, it will try to search the thumbnail from the source + .png.
thumbnail a StringProperty, default to None.
- volume¶
Volume of the video, in the range 0-1. 1 mean full volume, 0 mean mute.
volume is a NumericProperty, default to 1.
- class kivy.uix.videoplayer.VideoPlayerAnnotation(**kwargs)¶
Bases: kivy.uix.label.Label
Annotation class used for creating annotation labels.
Additionnals key are available:
- bgcolor: [r, g, b, a] - background color of the text box
- bgsource: ‘filename’ - background image used for background text box
- border: (n, e, s, w) - border used for background image
- duration¶
Duration of the annotation
duration is a NumericProperty, default to 1
- start¶
Start time of the annotation.
start is a NumericProperty, default to 0