gomp

gomp is a reusable Go media player package with a terminal UI layer on top of mpv.

The repository is split so you can embed the player in another terminal app now and add a GUI on top of the same playback API later.

What is included

• gomp: shared playlist and track types for embedding
• player: stable controller interfaces and shared state types
• player/mpv: mpv backend using JSON IPC, no cgo
• tui: terminal UI wrapper that can be imported into another Go app
• cmd/gomp: minimal example binary

Requirements

• Go 1.25+
• mpv installed and available in PATH

Quick start

go run ./cmd/gomp "https://example.com/video.mp4"

Useful flags:

• -title "Episode 1"
• -start 90s
• -start-index 3
• -vo gpu
• -vo tct
• -vo kitty
• -mpv-arg=--really-quiet

Multiple positional arguments are treated as a playlist:

go run ./cmd/gomp "ep1.mkv" "ep2.mkv" "ep3.mkv"

Default controls

• space: play or pause
• left / right: seek backward or forward by 10 seconds
• up / down: volume up or down by 5%
• m: mute toggle
• s: stop playback
• [ / ]: previous or next playlist item
• q: quit the TUI

Library usage

package main

import (
	"context"
	"log"

	"github.com/KellerHalm/gomp"
	"github.com/KellerHalm/gomp/player"
	"github.com/KellerHalm/gomp/player/mpv"
	"github.com/KellerHalm/gomp/tui"
)

func main() {
	controller, err := mpv.New(context.Background(), mpv.Config{
		VideoOutput: "gpu",
	})
	if err != nil {
		log.Fatal(err)
	}
	defer controller.Close()

	err = tui.Run(context.Background(), tui.Options{
		Player: controller,
		Playlist: gomp.Playlist{
			Title: "Season 1",
			Tracks: []gomp.Track{
				{Location: "episode-01.mkv", Title: "Episode 1"},
				{Location: "episode-02.mkv", Title: "Episode 2"},
			},
		},
	})
	if err != nil {
		log.Fatal(err)
	}
}

If you do not want the bundled terminal UI, use player/mpv directly:

controller, err := mpv.New(context.Background(), mpv.Config{})
if err != nil {
	log.Fatal(err)
}
defer controller.Close()

if err := controller.Load(context.Background(), player.Media{Source: "episode-01.mkv"}); err != nil {
	log.Fatal(err)
}

Notes

• The backend is designed to be reused by a future GUI without changing the playback API.
• The TUI now supports playlists, manual episode switching, and automatic move to the next item on end-of-file.
• By default gomp starts mpv with --no-config to keep embeds predictable. Pass UseUserConfig: true if your project needs the local mpv.conf.
• mpv terminal video outputs like tct and kitty are available, but the current TUI is primarily a controller/status UI. If you want fully inline terminal video composition, that should be the next layer on top of this backend.