flet-video: add mpv_properties to VideoConfiguration

[Dejv311]

Description

Added the option for flet_video to accept MPV parameters by passing them through media_kit flutter package. This is needed in scenarios, where the default configuration is unable to play the selected media.

Test Code

Showing a real-time video stream from a capture device on Linux (with v4l2).

import flet as ft
import flet_video as fv

def main(page: ft.Page):
    page.add(ft.Text("Video test"))
    page.add(
        fv.Video(
            playlist=[fv.VideoMedia("/dev/video0")],
            autoplay=True,
            show_controls=True,
            configuration=fv.VideoConfiguration(
                mpv_properties={
                    "demuxer-lavf-format": "video4linux2",
                    "demuxer-lavf-o": "input_format=mjpeg,video_size=1600x1200,framerate=30",
                    "profile": "low-latency",
                    "untimed": "yes",
                }
            ),
            width=720,
            height=360,
        )
    )

ft.app(main)

Type of change

• New feature (non-breaking change which adds functionality)
• This change requires a documentation update

Checklist

• I signed the CLA.
• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• My changes generate no new warnings
• New and existing tests pass locally with my changes
• I have made corresponding changes to the documentation (if applicable)

[CLAassistant]

All committers have signed the CLA.

[sourcery-ai]

We've reviewed this pull request using the Sourcery rules engine

[ndonkoHenri]

Is mpv not Linux-only? (ref)

Also, can you please share a link to docs of these properties?

[Dejv311]

Hello @ndonkoHenri , thank you for your comments.

The libmpv is internally used for everything but web as far as I am aware. The Flet docs mention it here:

https://docs.flet.dev/video/types/video_configuration/#flet_video.VideoConfiguration.hardware_decoding_api

The media_kit github shows the diagram splitting between NativePlayer and WebPlayer:

https://github.com/media-kit/media-kit?tab=readme-ov-file#packagemedia_kit-1

This site seems to mention the parameters, though I used mpv -h on my machine.

https://mpv.io/manual/stable/

I am unable to test other systems but Linux as I do not use other OSs.

[ndonkoHenri]

Ah, I never knew their Github provided more detailed infos than their pub.dev page.

The libmpv is internally used for everything but web

Yeah, you are right from what I see.

Can you please add the link to the properties (https://mpv.io/manual/stable/#options) in this docstring too? And perhaps mention how they get translated. For ex: --hdr-compute-peak becomes key hdr-compute-peak, with possible value "yes" or boolean True...

I am unable to test other systems but Linux as I do not use other OSs.

Will see if I can test it on macOS later on.

[ndonkoHenri]

quick developer survey :)
Since you are on Linux, can you please tell me if you faced any issues while trying to play videos using flet+flet-video packages?

[bl1nch]

flet-dev/flet-video#3

[Dejv311]

quick developer survey :) Since you are on Linux, can you please tell me if you faced any issues while trying to play videos using flet+flet-video packages?

The transition from 0.28 to 0.80 forced me to install a new OS. Flet 0.28 needed libmpv1, whereas Flet 0.80 requires libmpv2, which I was unable to install on my Ubuntu 22.04. Updating to Ubuntu 25.04 solved the issue.

The video example works on Linux just fine, though where I found a mismatch is in local files. flet run linux does not use assets as the root directory (instead it uses the system root), but flet run web seeks the files in the assets folder. This introduces a mismatch in behavior and needs to be accounted for on per-system basis. EDIT: I tried putting the video in the system root and it was not found - it always needs the full path - relative paths just seem to not work.

Other than that it all seems to work just fine :).

[Copilot]

Pull request overview

This PR adds support for custom MPV properties to the flet-video package, enabling users to pass advanced configuration parameters to the underlying media_kit/MPV player. This is particularly useful for scenarios where default playback configuration is insufficient, such as streaming from capture devices.

Changes:

• Added mpv_properties field to VideoConfiguration dataclass in Python to accept custom MPV parameters
• Implemented _applyMpvProperties method in Dart to apply these properties to the native player before media playback
• Modified player initialization flow to apply MPV properties before opening the playlist

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 5 comments.

File	Description
sdk/python/packages/flet-video/src/flet_video/types.py	Added mpv_properties field to VideoConfiguration dataclass with documentation and examples
sdk/python/packages/flet-video/src/flutter/flet_video/lib/src/video.dart	Implemented _applyMpvProperties method and integrated it into the player setup flow

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The documentation states "All values are converted to String" but the implementation only converts boolean values to "yes"/"no" and uses toString() for other types. This could be misleading since numeric values (int, float) will be converted using their default toString() representation, which may or may not match MPV's expected format for certain properties.

Consider clarifying in the documentation that numeric values are converted using their standard string representation, or add examples showing how different value types are converted.

Suggested change

	All values are converted to String. Boolean values are converted to `yes`/`no`.
	See the full list of parameters: https://mpv.io/manual/stable/#options
	Example:
	`{
	'profile': 'low-latency',
	'untimed': True,
	All values are converted to strings using their standard Python string representation (for example, `str(42)` -> `"42"`, `str(0.5)` -> `"0.5"`).
	Boolean values are converted to `"yes"`/`"no"` to match mpv's expected format.
	See the full list of parameters: https://mpv.io/manual/stable/#options
	Example:
	`{
	'profile': 'low-latency',
	'untimed': True,
	'volume': 50,

[Copilot]

Casting the NativePlayer to dynamic bypasses Dart's type safety and could lead to runtime errors if the setProperty method signature changes or doesn't exist. The code assumes that NativePlayer has a setProperty method available through dynamic invocation, but this is not type-safe.

Consider checking if the media_kit package provides a proper typed interface for setting properties, or add proper error handling around the dynamic method call to catch potential runtime errors.

Suggested change

	final native = platform as dynamic;
	for (final entry in mpvPropsRaw.entries) {
	final key = entry.key.toString();
	final val = entry.value;
	if (val == null) continue;
	final valueStr = val is bool ? (val ? "yes" : "no") : val.toString();
	await native.setProperty(key, valueStr);
	final native = platform;
	for (final entry in mpvPropsRaw.entries) {
	final key = entry.key.toString();
	final val = entry.value;
	if (val == null) continue;
	final valueStr = val is bool ? (val ? "yes" : "no") : val.toString();
	try {
	await (native as dynamic).setProperty(key, valueStr);
	} catch (e, stackTrace) {
	debugPrint(
	'Error setting MPV property "$key" to "$valueStr": $e\n$stackTrace',
	);
	}