avebi plays local video and live video streams in
Ebitengine applications. It decodes media through
go-ffmpeg-ffi,
presents decoded video through ebiten.Image, and feeds decoded audio to
Ebitengine's audio context.
- Local playback with play, pause, stop, seek, replay and looping.
- Optional synchronized audio with volume and mute controls.
- Video-only live stream playback with connection and read timeouts.
- Aspect-ratio-preserving rendering through
avebi.Draw. - Runtime FFmpeg loading through purego.
- Automatic platform-aware hardware decoding with software fallback.
- Optional GPU YUV-to-RGB conversion for 8-bit 4:2:0 video.
- Go 1.25 or newer.
- Ebitengine 2.9.9.
- FFmpeg 6.x, 7.x, 8.x or 9.x shared libraries available at runtime.
- A supported 64-bit target: Linux, macOS, Windows, Android or iOS on the architectures listed in the platform matrix.
The integration suite validates Linux amd64 with FFmpeg 6.1.6, 7.1.5, 8.1.2
and 9.0.1. Platform CI also validates native playback on the desktop targets
where GitHub provides runners and compiles Ebitengine bindings for Android and
iOS. Codec and container availability still depends on how the installed FFmpeg
libraries were built.
go get github.com/erparts/go-avebiAvebi depends directly on go-ffmpeg-ffi v1.1.2. Applications do not need a dependency override. See development and testing for the validated changes.
go-ffmpeg-ffi checks the platform's dynamic-library search path before standard system locations. Set it before starting the program and point it at a directory that contains only the FFmpeg family you want to load.
Linux:
LD_LIBRARY_PATH=/opt/ffmpeg-7/lib go run .macOS:
DYLD_LIBRARY_PATH=/opt/ffmpeg-7/lib go run .Windows PowerShell:
$env:PATH = "C:\ffmpeg-7\bin;$env:PATH"
go run .The path must be configured before process startup because go-ffmpeg-ffi initializes its bindings while Go packages are initialized. If one directory contains multiple families, go-ffmpeg-ffi prefers the newest supported family and verifies that all loaded libraries belong to the same ABI.
Android applications package unversioned libav*.so files in the APK or AAR.
iOS applications embed signed FFmpeg frameworks or link FFmpeg into the process
image. See platform support and packaging for the precise
validation level and mobile requirements.
Create the audio context before the player when audio playback is wanted. Files
without audio can use the same setup; ErrNoAudio simply leaves audio disabled.
package main
import (
"errors"
"log"
"os"
"github.com/erparts/go-avebi"
"github.com/hajimehoshi/ebiten/v2"
)
type game struct {
player *avebi.Player
frame *ebiten.Image
}
func (g *game) Update() error {
frame, err := g.player.CurrentFrame()
if err != nil {
return err
}
g.frame = frame
return g.player.Error()
}
func (g *game) Draw(screen *ebiten.Image) {
if g.frame != nil {
avebi.Draw(screen, g.frame)
}
}
func (*game) Layout(_, _ int) (int, int) { return 1280, 720 }
func main() {
path := os.Args[1]
if err := avebi.CreateAudioContextForMedia(path); err != nil && !errors.Is(err, avebi.ErrNoAudio) {
log.Fatal(err)
}
player, err := avebi.NewPlayer(path)
if err != nil {
log.Fatal(err)
}
defer player.Close()
if err := player.Play(); err != nil {
log.Fatal(err)
}
if err := ebiten.RunGame(&game{player: player}); err != nil {
log.Fatal(err)
}
}The player also exposes Pause, Stop, Seek, Position, Duration,
State, HasEnded, loop controls, and volume/mute controls. Use
NewPlayerWithOptions for further audio options.
For supported YUV420P, YUVJ420P and NV12 video, color conversion can run in an Ebitengine shader instead of FFmpeg's CPU scaler:
player, err := avebi.NewPlayerWithOptions(path, &avebi.PlayerOptions{
UseYUVShader: true,
})Unsupported pixel formats automatically fall back to the RGBA path. The shader uses explicit BT.709, FCC, BT.470BG, SMPTE 170M, SMPTE 240M and BT.2020 non-constant-luminance matrix metadata. Missing or unsupported matrix metadata also falls back to RGBA instead of guessing a conversion.
If the media and Ebitengine audio context use different sample rates,
NewPlayer converts the audio and reports the mismatch through the package
logger. Applications that prefer to reject the media can opt out:
player, err := avebi.NewPlayerWithOptions(path, &avebi.PlayerOptions{
RejectSampleRateMismatch: true,
})In that case, a mismatch returns ErrBadSampleRate with both sample rates in
the error message. GetMediaAudioSampleRate can be used to inspect a source
before opening a player.
For a video-only live stream:
player, err := avebi.NewStreamPlayer("rtsp://example.test/live")Connection and read deadlines can be configured with
NewStreamPlayerWithOptions.
go run ./examples/mediaplayer/desktop /path/to/video.mp4
go run ./examples/stream rtsp://example.test/liveThe desktop media player receives its file from the command line. Its Android
build reuses the same controls, diagnostics and playback lifecycle; only the
Android host with a file picker adds Open. See the
mediaplayer example for Android packaging. The examples
are instrumented for automated interaction but behave as ordinary Ebitengine
applications when that instrumentation is not enabled.
The H.265 benchmark measures decoding plus conversion to the RGBA buffers used
by Ebitengine. CPU uses the process convention, where 100% represents one
fully occupied logical CPU.
| Current v1.1.1 mode | x86 | Raspberry Pi 5 | Android SM-X210 |
|---|---|---|---|
| Software | 118.3 fps · 101.2% CPU | 52.21 fps · 100.7% CPU | 74.23 fps · 123.0% CPU |
| Hardware required | 127.4 fps · 86.35% CPU (CUDA) | 123.3 fps · 88.43% CPU (DRM/rpivid) | 109.7 fps · 114.7% CPU (MediaCodec) |
For reference, software decoding in the current version improves on the former v0.0.7 Reisen backend as follows:
| Platform | v0.0.7 / Reisen | Current v1.1.1 | Throughput gain |
|---|---|---|---|
| x86 | 93.39 fps | 118.3 fps | +26.7% |
| Raspberry Pi 5 | 36.66 fps | 52.21 fps | +42.4% |
The v1 backend also reduces allocations from approximately 4.616 GiB to 8.3–8.5 MiB per clip. These are decode and RGBA conversion figures, not physical-display frame rates. See the full benchmark report for memory, methodology, and stability results.
- Live streams are video-only.
- Hardware-decoded video is transferred to CPU-accessible frames. The optional shader uploads YUV instead of RGBA, but zero-copy GPU presentation is not implemented.
- The shader uses nearest-neighbor chroma upsampling. Saturated color edges can therefore show 2x2 chroma blocks that the bilinear RGBA path smooths.
- Packed 4:2:0 storage makes the shader texture 1.5 times the video height, so the maximum supported video height is roughly two-thirds of the GPU's maximum texture dimension. The RGBA fallback does not have this height overhead.
- Packed YUV is uploaded as opaque byte storage through
WritePixels; this relies on Ebitengine preserving channel bytes even when they are not valid premultiplied-alpha colors. - Mobile applications must package their own compatible FFmpeg libraries.
See development and testing for the compatibility matrix, platform checks and stress-test commands.
Avebi is available under the MIT License.