Skip to content
bstkhqPublic

About

Avebi plays local video and live video streams in Ebitengine applications.

Resources

Stars

2 stars

Watchers

1 watching

Forks

Repository files navigation

avebi

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.

Features

  • 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.

Requirements and compatibility

  • 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.

Installation

go get github.com/erparts/go-avebi

Avebi depends directly on go-ffmpeg-ffi v1.1.2. Applications do not need a dependency override. See development and testing for the validated changes.

Selecting an FFmpeg installation

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.

Basic usage

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.

Examples

go run ./examples/mediaplayer/desktop /path/to/video.mp4
go run ./examples/stream rtsp://example.test/live

The 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.

Performance

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.

Current limitations

  • 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.

License

Avebi is available under the MIT License.

About

Avebi plays local video and live video streams in Ebitengine applications.

Resources

Stars

2 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages