git clone https://github.com/kpg-anon/coomplexer.git
cd coomplexer
pipx install .            # or: pip install .

For a live checkout where edits take effect immediately:

pip install -e .

git clone https://github.com/kpg-anon/coomplexer.git
cd coomplexer
pip install -r requirements.txt
python -m coomplexer --help

Every command works the same way, python -m coomplexer standing in for coomplexer.

pip install "coomplexer[probe]"   # pillow + av: faster orientation probing for -p/-L
pip install "coomplexer[net]"     # curl_cffi: browser-TLS fetching for the scraper
pip install "coomplexer[tui]"     # prompt_toolkit: tab completion in the playlists picker
pip install "coomplexer[all]"     # everything

None of these are required — coomplexer falls back to ffprobe for probing and to stdlib HTTP for scraping. coomplexer doctor reports which are present.

coomplexer grid ~/videos -D 2            # second monitor
coomplexer grid ~/videos -D all          # every monitor
coomplexer grid ~/videos -D 1,2 -g 3x1,2x2   # a different layout per monitor

-D takes a 1-based index, a comma list, or all. One -g layout repeats on every screen; a comma list of layouts pairs one per monitor in -D order. Files are dealt across the whole combined wall.

The taskbar. By default tiles are measured against the work area, so nothing hides behind the taskbar. To use the full screen instead:

coomplexer grid ~/videos --hide-taskbar

The taskbar comes back when you coomplexer stop. If one ever gets stranded — a wall closed some other way — coomplexer stop --all always restores it. Set hide-taskbar = true under [grid] in your config to make it the default. Windows only.

coomplexer scrape karina                     # newest matches -> a playlist
coomplexer scrape karina -g                  # ...and open it as a wall
coomplexer scrape karina -d                  # ...or download it instead
coomplexer scrape -n 99 --limit-mode live karina   # keep going until 99 live URLs

Results are resolved to live direct media URLs and written to a self-describing .m3u.

Sources — --source reddit (default), kkzz, kgirls, youtube, or all:

coomplexer scrape --source all shuhua
coomplexer scrape --source youtube 카즈하      # YouTube Shorts by #hashtag

youtube searches youtube.com/hashtag/<term>/shorts. Its links go into the playlist as YouTube page URLs, deliberately unresolved — YouTube's direct media URLs expire quickly and are tied to the client that requested them, so a resolved playlist would be dead on arrival. mpv's own yt-dlp hook opens each one when a tile reaches it, and coomplexer keeps that hook enabled whenever a playlist contains such links.

-n is split between the sources, and the term is auto-translated per source: reddit searches shuhua, the Korean boards search 슈화. Name both scripts yourself with a piped term ("iroha|이로하"), or turn it off with --no-translate.

reddit's JS bot-wall is cleared headlessly (install Deno for the robust solver, or pass --cookies firefox). kgirls.net sits behind Cloudflare and needs a FlareSolverr endpoint: --flaresolverr http://host:8191/v1.

Incremental scraping. Every URL a run collects is remembered, so:

coomplexer scrape karina --new-only -n 25 -d --download-archive

only fetches what previous runs never saw, and skips videos already downloaded.

Merging. -a/--append folds existing playlists, folders and files into a combined playlist alongside the fresh results:

coomplexer scrape -g 3x1 --source all "iroha|이로하" -a old.m3u -a ~/pics/iroha -t videos -p

Every local file a grid scan touches is indexed automatically (path, type, orientation, dimensions), so it grows into a catalog of your libraries.

coomplexer db                              # what's in there
coomplexer db index ~/pics ~/videos -r     # add a library explicitly
coomplexer db search kazuha                # where is that file?
coomplexer db prune -n                     # preview dead entries, then drop the -n

Export new playlists from it instantly — no rescanning, no re-probing:

coomplexer db export -t videos -p                 # portrait videos
coomplexer db export --order random --limit 50    # 50 at random
coomplexer db export --min-height 1080            # 1080p and up
coomplexer db export -L --db other.db             # from a secondary index

--order takes path, random, newest, oldest, largest, smallest.

Add -g to any export to open it as a wall straight away:

coomplexer db export -t videos -p -g 3x1 -D all

Master playlists keep one file per set of filters and rewrite it in place, so you can point at it forever instead of collecting timestamped exports:

coomplexer db master -t videos -p        # -> playlists/master_videos_portrait.m3u
coomplexer db master -t videos -g -D all # refresh it, then shuffle it everywhere

Re-running reports the drift — 642 entries (+12 new, -3 gone).

coomplexer stack clip.webm                 # one clip, tripled across the row
coomplexer stack -r 1 a.mp4 b.mp4 c.mp4    # three clips, each rotated 90°
coomplexer stack -V -D 3 a.mp4 b.mp4 c.mp4 # a column of three, filling portrait monitor 3
coomplexer stack https://youtu.be/XXXX     # a URL, resolved by mpv
coomplexer stack -z 1.2 clip.webm          # zoomed 20% into the centre

Uses mpv's filtergraph to stack the panes in a single window: hstack into a row by default, or vstack into a column with -V/--vertical. Panes are normalized to one height for a row and one width for a column, so mixed resolutions can be stacked together. Three 16:9 clips make a 16:27 column, which is close enough to fill a portrait monitor. Panes without an audio track are handled automatically. -D 3 fills a chosen monitor, and -z zooms into the centre of the source without changing the layout.

coomplexer config --init    # generate a fully commented starter
coomplexer config --edit    # open it in your editor
coomplexer config --path    # where is it?

config.example.toml in the repo root is exactly what --init writes: every key, commented, with its default. Read it there without installing anything.

[grid]
grid = "3x1"
volume = 20
hide-taskbar = true

[scrape]
subreddit = "kpopfap"
solver = "deno"

[profiles.default]          # applied automatically to: coomplexer grid PLAYLIST.m3u
grid = "3x1"
speed = 0.5

[profiles.wall]             # applied with: --profile wall
grid = "4x2"
portrait = true
type = "videos"

Precedence, lowest to highest: built-in defaults → [command] table → [profiles.default] for grid → --profile NAME → explicit CLI flags. Unknown keys are rejected with a suggestion rather than ignored.

The file lives in the repo root from a checkout, or your per-user config dir (%APPDATA%\coomplexer, ~/.config/coomplexer, ~/Library/Application Support/coomplexer) when installed.

Each launch records a session: its tiles, their process ids, and their mpv IPC endpoints. That is what lets stop close one wall without touching another, and what ctl talks to.

coomplexer stop --list        # ids, live tile counts, layouts, start times
coomplexer ctl next -S 6a66dec        # target one wall explicitly
coomplexer stop -S 6a66dec

Records are cleaned up once their processes are gone. Walls launched before v1.9 have no IPC channel and must be relaunched to be controllable.

Start with coomplexer doctor. Then re-run the failing command with --verbose — every failure the tool handles quietly (a source falling back, a retried request, an unreadable file, a URL yt-dlp gave up on) is reported there with its cause.

Full reference for every flag and config key: USAGE.md.