This repository contains the CLI tool uiina, modified from this script from mpv’s repository at Github.
Also a good oppourtunity for me to learn python project build based on uv2nix + nix flakes.
Last modified: [2025-05-08 Thu]
uiina --helpUsage: uiina [option] [target ...]
options:
-h | --help Show this help.
-v | --verbose Be verbose.
-V | --version Print version info then exit.
target ...:
The target(s) to be opened by uiina.
They can be paths, or URLs.
To read from stdin, give a single parameter "-" and nothing else.
Inspect the python script for a more detailed explaination.
All mentions of mpv have been replaced with iina where applicable.
It should be noted that IINA will NOT quite automatically after all files are played.
The way mpv options are via iina is also different:
iina --help | head -n 10
Since commit dfbd60f umpv had changed to NOT wait for quit even for
new socket / pipe.
However, due to uiina’s auto cleanup feature we DO need it to keep alive
and clean up on quit.
unlike mpv we allow reading from stdin.
We also accepts URLs too due to IINA’s builtin yt-dlp.
You can configure the socket directory with a environment variable.
These are accepted, in order of precedence:
UIINA_SOCKET_DIRXDG_RUNTIME_DIRHOME- in
uiinawe take this fromPath.home(), unlikeumpvwhich relies on env var.
- in
TMPDIR
This script ensures that only one instance of IINA is used.
If invoked via the command line, it will attempt to append files to the playlist of an already running IINA instance
but only if that instance was started with the uiina command, which can be detected by socket / pipe existence.
Any other IINA processes remain unaffected.
If an target argument is invalid, IINA will quit with a non-zero exit code.
If no good IINA running, that is no socket / pipe file, they will be created and a fresh IINA instance will be launch.
To avoid cluttering logs (notably ~/.xsession-errors or, on macOS, stdout/stderr), it deliberately suppresses output.
You may define a custom IINA (originally MPV for umpv) binary path and options using some appropriate environment variable.
This variable is split on whitespace:
- the first element specifies the IINA binary’s path
- any subsequent items are options applied only when the script initiates IINA
- If IINA is already running, these settings are ignored
nix run github:ed9w2in6/uiina#defaultRun any of these:
nix-env -iA github:ed9w2in6/uiina#defaultnix profile install github:ed9w2in6/uiina#default
Something like this in your nix-darwin / home-manager flake.
{
description = "Example configuration with uiina installed";
inputs = {
# use your preferred nixpkgs channel here
nixpkgs.url = "github:NixOS/nixpkgs/nixpkgs-unstable";
nix-darwin.url = "github:nix-darwin/nix-darwin";
home-manager.url = "github:nix-community/home-manager";
# add the uiina flake as an input
uiina-flake.url = "github:ed9w2in6/uiina";
};
outputs =
{
self,
nixpkgs,
nix-darwin,
home-manager,
uiina-flake,
}:
let
username = "my-name";
homeDirectory = "/Users/${username}";
system = "x86_64-darwin"; # [2025-05-08]: only "x86_64-darwin" for now, can easily add the "aarch64-darwin" later
pkgs = import nixpkgs { inherit system; };
uiina = uiina-flake.packages.x86_64-darwin.default;
in
{
darwinConfigurations."my-hostname" = nix-darwin.lib.darwinSystem {
inherit system;
modules = [
(
{ config, pkgs, ... }:
{
environment.systemPackages = with pkgs; [
uiina
];
}
)
home-manager.darwinModules.home-manager
{
home-manager = {
users."${username}" = {
home = (
{
pkgs,
lib,
# config,
...
}:
{
# WARNING: you probably should NOT change yours
stateVersion = "25.05"; # this is just an example
# WARNING: you probably should NOT change yours
inherit username homeDirectory;
packages = with pkgs; [
uiina
];
}
);
};
};
}
];
};
};
}After downloading the uiina binary
- Verify its checksum (e.g.
sha256sum --check sha256sum.txt) - Move the
uiinabinary to your desired location - Make your desired location is under
$PATH
As this software is a derivative work of mpv, it is licensed with the same terms.
If there are any difference in the licensing terms, consider that a result of error. Please contact for any licensing error and refer to the mpv-player repository as the authorative source.