A self-hosted, Jellyfin-compatible media catalog for local and cloud libraries.
English | 简体中文
TJXY separates a media title from the files and storage providers that supply it. One movie, episode, or track can therefore keep a stable catalog identity while its playable sources live on local disks, Google Drive, or OneDrive.
The project includes a browser media client, an administrator console, a Rust HTTP server, and a terminal diagnostic console. The recommended installation pulls a published Docker image. Native builds, source builds, and Linux archives remain available for maintainers.
Important
TJXY is under active development and does not yet implement the complete Jellyfin API. Check the API compatibility matrix before depending on a specific Jellyfin client or endpoint.
- Unified media catalog: model titles independently from their physical files, alternate copies, subtitles, and storage locations.
- Local and cloud storage: browse root-confined local files, Google Drive, Shared Drives, and OneDrive Personal without exposing provider credentials to the browser. The configured local path remains authoritative across remounts; Unix device and inode changes are treated as remount signals while the stored root namespace remains stable.
- Metadata pipeline: discover movies, series, episodes, and music from file names and local NFO/artwork, with optional TMDb, MusicBrainz, and TheAudioDB enrichment. TMDb title searches with a known year accept candidates only within one year, including relaxed searches; otherwise naming metadata is retained.
- Direct playback: prepare session-scoped playback URLs, stream bounded byte ranges, select subtitles and sources, copy temporary direct links, or open supported third-party players while retaining in-app play state, favorites, and viewing progress.
- Web applications: use the responsive
/app/media client and/admin/administration console from the same server. - Library operations: create libraries, bind storage roots, choose scan policies, run durable scan tasks, inspect progress, and retry failed work.
- Users and access: Argon2id passwords, server-side sessions, QR sign-in, device/session revocation, API keys, and administrator-managed users.
Authentication sessions issued by the server expire after 30 days by default; the explicit “remember me” option uses a 180-day server-side lifetime. Logout, credential changes, and administrator revocation continue to invalidate sessions immediately.
During first-run setup, forwarded proxy headers are rejected unless
TJXY_SETUP_TRUST_PROXY=true is explicitly configured. Keep /Setup/* on a
loopback-only path whenever possible.
Legacy query-string API-key authentication can be controlled with
TJXY_LEGACY_QUERY_TOKEN=true|false; header-based legacy authentication remains
controlled separately by TJXY_LEGACY_AUTH.
- Optional AI assistant: connect an OpenAI-compatible provider for media discovery grounded in the authenticated user's visible catalog and history.
- Multiple databases: use SQLite, PostgreSQL, or MySQL; PostgreSQL can be
provisioned automatically by
tjxy-setup. - Client updates: administrators upload desktop and Android installers under
Client releases and mark the latest version per platform and architecture.
Packages are stored in
<assets dir>/client-releases(2 GiB per upload). Signed-in native clients checkGET /ClientUpdates/Latestand download throughGET /ClientUpdates/{id}/Download, which supports resumable ranges. - Operational tooling: health checks, structured rotating logs, a diagnostic TUI, Docker health checks, and persistent installation configuration.
The recommended end-user installation pulls the published Docker image. The
launcher creates persistent storage, starts Compose, and waits until the
services are healthy. You do not need Node.js, Rust, or HEROUI_KEY on the
deployment host.
- Docker Engine with a recent Compose v2 plugin
Current release: ghcr.io/youtonghy/tjxy:0.0.1 (linux/amd64 and
linux/arm64). The latest tag points at the same image. Pin the version tag
in production.
The repository and GHCR package are currently private, so authenticate before the first pull:
docker login ghcr.io
./tjxy-setup \
--runtime docker \
--database postgres \
--image ghcr.io/youtonghy/tjxy:0.0.1 \
--media /path/to/mediaTJXY_IMAGE=ghcr.io/youtonghy/tjxy:0.0.1 is equivalent to --image. Rerun the
same command to pull a newer tag and recreate the application container.
The command above provisions PostgreSQL automatically. You can also run the interactive launcher and pass the published image:
./tjxy-setup --image ghcr.io/youtonghy/tjxy:0.0.1Choose Docker and managed PostgreSQL, or provide the choices directly:
./tjxy-setup \
--runtime docker \
--database postgres \
--image ghcr.io/youtonghy/tjxy:0.0.1 \
--media /path/to/media \
--port 8096The launcher stores configuration under .tjxy/config and application data
under .tjxy/data unless other paths are supplied. On Linux, run it as the
account that should own those directories. Open
http://127.0.0.1:8096/setup/ after startup and create the first administrator.
After the first run, omitting --media reuses the path saved in
.tjxy/media-path; pass --media explicitly only when changing the mapping.
Managed PostgreSQL credentials are generated locally in
.tjxy/postgres-password, are never printed, and are not sent to the browser.
The database is available only on the Compose network. Its data remains in the
tjxy-setup_tjxy-postgres Docker volume when the application is stopped.
Use an existing SQLite, PostgreSQL, or MySQL database by selecting external mode:
./tjxy-setup \
--runtime docker \
--database external \
--image ghcr.io/youtonghy/tjxy:0.0.1 \
--media /path/to/mediaEnter the database settings in the browser setup. A database running on the
Docker host must be addressed as host.docker.internal, not localhost. The
Compose configuration adds the Linux host-gateway mapping and also works with
Docker Desktop.
TJXY opens PostgreSQL sessions with jit=off, sent as a startup option, because
JIT compilation of the work-queue claim costs far more than the query itself. A
connection pooler in front of PostgreSQL, such as PgBouncer, must accept that
option, for example with ignore_startup_parameters = options. Each pooled
connection also keeps up to 512 prepared statements, so wide catalog queries
reuse their plans; budget PostgreSQL memory for a few tens of MB per connection.
| Option | Default | Container path / behavior |
|---|---|---|
--config-dir PATH |
.tjxy/config |
/config, including tjxy.toml |
--data-dir PATH |
.tjxy/data |
/data, including assets and logs |
--media PATH |
./media |
/media, available for media libraries and STRM targets |
--media-mode ro |
rw |
Mount media read-only |
--port PORT |
8096 |
Publish the TJXY HTTP service |
--image IMAGE |
unset (source build) | Recommended: ghcr.io/youtonghy/tjxy:0.0.1. Omit only when building from a checkout |
TJXY publishes only on 127.0.0.1 by default. Keep this setting when using an
SSH tunnel or reverse proxy on the same host. For direct LAN access, explicitly
publish on every interface and protect the port with a firewall:
TJXY_PUBLISH_HOST=0.0.0.0 ./tjxy-setup \
--runtime docker \
--database postgres \
--image ghcr.io/youtonghy/tjxy:0.0.1 \
--port 8096Use a TLS reverse proxy before exposing TJXY outside a trusted network.
When the same server is reachable through several origins (for example a
CDN, a domestic line, and a LAN address), list them under System settings →
Stream addresses. Each entry is a name plus scheme://host[:port] without a
path; up to 10 are allowed. Signed-in web and desktop clients time
/System/Ping on every address and the address they opened, then load video,
audio, external-player links, and posters from the fastest one. API requests
and the sign-in session always stay on the opened address. Users can switch to
a specific line, or back to automatic, from the player page or their profile;
clients re-read the address list whenever they check routes, so changes appear
without signing in again. In automatic mode
a failing line falls back to the next one, ending at the opened address.
Every address must proxy to this server without rewriting paths or query strings. Posters are fetched cross-origin with the bearer token, so every address users may open, including the public URL, must be listed for those requests to be allowed; HTTPS pages ignore HTTP addresses.
./tjxy-setup status
./tjxy-setup logs
./tjxy-setup stopstop removes containers and the Compose network but preserves bind-mounted
files and the managed PostgreSQL volume. To update a published-image deployment,
back up the database and host directories, then rerun the same command with the
new version tag. The launcher pulls the image before recreating TJXY.
Filesystem storage upgrades persist a root-scoped path-index state. When the mounted device or
root inode changes, TJXY keeps the service healthy but returns 503 Service Unavailable with
Retry-After: 5 for media under that root until one recursive validation and title publication
complete. After a transient database outage, startup and the background maintainer reclaim expired
work leases and requeue the jobs; recursive validation backs off while waiting for staged children
instead of retrying at a fixed high frequency. Do not restart the container repeatedly during this rebuild; progress logs include the
root, scanned directory/object counts, revision, and elapsed time. Obsolete title-discovery work is
retired before workers start, and request handling never performs a recursive filesystem search.
This release adds a database migration. An older binary rejects a database containing an unknown migration, so rollback requires either a schema-compatible build or restoration of the pre-upgrade database backup together with the older image.
Do not run docker compose down --volumes unless the managed PostgreSQL database
is intentionally being deleted.
Native builds require Rust 1.88 or newer, Node.js 22.12 or newer, pnpm 10
(corepack enable uses the version pinned in admin/package.json), and the
prepared frontend dependencies. Docker is additionally required when native
TJXY uses managed PostgreSQL.
Use the launcher for a guided local installation:
./tjxy-setup --runtime local --database external --media /path/to/mediaTo let the launcher provision PostgreSQL in Docker while TJXY runs natively:
./tjxy-setup \
--runtime local \
--database postgres \
--media /path/to/media \
--postgres-port 5433For a manual build:
pnpm --dir admin run build
cargo build --release --locked -p tjxy-server --bin tjxy-server
TJXY_ADMIN_DIST_DIR=admin/dist ./target/release/tjxy-serverLocal builds report product version 0.0.0. To stamp a build manually, pass the
same version to both build pipelines:
VITE_TJXY_VERSION=0.2.0 pnpm --dir admin run build
TJXY_BUILD_VERSION=0.2.0 cargo build --release --locked -p tjxy-server --bin tjxy-serverOptionally set VITE_TJXY_COMMIT to show the build commit hash on the administrator About page.
The release workflow injects its validated release version automatically.
Complete setup at http://127.0.0.1:8096/setup/. The installation manifest is
stored at the platform configuration path by default; set TJXY_CONFIG_FILE to
use an explicit location.
Playback preparation has its own wait budget. TJXY_PLAYBACK_WAIT_MS defaults to
15000 and accepts integers from 0 through 30000. The budget covers storage
sync prerequisites, source indexing, probe queue time, and probe execution within
one GET or POST /Items/{id}/PlaybackInfo request. Zero schedules work without
waiting; it still checks the current published result. TJXY_LAZY_WAIT_MS
continues to control ordinary lazy catalog work (default 2500); it does not
configure this playback budget or lengthen playback event reporting.
An already playable version is returned immediately while other eligible probes
can continue. An explicit MediaSourceId waits only for that version; an item ID
continues to mean the default selection. Only published, probed, visible sources
with available locations are advertised, using local TJXY streaming routes.
If preparation is still pending when the budget ends, PlaybackInfo returns HTTP
503, Retry-After: 2, Cache-Control: no-store, and a preparation message.
Terminal preparation failures also return 503 with a distinct sanitized message
and no retry hint. A completed preparation with no usable source returns a
PlaybackInfo response with ErrorCode: NoCompatibleStream. Successful responses
omit ErrorCode. Durable work survives request cancellation or timeout; repeated
requests join active work, and a fresh request reads the published result directly
so an old empty cache entry cannot hide a completed probe.
The 15-second default covers the observed 4.38- and 7.90-second first-play delays,
but slower sources can still time out. HTTP waiting does not change the worker's
own probe limits. Clients and re
8000
verse proxies must allow the selected wait time;
Retry-After does not guarantee that a third-party client retries automatically.
Validate the affected client/version before deployment. Rolling back this change
requires reverting the server build and removing TJXY_PLAYBACK_WAIT_MS; this
feature adds no database migration. Background pre-probing and production capacity
changes are outside this fix.
Background scans default to TJXY_SCAN_CONCURRENCY=auto. Pending work, CPU,
available memory, database latency and foreground request latency control admission
between 1 and 8 concurrent jobs. Expansion is gradual; shrinking lets active jobs
finish. Queues of at most 32 items stay serial. Background media parsing is capped
at 1–4 slots with a separate foreground reserve. Set TJXY_SCAN_CONCURRENCY=1
for serial admission, or 2–8 for a fixed target bound. Fixed mode still applies
pressure protection; unavailable host samples fall back to 1. Restart after changing
this setting. More concurrency does not guarantee higher throughput; SQLite writes
remain serialized.
Unchanged storage observations no longer advance catalog revisions, and a source rebuild whose
manifest matches the active publication reuses it instead of re-indexing and re-resolving
metadata. Enqueueing a newer ResolveMetadata revision removes the item's older Pending jobs,
and queue maintenance drains Pending jobs left behind a newer revision (5,000 per pass).
TJXY_LOCAL_REFERENCE_ROOT fences absolute local references such as STRM targets to one
absolute directory; leave it unset to keep the file system root, and set it to the media mount
in production so a library file cannot point at other files on the host.
The database pool is shared by request handlers and background workers. It defaults to 20
connections with a 10 second acquire timeout; adjust with TJXY_DATABASE_MAX_CONNECTIONS
(2–200) and TJXY_DATABASE_ACQUIRE_TIMEOUT_SECONDS (1–300), and keep the total below the
PostgreSQL max_connections shared with other applications. PostgreSQL sessions end
transactions left idle for 60 seconds, and the work-notification listener uses its own
connection outside the pool. Foreground media reads hold a storage admission slot only while
the upstream connection is established and wait at most 5 seconds before answering 503 with
Retry-After.
Login attempts are limited per normalized account (10 failures in 15 minutes) and per client
address (30 failures per minute), independent of the client-supplied DeviceId; authentication
events are written to the structured tjxy_server::audit log target without credentials. Behind
a reverse proxy set TJXY_TRUSTED_PROXIES to the proxy address or CIDR (for example 127.0.0.1)
so the client address is taken from X-Forwarded-For; unset, the peer address is used and every
client behind the proxy shares one address budget. New passwords must be at least 8 characters,
the administrator password reset requires a new password, and changing or resetting a password or
disabling an account also removes that user's passkeys. Registering a passkey needs a session
token and the current password.
Periodic validation keeps a directory's children revision (the value metadata and source
indexing work is fenced on) unchanged while its listing is unchanged, and stops emitting change
events for objects it re-observes identically; only new, modified, moved, restored or removed
children advance it. Behind Cloudflare, make the reverse proxy replace the connecting address with
the real client address (for example OpenResty real_ip_header CF-Connecting-IP with Cloudflare's
published ranges in set_real_ip_from) so the per-address login budget and audit log see the
visitor instead of a Cloudflare edge node. Jellyfin clients that send ResetPassword without a
NewPw now receive 400 with a message naming NewPw.
Work completed by the running version is retained for 7 days by default. Set
TJXY_WORK_HISTORY_RETENTION_DAYS to a value from 1 through 3650, or set
TJXY_WORK_HISTORY_RETENTION_ENABLED=false to suspend retention. The retention
worker enrolls terminal work left by earlier versions in batches of up to 1,000,
then clears at most 100 jobs per short transaction. Retired publications are
re-enrolled with their job's original completion time, including publications
compacted by older versions. Active references and live work dependencies prevent
purging; deleting expired projections does not remove media files. PostgreSQL and SQLite keep
the work-claim index limited to pending and running jobs. PostgreSQL replaces
this index in the migration transaction, so the first startup after upgrading
can take longer on a large work history. Legacy processed outbox rows are removed
in bounded background batches; failed storage events are kept for seven days
after they become dead letters.
Deleting rows does not immediately shrink existing database files. After a large
history cleanup, run VACUUM (ANALYZE) during normal operations. Reclaiming file
system space requires a separately planned maintenance window for VACUUM FULL or
an online PostgreSQL reorganization tool such as pg_repack.
Jellyfin Media Player 1.11 and newer loads a server-hosted Jellyfin Web client.
TJXY can mount an operator-supplied Jellyfin Web distribution at /web/ while
keeping the TJXY application at /app/ and the administrator UI at /admin/:
TJXY_ADMIN_DIST_DIR=admin/dist \
TJXY_JELLYFIN_WEB_DIST_DIR=/usr/share/jellyfin/web \
./target/release/tjxy-serverThe configured directory must contain index.html. Jellyfin Web is GPL-2.0
licensed and is not bundled into TJXY's MIT-licensed release archives. For local
development, TJXY automatically mounts data/jellyfin-web when that directory
contains index.html; TJXY_JELLYFIN_WEB_DIST_DIR overrides this location.
When neither source is available, the server root continues to open /app/.
The current compatibility baseline is Jellyfin Web 10.11.11; newer client
releases need to be validated before changing the mounted distribution.
TJXY implements the Jellyfin direct-play subset rather than remuxing or
transcoding. Playback negotiation accepts optional or empty POST bodies and
ignores client-specific query hints that Jellyfin model binding would ignore.
The original-file endpoints accept Jellyfin's lowercase /videos and /audio
forms, their optional container suffix, and authenticated requests without a
MediaSourceId by selecting the first authorized playable source. A container
suffix such as stream.mp4 is only a route alias: it neither converts the file
nor changes the response MIME type. Direct file delivery also applies when the
static hint is absent or false; ticket-only URLs retain an explicit
ticket-bound media source. Transcoding-shaped query parameters on these
progressive endpoints are accepted as compatibility hints but still return the
original bytes and actual MIME type.
Playback state reports accept a missing or null PositionTicks and interpret
MediaSourceId=ItemId as the default media source. When Playing, Progress,
or Stopped changes watch data, the server publishes UserDataChanged to that
user; replayed events remain idempotent and do not emit another revision.
The TJXY browser client intentionally limits direct playback to containers that the browser can handle reliably and therefore does not advertise MKV. Jellyfin Media Player's native MPV path can play compatible MKV sources returned by the server. Requests for transcoding fall back to the same original-file delivery; TJXY does not expose HLS manifests or claim that an unsupported client codec can decode those bytes.
GitHub Releases provide
linux-x86_64-gnu and linux-aarch64-gnu archives for systems with glibc 2.35
or newer. The archives include the web assets, server, and TUI, so they do not
require a Rust or Node.js toolchain.
sha256sum -c --ignore-missing SHA256SUMS
tar -xzf tjxy-v0.0.1-linux-x86_64-gnu.tar.gz
cd tjxy-v0.0.1-linux-x86_64-gnu
./tjxyThe terminal console can start, stop, restart, and inspect the bundled server.
Press g to switch between English and Chinese.
Before an installation manifest exists, TJXY serves only the setup application. The wizard configures branding, database access when required, network settings, and the initial administrator. After completion:
/app/serves the ordinary media client;/admin/serves the administrator console;/health/readyreports application and database readiness; and- setup URLs redirect to the installed application.
A completed configuration contains the installation identity and database
endpoint. Do not reuse the same tjxy.toml when switching between native and
Docker runtimes or between managed and external databases. tjxy-setup detects
this situation and requires a new --config-dir instead of silently rewriting
an installation.
Source builds are for maintainers. They require Node.js 22.12 or newer, pnpm 10,
prepared frontend dependencies in admin/node_modules, and Rust 1.88 or newer
when compiling the server. HeroUI Pro is a licensed build dependency. Store
HEROUI_KEY as a GitHub Actions repository secret before publishing a release.
For a local source build, install it without committing the key:
cd admin
HEROUI_KEY="<your-key>" pnpm dlx hpsetup@latest --auto
pnpm run build
cd ..The Release workflow uses that secret only while producing admin/dist; the
published image and Linux archives already contain the built frontend. The
secret is never needed on a deployment host. To build Docker from the checkout
instead of pulling GHCR, omit --image and TJXY_IMAGE:
./tjxy-setup --runtime docker --database postgres --media /path/to/mediaFor a manual release, open Actions > Release > Run workflow and enter a
version such as 0.0.1 or v0.0.1. CI builds the current main branch and
creates the tag, GitHub Release, portable archives, and container image. An
existing tag is not required. Every push to main also creates a new GitHub
pre-release with a betaYYMMDDHHmm version based on Taipei time, such as
beta2608292011 for 2026-08-29 20:11.
The backend is a Rust 2024 workspace built on Axum and SeaORM. The frontend uses React 19, HeroUI v3, Tailwind CSS v4, and Vite.
# Frontend
pnpm --dir admin run typecheck
pnpm --dir admin run lint
pnpm --dir admin test --run
pnpm --dir admin run build
# Rust workspace
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all -- --checkDatabase tests use SQLite by default. Set TJXY_TEST_DATABASE_URL to a
disposable PostgreSQL or MySQL instance when running cross-database contracts.
Each test creates an isolated database or schema.
Managed setup PostgreSQL connections require TLS by default. Set
TJXY_SETUP_POSTGRES_TLS to disable, prefer, or require when the managed
database is supplied through environment variables. The bundled Compose stack
uses disable only for PostgreSQL traffic confined to its private Docker
network; externally reachable databases should keep the default require.
TJXY is licensed under the MIT License.