detain / phlix-console-client
Full-window terminal (TUI) client for Phlix — browse libraries and posters and play media in the terminal, rendered as sixel / kitty / iTerm2 / half-block ANSI via the SugarCraft stack.
Package info
github.com/detain/phlix-console-client
Type:project
pkg:composer/detain/phlix-console-client
Requires
- php: ^8.3
- ext-gd: *
- ext-intl: *
- ext-json: *
- ext-mbstring: *
- ext-pcntl: *
- react/event-loop: ^1.5
- react/http: ^1.11
- react/promise: ^3.3
- react/promise-timer: ^1.11
- sugarcraft/sugar-colorprofile: dev-master
- sugarcraft/sugar-core: dev-master
- sugarcraft/sugar-focus: dev-master
- sugarcraft/sugar-forms: dev-master
- sugarcraft/sugar-fuzzy: dev-master
- sugarcraft/sugar-gallery: dev-master
- sugarcraft/sugar-image: dev-master
- sugarcraft/sugar-markdown: dev-master
- sugarcraft/sugar-navstack: dev-master
- sugarcraft/sugar-overlay: dev-master
- sugarcraft/sugar-panels: dev-master
- sugarcraft/sugar-quickpick: dev-master
- sugarcraft/sugar-style: dev-master
- sugarcraft/sugar-table: dev-master
- sugarcraft/sugar-toast: dev-master
- sugarcraft/sugar-video: dev-master
- workerman/workerman: ^5.0
Requires (Dev)
- humbug/box: ^4.7
- phpstan/phpstan: ^2.0
- phpunit/phpunit: ^12.0
- squizlabs/php_codesniffer: ^4.0
- sugarcraft/sugar-testing: dev-master
Suggests
None
Provides
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-21 02:10:34 UTC
README
Phlix is an open-source media server you run yourself — your own movies,
shows and music on your own hardware, streamed to your devices. The server is a
separate project, phlix-server, and
you need one running before this client can do anything. This repository is its
full-window terminal (TUI) client: the whole library, browsed and played
from any terminal — over SSH if you like.
What it does once connected:
- Browse — libraries as poster rails and virtualized grids; media detail and series → season → episode drill-down; music, book, audiobook and photo libraries open in browsers built for each; global search.
- Watch together — SyncPlay watch party rooms, casting to Chromecast / Roku / AirPlay / DLNA, and item downloads.
- Play in the terminal — an in-terminal video player that direct-plays HEVC/AV1 the browser can't, with trickplay sprite thumbnails previewing while you scrub; posters and video render as sixel / kitty / iTerm2 / half-block ANSI via the SugarCraft stack.
- Stay in control — a command palette wired to every screen in the client (the full screen-by-screen list lives in the manual's Screens section), and a full admin client for server upkeep.
The command palette is the one keypress to all of it — Search, Home, Settings, Keyboard shortcuts, Watch History, Favorites, Photos, Music Artists, Playlists, Collections, Servers, Shared With Me, Invite Links, Federation Shares, Show metrics / Hide metrics, Stats and Admin (admins only — Stats reads the admin stats API), Resume playback / Pause playback / Stop playback (while a music or audiobook session is live), Sign out and Quit — plus a Go to jump per library.
The same screen rendered with each --mode, cycling every few seconds —
the modes are compared side by side under Render modes.
Documentation
This page is the front door. The full user manual — config-file layout, every keybinding, the screen-by-screen guide, the render-mode reference and genuine troubleshooting — lives in docs/clients/console.md. Straight to the answers:
| Question | Jump to |
|---|---|
| Where does config live; which files and env vars? | Configuration |
| What does every key do? | Keybindings |
| Which screens exist, and how do I reach each? | Screens |
| How do rating / favorite / watched persist? | Watching & ratings |
| How do I consume hub-relay play commands headless? | Hub relay consumer |
| "needs a TTY" / no graphics / expired session? | Troubleshooting |
| Which languages does the interface speak? | Languages |
NO_COLOR, TERM=dumb, tiny or basic terminal? |
Accessibility and basic terminals |
Further reading: the full manual (keys, screens, configuration), i18n (the env locale chain), terminal graphics (protocol capabilities), upgrade notes, development guide (architecture and gates), CI gates (what must stay green), vendor-patch policy, dependency policy. Issues and questions: the issue tracker.
Requirements
- A running Phlix media server — without one this client has nothing to
connect to. The server is a separate project you run yourself:
phlix-server. - PHP ≥ 8.3 with
ext-gd(image decode),ext-mbstring(multibyte text width — src/ and sugar-image),ext-intl(sugar-core),ext-ffi(PTY control via sugar-pty),ext-json(required by workerman; bundled in PHP ≥ 8.0) andext-pcntl(the exit-signal teardown that stops ffplay/ffmpeg children onkillor a closed terminal, plus Ctrl-Z suspend). Composer enforces all six at install.ext-ffiis not peripheral: sugar-pty drives the terminal through it, so a lean PHP build without it hard-failscomposer installat the platform check — and inside a PHAR (which skips that check) the client dies at boot. ext-curl— thedoctor/run --selftestserver-reachability probes andwatch's hub relay-token mint call it; the TUI itself needs no curl.ext-pcntlis composer-enforced (soft only in PHAR): every pcntl call isfunction_exists()-guarded, so a PHAR on a PHP without it still runs but loses the exit-signal teardown and Ctrl-Z suspend. Raw mode itself is plainstty, no extension needed.posixis optional: Ctrl-Z suspend needs it too, and two fork-based tests self-skip without it.- ffmpeg + ffprobe (video decode + frame grabs).
- ffplay or mpv (audio playback — video, music, audiobooks).
- A terminal of at least 80×24 (designed size). Below the hard floor of 20×9 the client shows a "Terminal too small" notice instead of the UI.
- A terminal with sixel or the kitty/iTerm2 graphics protocol is recommended; half-block is the universal colour fallback (any UTF-8 locale renders it — the UI's glyphs assume UTF-8 throughout).
Install
Composer (developer)
The fully verified install path — clone over HTTPS (no SSH key needed) and run from the checkout:
git clone https://github.com/detain/phlix-console-client.git cd phlix-console-client composer install bin/phlix run # needs a real TTY; first run asks for your server URL
The SugarCraft libraries are normal Composer dependencies, pulled from
Packagist (sugarcraft/*, currently tracking dev-master).
PHAR (end user)
CI publishes a rolling pre-built PHAR of the tip of master on every push,
carried as an asset of the GitHub Release tagged latest — marked
prerelease. No stable, versioned release has been cut yet (no v*.*.*
tag exists), and GitHub's /releases/latest shortlink deliberately excludes
prereleases, so releases/latest/download/... URLs 404 today. Download
from the latest tag path instead (the commands below are verified against
the live release):
# Download the rolling master-build PHAR (tag path — not releases/latest) curl -fsSL https://github.com/detain/phlix-console-client/releases/download/latest/phlix.phar -o phlix.phar # Make it executable chmod +x phlix.phar # Run it (first run will prompt for server URL) ./phlix.phar run # Or add it to your PATH sudo mv phlix.phar /usr/local/bin/phlix phlix run
Verify the download (recommended):
# Fetch the checksums file (the asset is named SHA256SUMS, no .txt) curl -fsSL https://github.com/detain/phlix-console-client/releases/download/latest/SHA256SUMS -o SHA256SUMS # Verify (Linux; on macOS use `shasum -a 256 -c SHA256SUMS`) sha256sum -c SHA256SUMS
Requirements for PHAR:
- PHP ≥ 8.3 with
ext-gd,ext-mbstring,ext-intl,ext-ffi,ext-json(a PHAR runs without composer's platform check, so these are on you; addext-curlfor thedoctor/run --selftestreachability probes andwatch's hub relay-token mint).ext-pcntlis composer-enforced (soft only in PHAR): without it the PHAR still runs, minus the exit-signal teardown and Ctrl-Z suspend.posixis optional (Ctrl-Z suspend wants it too) - A terminal with sixel/kitty/iTerm2 support (or use
--mode=halfblockas fallback) - ffmpeg + ffprobe (for video frame grabs)
- ffplay or mpv (audio playback — video, music, audiobooks)
To build your own PHAR from source (humbug/box is already a declared dev
dependency and scripts/build-phar.sh auto-detects vendor/bin/box, so no
separate box install step is needed):
composer install ./scripts/build-phar.sh # Output: build/phlix.phar # Building needs phar.readonly=0 (CI sets it); box reports a clear error # if your PHP has it enabled.
Developing against unreleased library changes
To test the client against local, unmerged SugarCraft changes, add a path repository without committing it:
composer config repositories.sugarcraft path '../../sugarcraft/*' composer update 'sugarcraft/*' # revert before committing: git checkout composer.json
Below, examples are written bin/phlix … — the checkout layout. Once you have
installed the PHAR on your PATH, the same commands run as phlix ….
Run it
# Launch the full-window app (needs a real TTY): first run asks for your server # URL, then sign in. No account yet? Press `s` at the sign-in form to register # in place when the server allows sign-ups (a server that approves accounts # reports yours as pending; an admin can also create one). Browse rails + # sidebar → open a library → grid → open a # poster → detail → drill series/season/episode. Opening a music, book, # audiobook, or photo library routes to its own browser instead (album list / # book grid / audiobook list / photo albums). Press `/` to search and Ctrl-K # (or `:`) for the command palette — both once you're signed in (until then # they type as characters in the sign-in form). Esc walks back; Ctrl-C quits. bin/phlix run
Keys: ↑↓←→ move · ⏎ open · / search (or filter, in a grid) · Ctrl-K / :
command palette · A–Z jump · PgUp / PgDn page a grid · Home / End jump to
a grid's first / last item · p play · C cast (on a detail screen) · d
download (on a detail screen) · R refresh (home rails / library grids) · s
shuffle-play the focused item (home rails / library grids / media detail) · c clear the grid
filter · u / n jump to the Up Next rail (home) · [ / ] page the Most
Watched rail (home) · q quit the home browse view · H history, P playlists
and the a watch filter on the home sidebar · Tab switch focus on the
home screen · Esc back · Ctrl-C quit. / and the palette are
signed-in keys: until you sign in they type as characters into the sign-in
and server-pick forms.
Watch state — on a media detail screen: r rate (a star picker, 1–5 stars =
ratings 2–10), F favorite, w watched, l / j thumbs up / down (every one
of these persists to your account on the server, and the screen reverts if the
save fails); on home, a cycles the watch filter
All → Watched → Unwatched → ♥ Favorites, and H / P open your watch history
and playlists. The manual's Watching & ratings
section covers the loop in full.
The command palette (Ctrl-K or :) is the universal navigator: Search,
Home, Settings (theme + slideshow interval), Watch History,
Favorites, Photos, Music Artists,
Playlists, Collections, Servers, Shared With Me, Invite
Links, Federation Shares, Show metrics / Hide metrics, Sign out,
Quit — plus a Go to <library> jump per library, the read-only Stats
screen and the Admin menu
when you're signed in as an admin (see Status below), and Resume
playback / Pause playback and Stop playback while a music or
audiobook session is live. Every live screen is listed with how to reach
it in the manual's Screens section.
In the player: Space play/pause · ←/→ seek ±10s · 0–9 seek to % ·
[ / ] speed · m cycle render mode · s skip intro/outro · o start over ·
c captions · a audio-track picker (when the item exposes audio tracks) ·
S subtitle-track picker (shift; when the item has subtitle tracks — s
stays skip intro/outro) · C chapter picker (shift; when the item has
chapters — c stays captions) · v quality (only shown when the active
transcode advertises an ABR ladder — direct-play and legacy items skip it) ·
n / p next / previous episode · w "For You" recommendations ·
y SyncPlay room (create/join) · z sleep timer (pause playback after a
15–120 min preset) · f toggle chrome · q/Esc back. Transport keys are
inert until the stream is up (q/Esc always close the player); while a
picker or modal is open it captures every keystroke (↑/↓ move, Enter
picks, q/Esc dismisses).
Cast — on a media detail screen, C opens a device picker (Chromecast /
Roku / AirPlay / DLNA discovered on the network); pick one to send the item, then
drive a transport overlay (Space pause/resume, x stop, Esc back). Seek is
capability-gated: ←/→ step ∓10 s (Shift+arrow: ∓60 s) when the device
exposes its playback position (Chromecast and DLNA do; AirPlay and Roku don't —
there the arrows stay inert and the on-screen hint omits them).
Music — an album list → a track table; ⏎ plays a track (Space pause,
n/p next/previous). Audiobooks — a list → a chapter table; ⏎ plays a
chapter, r resumes from your saved spot, Space pauses (progress is saved
back). Books — a cover grid → a detail screen with a copyable download URL.
Photos — album covers (by date) → an album's thumbnails → a fullscreen photo
(←/→ prev/next, i EXIF panel, s slideshow).
Render diagnostics
# What can this terminal render? bin/phlix doctor # env snapshot + extensions + PATH probes bin/phlix doctor --probe # also run the live terminal query # Render an image at 40 cells wide (safe cell renderer by default) bin/phlix poster /path/to/poster.jpg 40 bin/phlix poster /path/to/poster.jpg 40 --mode=halfblock # …or force any mode # Decode the first 3 frames of a video to ANSI (ffmpeg) bin/phlix frame /path/to/movie.mkv 3 60 20
doctor, poster, and frame are non-interactive and work over a pipe;
run needs an interactive terminal — run --selftest is the headless wiring
ladder and does not. The full command inventory is run,
doctor, poster, frame, watch (below), version (-V / --version)
and help (-h / --help) — the latter two print and exit, no terminal required.
Hub relay watch
# Consume the hub relay's "play this" commands (headless — no TTY needed) bin/phlix watch --hub https://hub.example --server-id srv-7 \ --hub-token-stdin < /run/secrets/hub_token # Fully env-driven — the recommended carrier for tokens PHLIX_HUB_URL=https://hub.example PHLIX_HUB_SERVER_ID=srv-7 \ PHLIX_HUB_TOKEN="$TOKEN" bin/phlix watch --once --timeout 60
watch connects to the hub's SyncPlay relay (ws(s)://{hub}:8804/syncplay/{server_id})
and dispatches every delivered play_media command to the player. Four environment
variables drive it — PHLIX_HUB_URL, PHLIX_HUB_SERVER_ID, PHLIX_HUB_TOKEN (a hub
user access token, exchanged for a relay token on each connect) and PHLIX_RELAY_TOKEN
(a ready-made relay token; skips minting) — each overridden by its flag (--hub,
--server-id). The --server-id value is the
hub's own identifier for your server — assigned when the server pairs with the
hub; GET /api/v1/me/servers on the hub lists the ids of the servers on your
account (the hub web portal's My Servers view shows the same), and watch
mints its short-lived relay token against POST /api/v1/me/servers/{id}/relay-token.
For the two token values prefer the
environment or --hub-token-stdin / --relay-token-stdin: literal argv secrets are
world-readable via ps(1), so the literal --hub-token / --relay-token flags were
removed and now exit 2 with a migration hint. --once waits for a single play command
and exits, giving up after --timeout
seconds (default 30). Exit codes: 0 = a command was dispatched, 1 = the run ended
without one (the connection failed, or a --once wait timed out), 2 = usage
error (bad flag or value).
Render modes
Graphics protocols emit a real image (highest fidelity, terminal-dependent);
cell modes tile coloured text and work in any terminal, trading detail for
compatibility. The animated tour at the top of this page cycles the same
screen through every --mode; the stills below compare them side by side.
Side-by-side stills
kittyis also supported (graphics, kitty protocol) but renders identically to the other graphics modes in a capable terminal.
chafais accepted byrunandposteras well — the external chafa renderer, resolved through sugar-image — andframerejects it as a usage error, taking the nine canonical names only.
Status
Status: every screen and subsystem below is shipped. Working today: sign in, browse your libraries as poster rails beside a sidebar, open a library into a virtualized poster grid (scroll, filter, sort, A–Z jump), open any poster into a detail screen (hero poster, metadata, synopsis, and a Cast list with initials-based ANSI avatars), and drill series → season → episode, with a breadcrumb trail in the header.
Press
pto launch the in-terminal player: it direct-plays the item's signed stream straight through ffmpeg — decoding HEVC/MKV/AV1 the browser can't and bypassing the server transcode — with a scrubber (chapter ticks + intro/outro skip + trickplay sprite thumbnails previewing while you drag, where the server publishes them for the item), resume from where you left off, progress reporting, up-next auto-advance between episodes, on-demand subtitles, and a transcode fallback when a file can't be direct-played.Also shipped: global search (
/→ a debounced query over a virtualized poster grid of/media?search=results), a command palette (Ctrl-K or:→ fuzzy-ranked actions) — both once you're signed in (until then the keys type as characters) — and toasts — transient top-right notifications that surface errors which used to fail silently. The palette has since grown into the client's universal navigator, registered screen-by-screen insrc/App.php: Search, Home, Settings, Keyboard shortcuts, Watch History, Favorites, Photos, Music Artists, Playlists, Collections, Servers, Shared With Me, Invite Links, Federation Shares, Show metrics / Hide metrics, Stats and Admin (offered only while signed in as an admin), Resume playback / Pause playback and Stop playback (while a music or audiobook session is live), Sign out, and Quit — plus aGo to <library>jump per library. The same list, with what each action opens, is in the manual's Screens section.Every library type is browsable, and audio + photos are fully usable — opening a library now routes to a browser built for its type:
- Music — an album list (Album · Artist · Year · Tracks) → a track table; Enter direct-plays the audio through ffplay/mpv, with
Spacepause andn/pfor the next/previous track. (No server cover art → text-forward.)- Books — a virtualized cover grid (lazy covers) → a detail screen with the cover, metadata, and a copyable download URL (there is no in-terminal reader).
- Audiobooks — a list (Title · Author · Narrator · Duration) → a chapter table; Enter plays a chapter,
rresumes from your saved position,Spacepauses, and your progress is saved back to the server. (Text-forward.)- Photos — a grid of album covers (by date) → an album's thumbnail grid → a fullscreen photo (
←/→prev/next) with an EXIF panel (i) and an auto-advancing slideshow (s). Thumbnails and full images render directly from signed URLs.Theming, settings, and polish: three built-in themes — Nocturne (default), Daylight, and Midnight — plus a Settings screen (reachable from the command palette) for picking the theme and the photo-slideshow interval, applied live.
NO_COLORis honoured: colour drops out everywhere while bold/faint/reverse structure stays; a basicTERM(dumb,unknown, unset or empty) cannot draw the full-window app, sophlix runrefuses it with the fix spelled out (Accessibility and basic terminals). A persistent Now-Playing bar spans every screen so music and audiobook audio keeps playing (and stays controllable) as you navigate; the palette also toggles a diagnostic metrics HUD overlay and (for admin accounts) opens a read-only Stats screen, and lists load behind animated shimmer skeletons.Full admin parity plus casting (the Admin action appears in the command palette only when you're signed in as an admin). It opens an admin menu with every section wired:
- Dashboard — now-playing sessions, storage usage, top users, top media, and recent activity.
- Users — list with a status filter (All / Pending / Active / Disabled) and per-row actions: approve, disable, reject, delete, toggle admin, reset password (the new password is revealed once);
Popens that user's viewer profiles.- Plugins — list with enable / disable / uninstall and install-from-URL.
- Plugin Updates — available updates with an auto-update toggle, a catalog channel setting, and a confirmed apply.
- Logs — a file list with a single-file or merged "all logs" tail viewer.
- Backup — list / create / delete / restore / upload-to-S3, plus a backup schedule editor.
- Server Settings — per-key typed editing (bool toggles inline; int / float / string / JSON via a validated input).
- Transcoding — read-only hardware-accelerator introspection plus editable HDR tone-mapping settings.
- Libraries — scan / rescan / match-metadata with a live scan-status readout.
- DLNA server — status with start / stop.
- Remote Access — Hub, subdomain, relay, and port-forward status with their toggles, plus an in-console Hub pairing wizard.
- Live TV — five tabbed sections (Tuners · Channels · Guide · Recordings · Series Rules), all operated in-terminal: scan / toggle / rename / delete tuners, toggle / rename channels, refresh the guide and load EPG, record a program (
R) or an entire series (S) from the guide, delete recordings, and edit or delete series rules.- Parental Controls — per-profile tags, access schedules, and stream limits.
- Metrics — read-only snapshot / history / connections / routes panels.
- Watch History — every user's recently-watched items with an optional filter-by-user.
- Duplicates — duplicate groups per library, with an armed merge.
- Webhooks — subscriptions with their URL, events, and enabled status.
- Auth Providers — OIDC / LDAP / GitHub providers with enable / disable and a per-provider settings form.
- Server Restart — a graceful worker reload, confirmed by the server's own ack (no polling).
- Filesystem — a navigable listing of the server's configured browse roots and their subdirectories.
Cast is not an admin section — press
Con a media detail screen to discover Chromecast / Roku / AirPlay / DLNA devices on the network, send the item, and drive a transport overlay (pause / resume / stop). Seek is capability-gated:←/→step ∓10 s (Shift+arrow: ∓60 s) wherever the device exposes its playback position — Chromecast and DLNA do, AirPlay and Roku don't, and there the keys simply stay inert.Also working today, inside the player:
a, shift-Sand shift-Copen the track pickers — the audio, subtitle (with an explicit Off) and chapter tracks the item exposes; picking a chapter jumps to it, and picking a subtitle turns the caption overlay on.vselects the playback quality of a transcoded item, andwopens "For You" recommendations without leaving playback.yopens the SyncPlay watch party modal — create your own room (public or private) or join one the server lists; while you are in a room an overlay tracks the room, its member count and the sync status, and the room's play / pause / seek commands drive your player in step.zsets an in-player sleep timer (presets 15 / 30 / 45 / 60 / 90 / 120 min; playback pauses when the countdown expires, and the last preset you used is remembered).
Test
vendor/bin/phpunit # or: composer test
The video-decode test self-skips when ffmpeg is unavailable; the poster test
synthesizes its own image with gd, so no binary fixtures ever need to be
downloaded. The suite does carry two vendored text fixtures:
tests/fixtures/server-route-manifest.json, the byte-for-byte server route
manifest that tests/Unit/Api/ServerRouteManifestGateTest.php checks every
wire URL against, and tests/fixtures/contracts-error-codes.json, the
byte-for-byte @phlix/contracts error-code registry that
tests/Unit/Api/ContractsErrorCodesGateTest.php pins the SyncPlay wire-code
map against.
Static analysis
src/ is checked with PHPStan at level 9 of 10, enforced in
CI — any new type error fails the build. Config lives in phpstan.neon;
tests/ is analysed separately at level 2 via phpstan-tests.neon. There is
no baseline file and no ignoreErrors in either config; the honest
qualifier is that src/ carries 2 inline suppressions, all
@phpstan-ignore-next-line property.onlyWritten, each on a deliberately
write-only field (tests/Docs/StaticAnalysisClaimsDocsTest.php re-derives
this count from the tree — plant or remove a suppression and the table must
move with it; two former SyncPlayModal terminal-size rows retired when the
opaque-frame graft made those fields read):
| Site | Why it stays write-only |
|---|---|
SyncPlayService::$playbackPosition |
room-reported position ingested from group state; the player drives its own clock and never reads it back |
SyncPlayService::$currentMediaId |
sanitized group-state mirror — the ingest boundary stores every hostile wire string uniformly, display reader or not |
composer phpstan # or: vendor/bin/phpstan analyse vendor/bin/phpstan analyse -c phpstan-tests.neon # tests/ at level 2 composer cs # phpcs over src/ and tests/ (composer cs:fix autofixes)
License
MIT







