Video
video is a host primitive, not an element the renderer can
paint by walking children. On desktop and Android a native player decodes
the stream off the UI thread and publishes frames as textures; layout treats
the element as replaced content and the host paints the transport controls.
Why it is special
| Concern | How Donkeh handles it |
|---|---|
| Decoding | Uses LibVLCSharp. Initialisation, demuxing, decoding and I/O run on worker threads. |
| Presentation | Decoded frames are copied into the window's image cache as a dynamic texture, then drawn through the normal image path. The most recent frame is reused until the next one arrives. |
| Layout | The element is replaced content with a default 300 × 150 box. CSS width, height, aspect ratio and object-fit apply to the frame. |
| Chrome | When controls is present, the host paints and hit-tests its own play/pause, scrubber, time and volume controls. They are not DOM elements and cannot be styled individually. |
| Lifecycle | One player per element. Players are created asynchronously, updated when attributes change, and pruned when the element leaves the tree. |
This is why video needs a typed props object and a native
dependency. A plain H("video", ...) still works because
VideoProps derives from Props, but the typed
OnReady callback is only available through it.
Basic playback
using Donkeh.UILab;
using Donkeh.Windowing;
using static Donkeh.UILab.HtmlHelper;
using static Donkeh.UILab._;
public sealed class Clip : Component
{
public override Node Render() =>
H("video", new VideoProps
{
Src = "media/intro.mp4",
Controls = true,
AutoPlay = true,
Loop = true,
Muted = true,
Volume = 0.8f,
OnReady = player =>
{
// Save the player, or seek to a chapter once it exists.
player.Seek(12.5f);
},
OnTimeUpdate = seconds =>
Console.WriteLine($"position: {seconds:0.0}s"),
OnEnded = () => Console.WriteLine("finished")
});
LibVLCSharp package does not replace the native
LibVLC runtime. Install VLC or ship the matching native libraries with the
app. If LibVLC cannot be initialised, the element still lays out but no
frames or controls become available.
Playback props
| Prop | Attribute | Effect |
|---|---|---|
Src | src | Media URL or file path. Changing it replaces the player. |
Controls | controls | Paints the host transport controls. |
AutoPlay / Autoplay | autoplay | Starts playback as soon as the player exists. |
Loop | loop | Restarts at the end instead of stopping. |
Muted | muted | Starts with audio muted. |
Volume | volume | Initial volume in the 0–1 range. |
PlaybackRate | playbackrate | Initial speed multiplier. One is normal. |
OnPlay, OnPause, OnEnded | — | Lifecycle callbacks driven by the host. |
OnTimeUpdate | — | Receives the current position in seconds. |
OnReady | — | Receives a VideoPlayer once creation succeeds. |
Driving the player
OnReady gives you the window-side control surface. Keep it in a
field or ref if an event handler needs it later.
public sealed class PlayerControls : Component
{
private VideoPlayer? _player;
public override Node Render()
{
var playing = _player?.IsPlaying == true;
return Div(new() { ClassName = "transport" },
H("video", new VideoProps
{
Src = "media/demo.mp4",
OnReady = player => _player = player
}),
Button(new()
{
OnClick = () => _player?.Play()
}, Text("Play")),
Button(new()
{
OnClick = () => _player?.Pause()
}, Text("Pause")));
}
}
| Member | Purpose |
|---|---|
Play(), Pause(), Stop() | Transport control. |
Seek(float seconds), Seek(TimeSpan) | Seek to an absolute position. Returns whether the seek was accepted. |
IsPlaying, Time, Duration | Current transport state, in seconds where applicable. |
Volume, IsMuted, PlaybackRate | Audio and rate control. |
IsLooping | Reads the loop state of the underlying player. |
PlaybackEnded | Event raised when playback reaches the end without looping. |
Browser host
On WebAssembly the element is a native HTML video element. The
browser owns decoding, controls and the media APIs, so
OnReady, VideoPlayer and the host-painted transport
controls are desktop/Android features. Use standard attributes such as
src, controls, autoplay,
loop and muted; the browser applies its own policy
for autoplay and audio.