Table Of Contents
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 much, because of the complex assembly of numerous base widgets.

Annotations¶
If you want to display text at a specific time and duration, consider annotations. An annotation file has a ”.jsa” extension. The player will automatically load the associated annotation file if it exists.
The annotation file is JSON-based, providing a list of label dictionary items. The key and value must match one of the VideoPlayerAnnotation items. For example, here is a short version of a jsa file that you can find 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"}
]
For our softboy.avi example, the result will be:

If you want to experiment with annotation files, 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 by a double-tap on the video. By default, if the video is smaller than the Window, it will be not stretched.
You can allow stretching by passing custom options to a Video instance:
player = VideoPlayer(source='myvideo.avi', state='play',
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 defaults to -1, and is set to the real duration when the video is loaded.
duration is a NumericProperty, default to -1.
- fullscreen¶
Switch to control 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 will add itself to it. When fullscreen is unset, all the previous children are restored, and the widget is reset to its previous parent.
Warning
The re-add operation doesn’t care about the index position of it’s children 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 a “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_stop¶
Image filename used for the “Stop” button. image_stop a StringProperty
- 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¶
Optional parameters can be passed to Video instance with this property.
options a DictProperty, default to {}
- play¶
Deprecated since version 1.4.0: Use state instead.
Boolean, indicates if the video is playing. You can start/stop the video by setting this property:
# start playing the video at creation video = Video(source='movie.mkv', play=True) # create the video, and start later video = Video(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 defaults to -1, and is set to the 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 has no impact.
- source¶
Source of the video to read.
source a StringProperty, default to ‘’. .. versionchanged:: 1.4.0
- 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 a OptionProperty, default to ‘play’.
- thumbnail¶
Thumbnail of the video to show. If None, VideoPlayer will try to find the thumbnail from the source + .png.
thumbnail a StringProperty, default to ‘’. .. versionchanged:: 1.4.0
- volume¶
Volume of the video, in the range 0-1. 1 means full volume, 0 means 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