Skip to main content

Video

Embed a full-featured video player in your Flet app with playlist support, hardware acceleration controls, and subtitle configuration.

It is powered by the media_kit Flutter package.

Platform Support​

PlatformWindowsmacOSLinuxiOSAndroidWeb
Supported✅✅✅✅✅✅

Usage​

Add the flet-video package to your project dependencies:

uv add flet-video

Requirements​

The below sections show the required configurations for each platform.

Android​

You may need to declare and request file-system/storage permissions, depending on your use case:

flet build apk \
  --android-permissions android.permission.READ_MEDIA_AUDIO=true \
  --android-permissions android.permission.READ_MEDIA_VIDEO=true \
  --android-permissions android.permission.READ_EXTERNAL_STORAGE=true \
  --android-permissions android.permission.WRITE_EXTERNAL_STORAGE=true

Use PermissionHandler to request permissions at runtime.

See also:

Linux​

libmpv libraries must be installed and present on the machine running the app.

On Ubuntu/Debian, this can be done with:

sudo apt install libmpv-dev mpv

If you encounter libmpv.so.1 load errors, run:

sudo apt update
sudo apt install libmpv-dev libmpv2
sudo ln -s /usr/lib/x86_64-linux-gnu/libmpv.so /usr/lib/libmpv.so.1

Examples​

Basic example​

import random

import flet as ft
import flet_video as ftv

sample_media = [
    ftv.VideoMedia(
        "https://user-images.githubusercontent.com/28951144/229373720-14d69157-1a56-4a78-a2f4-d7a134d7c3e9.mp4"
    ),
    ftv.VideoMedia(
        "https://user-images.githubusercontent.com/28951144/229373718-86ce5e1d-d195-45d5-baa6-ef94041d0b90.mp4"
    ),
    ftv.VideoMedia(
        "https://user-images.githubusercontent.com/28951144/229373716-76da0a4e-225a-44e4-9ee7-3e9006dbc3e3.mp4"
    ),
    ftv.VideoMedia(
        "https://user-images.githubusercontent.com/28951144/229373695-22f88f13-d18f-4288-9bf1-c3e078d83722.mp4"
    ),
    ftv.VideoMedia(
        "https://user-images.githubusercontent.com/28951144/229373709-603a7a89-2105-4e1b-a5a5-a6c3567c9a59.mp4",
        extras={
            "artist": "Thousand Foot Krutch",
            "album": "The End Is Where We Begin",
        },
        http_headers={
            "Foo": "Bar",
            "Accept": "*/*",
        },
    ),
]


def main(page: ft.Page):
    page.spacing = 20
    page.horizontal_alignment = ft.CrossAxisAlignment.CENTER

    async def handle_pause(e: ft.Event[ft.Button]):
        await video.pause()

    async def handle_play_or_pause(e: ft.Event[ft.Button]):
        await video.play_or_pause()

    async def handle_play(e: ft.Event[ft.Button]):
        await video.play()

    async def handle_stop(e: ft.Event[ft.Button]):
        await video.stop()

    async def handle_next(e: ft.Event[ft.Button]):
        await video.next()

    async def handle_previous(e: ft.Event[ft.Button]):
        await video.previous()

    def handle_volume_change(e: ft.Event[ft.Slider]):
        video.volume = e.control.value

    def handle_playback_rate_change(e: ft.Event[ft.Slider]):
        video.playback_rate = e.control.value

    async def handle_seek(e: ft.Event[ft.Button]):
        await video.seek(10000)

    async def handle_add_media(e: ft.Event[ft.Button]):
        await video.playlist_add(random.choice(sample_media))

    async def handle_remove_media(e: ft.Event[ft.Button]):
        r = random.randint(0, len(video.playlist) - 1)
        await video.playlist_remove(r)

    async def handle_jump(e: ft.Event[ft.Button]):
        await video.jump_to(0)

    async def handle_fullscreen(e: ft.Event[ft.Button]):
        video.fullscreen = True

    page.add(
        ft.SafeArea(
            expand=True,
            content=ft.Column(
                expand=True,
                controls=[
                    video := ftv.Video(
                        expand=True,
                        playlist=sample_media[0:2],
                        playlist_mode=ftv.PlaylistMode.LOOP,
                        fill_color=ft.Colors.BLUE_400,
                        aspect_ratio=16 / 9,
                        volume=100,
                        autoplay=False,
                        filter_quality=ft.FilterQuality.HIGH,
                        muted=False,
                        on_load=lambda e: print("Video loaded successfully!"),
                        on_enter_fullscreen=lambda e: print("Entered fullscreen!"),
                        on_exit_fullscreen=lambda e: print("Exited fullscreen!"),
                    ),
                    ft.Row(
                        wrap=True,
                        alignment=ft.MainAxisAlignment.CENTER,
                        controls=[
                            ft.Button("Play", on_click=handle_play),
                            ft.Button("Pause", on_click=handle_pause),
                            ft.Button("Play Or Pause", on_click=handle_play_or_pause),
                            ft.Button("Stop", on_click=handle_stop),
                            ft.Button("Next", on_click=handle_next),
                            ft.Button("Previous", on_click=handle_previous),
                            ft.Button("Seek s=10", on_click=handle_seek),
                            ft.Button("Jump to first Media", on_click=handle_jump),
                            ft.Button("Add Random Media", on_click=handle_add_media),
                            ft.Button(
                                "Remove Random Media", on_click=handle_remove_media
                            ),
                            ft.Button("Enter Fullscreen", on_click=handle_fullscreen),
                        ],
                    ),
                    ft.Slider(
                        min=0,
                        value=100,
                        max=100,
                        label="Volume = {value}%",
                        divisions=10,
                        width=400,
                        on_change=handle_volume_change,
                    ),
                    ft.Slider(
                        min=1,
                        value=1,
                        max=3,
                        label="Playback rate = {value}X",
                        divisions=6,
                        width=400,
                        on_change=handle_playback_rate_change,
                    ),
                ],
            ),
        )
    )


if __name__ == "__main__":
    ft.run(main)

Description​

A control that displays a video from a playlist.

Inherits: LayoutControl

Properties

  • alignment - Defines the Alignment of the viewport.
  • autoplay - Whether the video should start playing automatically.
  • configuration - Additional configuration for the video player.
  • fill_color - Defines the color used to fill the video background.
  • filter_quality - Filter quality of the texture used to render the video output.
  • fit - The box fit to use for the video.
  • fullscreen - Whether the video player is presented in fullscreen mode.
  • muted - Defines whether the video player should be started in muted state.
  • pause_upon_entering_background_mode - Whether to pause the video when application enters background mode.
  • pitch - Defines the relative pitch of the video player.
  • playback_rate - Defines the playback rate of the video player.
  • playlist - A list of VideoMedias representing the video files to be played.
  • playlist_mode - Represents the mode of playback for the playlist.
  • resume_upon_entering_foreground_mode - Whether to resume the video when application enters foreground mode.
  • show_controls - Whether to show the video player controls.
  • shuffle_playlist - Defines whether the playlist should be shuffled.
  • subtitle_configuration - Defines the subtitle configuration for the video player.
  • subtitle_track - Defines the subtitle track for the video player.
  • title - Defines the name of the underlying window & process for native backend.
  • volume - Defines the volume of the video player.
  • wakelock - Whether to acquire wake lock while playing the video.

Events

Methods

  • get_current_position - Returns: The current position of the currently playing media.
  • get_duration - Returns: The duration of the currently playing media.
  • is_completed - Returns: True if video player has reached the end of the currently playing media, False otherwise.
  • is_playing - Returns: True if the video player is currently playing, False otherwise.
  • jump_to - Jumps to the VideoMedia at the specified media_index in the playlist.
  • next - Jumps to the next VideoMedia in the playlist.
  • pause - Pauses the video player.
  • play - Starts playing the video.
  • play_or_pause - Cycles between play and pause states of the video player, i.e., plays if paused and pauses if playing.
  • playlist_add - Appends/Adds the provided media to the playlist.
  • playlist_remove - Removes the provided media from the playlist.
  • previous - Jumps to the previous VideoMedia in the playlist.
  • seek - Seeks the currently playing VideoMedia from the playlist at the specified position.
  • stop - Stops the video player.

Properties​

alignmentclass-attributeinstance-attribute​

alignment: Alignment = field(default_factory=(lambda: Alignment.CENTER))

Defines the Alignment of the viewport.

autoplayclass-attributeinstance-attribute​

autoplay: bool = False

Whether the video should start playing automatically.

configurationclass-attributeinstance-attribute​

configuration: VideoConfiguration = field(default_factory=(lambda: VideoConfiguration()))

Additional configuration for the video player.

fill_colorclass-attributeinstance-attribute​

fill_color: ColorValue = Colors.BLACK

Defines the color used to fill the video background.

filter_qualityclass-attributeinstance-attribute​

filter_quality: FilterQuality = FilterQuality.LOW

Filter quality of the texture used to render the video output.

Note

Android was reported to show blurry images when using flet.FilterQuality.HIGH. Prefer the usage of flet.FilterQuality.MEDIUM on this platform.

fitclass-attributeinstance-attribute​

fit: BoxFit = BoxFit.CONTAIN

The box fit to use for the video.

fullscreenclass-attributeinstance-attribute​

fullscreen: bool = False

Whether the video player is presented in fullscreen mode.

Set to True to enter fullscreen or False to exit fullscreen programmatically.

mutedclass-attributeinstance-attribute​

muted: bool = False

Defines whether the video player should be started in muted state.

pause_upon_entering_background_modeclass-attributeinstance-attribute​

pause_upon_entering_background_mode: bool = True

Whether to pause the video when application enters background mode.

pitchclass-attributeinstance-attribute​

pitch: Number = 1.0

Defines the relative pitch of the video player.

playback_rateclass-attributeinstance-attribute​

playback_rate: Number = 1.0

Defines the playback rate of the video player.

playlistclass-attributeinstance-attribute​

playlist: list[VideoMedia] = field(default_factory=list)

A list of VideoMedias representing the video files to be played.

playlist_modeclass-attributeinstance-attribute​

playlist_mode: Optional[PlaylistMode] = None

Represents the mode of playback for the playlist.

resume_upon_entering_foreground_modeclass-attributeinstance-attribute​

resume_upon_entering_foreground_mode: bool = False

Whether to resume the video when application enters foreground mode. Has effect only if pause_upon_entering_background_mode is also set to True.

show_controlsclass-attributeinstance-attribute​

show_controls: bool = True

Whether to show the video player controls.

shuffle_playlistclass-attributeinstance-attribute​

shuffle_playlist: bool = False

Defines whether the playlist should be shuffled.

subtitle_configurationclass-attributeinstance-attribute​

subtitle_configuration: VideoSubtitleConfiguration = field(default_factory=(lambda: VideoSubtitleConfiguration()))

Defines the subtitle configuration for the video player.

subtitle_trackclass-attributeinstance-attribute​

subtitle_track: Optional[VideoSubtitleTrack] = None

Defines the subtitle track for the video player.

titleclass-attributeinstance-attribute​

title: str = 'flet-video'

Defines the name of the underlying window & process for native backend. This is visible inside the windows' volume mixer.

volumeclass-attributeinstance-attribute​

volume: Number = 100.0

Defines the volume of the video player.

Note

It's value ranges between 0.0 to 100.0 (inclusive), where 0.0 is muted and 100.0 is the maximum volume. An exception will be raised if the value is outside this range.

Raises:

  • ValueError - If its value is not between 0.0 and 100.0 (inclusive).

wakelockclass-attributeinstance-attribute​

wakelock: bool = True

Whether to acquire wake lock while playing the video. When True, device's display will not go to standby/sleep while the video is playing.

Events​

on_completeclass-attributeinstance-attribute​

on_complete: Optional[ControlEventHandler[Video]] = None

Fires when a video player completes.

on_enter_fullscreenclass-attributeinstance-attribute​

on_enter_fullscreen: Optional[ControlEventHandler[Video]] = None

Fires when the video player enters fullscreen.

on_errorclass-attributeinstance-attribute​

on_error: Optional[ControlEventHandler[Video]] = None

Fires when an error occurs.

Event handler argument's data property contains information about the error.

on_exit_fullscreenclass-attributeinstance-attribute​

on_exit_fullscreen: Optional[ControlEventHandler[Video]] = None

Fires when the video player exits fullscreen

on_loadclass-attributeinstance-attribute​

on_load: Optional[ControlEventHandler[Video]] = None

Fires when the video player is initialized and ready for playback.

on_track_changeclass-attributeinstance-attribute​

on_track_change: Optional[ControlEventHandler[Video]] = None

Fires when a video track changes.

Event handler argument's data property contains the index of the new track.

Methods​

get_current_positionasync​

get_current_position()

Returns:

  • Duration - The current position of the currently playing media.

get_durationasync​

get_duration()

Returns:

  • Duration - The duration of the currently playing media.

is_completedasync​

is_completed()

Returns:

  • bool - True if video player has reached the end of the currently playing media, False otherwise.

is_playingasync​

is_playing()

Returns:

  • bool - True if the video player is currently playing, False otherwise.

jump_toasync​

jump_to(media_index: int)

Jumps to the VideoMedia at the specified media_index in the playlist.

nextasync​

next()

Jumps to the next VideoMedia in the playlist.

pauseasync​

pause()

Pauses the video player.

playasync​

play()

Starts playing the video.

play_or_pauseasync​

play_or_pause()

Cycles between play and pause states of the video player, i.e., plays if paused and pauses if playing.

playlist_addasync​

playlist_add(media: VideoMedia)

Appends/Adds the provided media to the playlist.

playlist_removeasync​

playlist_remove(media_index: int)

Removes the provided media from the playlist.

previousasync​

previous()

Jumps to the previous VideoMedia in the playlist.

seekasync​

seek(position: DurationValue)

Seeks the currently playing VideoMedia from the playlist at the specified position.

stopasync​

stop()

Stops the video player.