Skip to main content

Media Player

The media plugin provides native media playback. Add it to drift.yaml:

plugins:
- package: github.com/go-drift/drift/plugins/media/plugin

and import its Go API as media "github.com/go-drift/drift/plugins/media/runtime". The plugin's section lists its config (DASH on Android).

Up to Drift v0.26 these types were core: platform.VideoPlayerController, platform.AudioPlayerController, platform.PlaybackState and the widgets.VideoPlayer widget. In the media package the controllers publish playback as state instead of callbacks: OnPlaybackStateChanged and OnPositionChanged became State() and Progress(), OnError became the Errors() stream with the media.ErrSource, ErrDecoder and ErrPlaybackFailed sentinels in place of the ErrCode* strings, and NewVideoPlayerController returns an error.

The plugin has two APIs: the VideoPlayerController for embedded video with platform controls, and the AudioPlayerController for headless audio playback with a custom UI. Audio and video controllers share the same method set but are separate types. The video controller creates its native surface eagerly on construction, while the audio controller defers native player creation until the first method call.

Each controller publishes:

  • State(), a *core.Derived[media.PlaybackState], and Progress(), a *core.Derived[media.Progress] (position, duration and buffered length: about every 250ms while media is loaded, playing or paused, and at once when the state changes or a seek moves the position, Stop included). Both change on the UI thread, so core.UseListenable rebuilds a widget on them.
  • Errors(), a *platform.Stream[error] of playback failures. Like every stream, its handlers run off the UI thread: update widget state inside drift.Dispatch.

Video Player​

The VideoPlayer widget embeds a native video player (ExoPlayer on Android, AVPlayer on iOS) with built-in transport controls including play/pause, seek bar, and time display.

Create a VideoPlayerController, subscribe to what the widget shows, and pass it to the widget:

import (
"log"
"time"

"github.com/go-drift/drift/pkg/core"
"github.com/go-drift/drift/pkg/drift"
"github.com/go-drift/drift/pkg/platform"
"github.com/go-drift/drift/pkg/theme"
"github.com/go-drift/drift/pkg/widgets"
media "github.com/go-drift/drift/plugins/media/runtime"
)

type playerState struct {
core.StateBase
controller *media.VideoPlayerController
failure *core.Signal[string]
}

func (s *playerState) InitState() {
controller, err := media.NewVideoPlayerController()
if err != nil {
log.Printf("video: %v", err) // the media plugin is missing, say
return
}
s.controller = controller
core.UseDisposable(&s.StateBase, controller)
core.UseListenable(&s.StateBase, controller.State())
core.UseListenable(&s.StateBase, controller.Progress())

s.failure = core.NewSignal("")
core.UseListenable(&s.StateBase, s.failure)
s.OnDispose(controller.Errors().Listen(platform.StreamHandler[error]{
OnEvent: func(err error) {
drift.Dispatch(func() { s.failure.Set(err.Error()) })
},
}))

controller.Load("https://example.com/video.mp4")
}

func (s *playerState) Build(ctx core.BuildContext) core.Widget {
if s.controller == nil {
return widgets.Text{Content: "Video unavailable"}
}
progress := s.controller.Progress().Value()
return widgets.Column{
Children: []core.Widget{
media.VideoPlayer{
Controller: s.controller,
Height: 225,
},
widgets.Text{Content: s.controller.State().Value().String() + " " +
progress.Position.String() + " / " + progress.Duration.String() + " " + s.failure.Value()},
widgets.Row{
Children: []core.Widget{
theme.ButtonOf(ctx, "Pause", func() {
s.controller.Pause()
}),
theme.ButtonOf(ctx, "Seek +10s", func() {
s.controller.SeekTo(progress.Position + 10*time.Second)
}),
},
},
},
}
}

NewVideoPlayerController fails when the native player cannot be created: the media plugin is missing from drift.yaml, or the platform could not make the player.

Width and Height set explicit dimensions in logical pixels. To fill available width, wrap the widget in layout widgets such as Expanded inside a Row:

widgets.Row{
Children: []core.Widget{
widgets.Expanded{
Child: media.VideoPlayer{
Controller: s.controller,
Height: 225,
},
},
},
}

Subscribe to Errors() before calling Load: a failure is an event, delivered only to the subscribers present when it happens. State() and Progress() are state, so their current values are always at hand.

UseDisposable registers a dispose callback automatically, so the controller is released when the widget is removed from the tree. Disposing a controller that is still buffering silently cancels playback; nothing changes after that. For non-widget contexts (tests, standalone services), use media.NewVideoPlayerController() directly and call Dispose() manually.

VideoPlayer Widget Fields​

FieldTypeDescription
Controller*media.VideoPlayerControllerThe controller that provides the native surface and playback control
Widthfloat64Player width in logical pixels
Heightfloat64Player height in logical pixels
HideControlsboolHide native transport controls. Use when building custom Drift widget controls on top of the video surface.

VideoPlayerController Methods​

All methods are safe for concurrent use.

MethodDescription
Load(url string) errorLoad a media URL. The native player begins buffering the media source.
Play() errorStart or resume playback
Pause() errorPause playback
Stop() errorStop playback and reset to idle. Media stays loaded; calling Play restarts from the beginning. Use Dispose to release resources.
SeekTo(position time.Duration) errorSeek to a position
SetVolume(volume float64) errorSet volume (0.0 to 1.0). Values outside this range are clamped by the native player.
SetLooping(looping bool) errorEnable or disable looping
SetPlaybackSpeed(rate float64) errorSet playback speed (1.0 = normal). Must be positive; behavior for zero or negative values is platform-dependent.
SetShowControls(show bool) errorShow or hide native transport controls at runtime.
State() *core.Derived[PlaybackState]Playback state, changing on the UI thread
Progress() *core.Derived[Progress]Position, duration and buffered length, changing on the UI thread about every 250ms while media is loaded
Errors() *platform.Stream[error]Playback failures, matching ErrSource, ErrDecoder or ErrPlaybackFailed
ViewID() int64Platform view ID, or 0 if the view was not created
Dispose()Release native resources. Later calls return platform.ErrDisposed; idempotent.

Audio Player​

AudioPlayerController provides audio playback without a visual component. It uses a standalone platform channel, so there is no embedded native view. Build your own UI around the controller.

Multiple controllers may exist concurrently, each managing its own native player instance. Call Dispose to release resources when a controller is no longer needed.

import (
"log"
"time"

"github.com/go-drift/drift/pkg/core"
"github.com/go-drift/drift/pkg/platform"
"github.com/go-drift/drift/pkg/theme"
"github.com/go-drift/drift/pkg/widgets"
media "github.com/go-drift/drift/plugins/media/runtime"
)

type audioState struct {
core.StateBase
controller *media.AudioPlayerController
}

func (s *audioState) InitState() {
s.controller = media.NewAudioPlayerController()
core.UseDisposable(&s.StateBase, s.controller)
core.UseListenable(&s.StateBase, s.controller.State())
core.UseListenable(&s.StateBase, s.controller.Progress())
s.OnDispose(s.controller.Errors().Listen(platform.StreamHandler[error]{
OnEvent: func(err error) { log.Printf("audio: %v", err) },
}))

s.controller.Load("https://example.com/song.mp3")
}

Subscribe to Errors() before calling Load, as for video.

UseDisposable registers a dispose callback automatically, so the controller is released when the widget is removed from the tree. Disposing a controller that is still buffering silently cancels playback; nothing changes after that. For non-widget contexts (tests, standalone services), use media.NewAudioPlayerController() directly and call Dispose() manually.

AudioPlayerController Methods​

All methods are safe for concurrent use.

MethodDescription
Load(url string) errorLoad a media URL. The native player begins buffering the media source.
Play() errorStart or resume playback
Pause() errorPause playback
Stop() errorStop playback and reset to idle. Media stays loaded; calling Play restarts from the beginning. Use Dispose to release resources.
SeekTo(position time.Duration) errorSeek to a position
SetVolume(volume float64) errorSet volume (0.0 to 1.0). Values outside this range are clamped by the native player.
SetLooping(looping bool) errorEnable or disable looping
SetPlaybackSpeed(rate float64) errorSet playback speed (1.0 = normal). Must be positive; behavior for zero or negative values is platform-dependent.
State() *core.Derived[PlaybackState]Playback state, changing on the UI thread
Progress() *core.Derived[Progress]Position, duration and buffered length, changing on the UI thread about every 250ms while media is loaded
Errors() *platform.Stream[error]Playback failures, matching ErrSource, ErrDecoder or ErrPlaybackFailed
Dispose()Release native resources. Later calls return platform.ErrDisposed; idempotent.

Example: Transport Controls with Seek​

func (s *audioState) Build(ctx core.BuildContext) core.Widget {
return widgets.Column{
Children: []core.Widget{
widgets.Text{Content: s.controller.State().Value().String()},
widgets.Row{
Children: []core.Widget{
theme.ButtonOf(ctx, "Play", func() {
s.controller.Play()
}),
theme.ButtonOf(ctx, "Pause", func() {
s.controller.Pause()
}),
theme.ButtonOf(ctx, "Stop", func() {
s.controller.Stop()
}),
},
},
widgets.Row{
Children: []core.Widget{
theme.ButtonOf(ctx, "Seek +10s", func() {
pos := s.controller.Progress().Value().Position
s.controller.SeekTo(pos + 10*time.Second)
}),
theme.ButtonOf(ctx, "Loop", func() {
s.controller.SetLooping(true)
}),
theme.ButtonOf(ctx, "Mute", func() {
s.controller.SetVolume(0)
}),
},
},
},
}
}

Playback States​

Both video and audio players share the same PlaybackState enum (defined in media). Use the String() method for human-readable labels.

StateValueDescription
PlaybackStateIdle0Player created, no media loaded
PlaybackStateBuffering1Buffering media data before playback can continue
PlaybackStatePlaying2Actively playing media
PlaybackStateCompleted3Playback reached the end of the media
PlaybackStatePaused4Paused, can be resumed

Failures arrive on Errors(), not as a playback state; the player goes idle after one.

Errors​

Control methods like Load and Play return an error that indicates a communication failure with the native player (for example, calling a method after disposal). Errors() streams playback-time failures the native player reports, such as network failures or unsupported codecs, the same on Android and iOS:

SentinelWire codeMeaning
media.ErrSourcesource_errorMedia source could not be loaded (network failure, invalid URL, unsupported format)
media.ErrDecoderdecoder_errorMedia could not be decoded or rendered (codec failure, DRM error)
media.ErrPlaybackFailedplayback_failedGeneral playback failure that does not fit a more specific category
controller.Errors().Listen(platform.StreamHandler[error]{OnEvent: func(err error) {
switch {
case errors.Is(err, media.ErrSource):
// Network or URL issue, prompt user to check connection
case errors.Is(err, media.ErrDecoder):
// Format not supported on this device
}
log.Printf("playback error: %v", err) // includes the platform's message
}})

Custom Controls​

To build your own playback controls in Drift widgets, set HideControls: true on the VideoPlayer widget. This hides the native transport UI (play/pause button, seek bar, time display) and leaves a bare video surface that you can overlay with Drift widgets using Stack and Positioned:

widgets.Stack{
Children: []core.Widget{
media.VideoPlayer{
Controller: s.controller,
Height: 300,
HideControls: true,
},
widgets.Positioned(widgets.Row{
Children: []core.Widget{
theme.ButtonOf(ctx, "Play", func() {
s.controller.Play()
}),
theme.ButtonOf(ctx, "Pause", func() {
s.controller.Pause()
}),
},
}).Bottom(8).Left(8),
},
}

You can also toggle controls at runtime via the controller:

s.controller.SetShowControls(false) // hide
s.controller.SetShowControls(true) // show again

Cleartext HTTP URLs​

Android (API 28+) and iOS block cleartext HTTP traffic by default. If you load an http:// URL, the native player will report a source_error. HTTPS URLs work without any extra configuration.

To allow HTTP URLs, set allow_http: true in your drift.yaml:

app:
allow_http: true

This adds android:usesCleartextTraffic="true" to the Android manifest and an NSAppTransportSecurity exception to the iOS Info.plist. Use HTTPS whenever possible and only enable this setting when your media source does not support it.

tip

UseDisposable is documented in the State Management guide.

Next Steps​