MpvIpcController 1.0.0

MpvIpcController

A typed .NET client for MPV JSON IPC allowing to control MPV as an external process from .NET

To embed MPV in-process via libmpv, use LibMpv instead.

Requires .NET 10. On Windows the transport is a named pipe; on Unix it is a domain socket.

How to use

var factory = new MpvApiFactory();

await using var api = await factory.StartAsync("mpv");
await api.LoadFileAsync("video.mp4");
await api.Pause.SetAsync(false);

var position = await api.TimePos.GetAsync();

StartAsync launches MPV, waits for IPC, and owns the process. ConnectAsync attaches to an instance that is already running and does not own it.

await using var api = await factory.ConnectAsync("mpv-pipe");

MpvApi exposes commands, properties, options, and events. api.Controller is the raw JSON client when you need an untyped command.

Process ownership

StartAsync always adds --idle=yes, --no-terminal, and --input-ipc-server. Idle keeps MPV alive with an empty playlist. Window, keep-open, vo/ao, and config flags belong in additionalArguments.

await using var api = await factory.StartAsync("mpv",
    additionalArguments: ["--force-window=immediate", "--keep-open=yes"]);

Dispose sends quit, waits briefly, then kills the process if it is still running. Prefer await using / DisposeAsync. OwnsProcess, ProcessId, and IsProcessRunning report ownership. The Shutdown event fires when the player exits on its own.

On Unix, a non-rooted pipe name becomes a .sock file under the temp directory. A leftover socket is deleted before launch; the owner unlinks the file after the process dies.

ConnectAsync never starts or stops MPV.

Commands, properties, and events

Commands are async methods (LoadFileAsync, SeekAsync, QuitAsync, …). LoadFileAsync can pass per-file options (MPV 0.38+):

await api.LoadFileAsync("clip.mp4", extraArgs: new Dictionary<string, object> { ["start"] = 5 });

Properties and options are typed members with GetAsync / SetAsync (and AddAsync, CycleAsync, and similar where MPV supports them).

api.FileLoaded += (_, _) => { /* playback started */ };
api.EndFile += (_, e) => { /* e.Reason, e.Error */ };

await api.Pause.ObserveAsync(observeId: 1);
api.PropertyChanged += (_, e) => { /* e.Id, e.Name, e.Data */ };

Request options

Pass ApiOptions on a single call, or set api.Controller.DefaultOptions for every request. Per-call values override defaults.

OSD and execution prefixes (NoOsd, OsdBar, Async, Raw, …) are the same flags MPV accepts on IPC commands.

MpvApiFactory.Timeout (default 5000 ms) is how long StartAsync / ConnectAsync wait for the pipe or socket. ServerName is the Windows pipe server (. = local).

Debugging

api.Controller.LogEnabled = true;
// ...
var log = api.Controller.Log?.ToString();

License

MIT. Copyright (c) 2020-2026 Etienne Charland.

Library provided by Etienne Charland.