8000 GitHub - youtonghy/TJXY · GitHub
[go: up one dir, main page]

Skip to content
youtonghyPublic

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

331 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

TJXY

TJXY

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.

Features

  • 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 check GET /ClientUpdates/Latest and download through GET /ClientUpdates/{id}/Download, which supports resumable ranges.
  • Operational tooling: health checks, structured rotating logs, a diagnostic TUI, Docker health checks, and persistent installation configuration.

Quick Start

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.

Requirements

  • Docker Engine with a recent Compose v2 plugin

Published Docker Image

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/media

TJXY_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.

Managed PostgreSQL

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.1

Choose 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 8096

The 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.

External Database

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/media

Enter 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.

Storage and Ports

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 8096

Use a TLS reverse proxy before exposing TJXY outside a trusted network.

Multiple Stream Addresses

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.

Operations and Upgrades

./tjxy-setup status
./tjxy-setup logs
./tjxy-setup stop

stop 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 Installation

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/media

To let the launcher provision PostgreSQL in Docker while TJXY runs natively:

./tjxy-setup \
  --runtime local \
  --database postgres \
  --media /path/to/media \
  --postgres-port 5433

For 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-server

Local 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-server

Optionally 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

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-server

The 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.

Linux Release Archive

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
./tjxy

The terminal console can start, stop, restart, and inspect the bundled server. Press g to switch between English and Chinese.

First-Run Setup

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/ready reports 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.

Build from Source

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/media

For 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.

Development

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 -- --check

Database 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.

Documentation

License

TJXY is licensed under the MIT License.

About

No description, website, or topics provided.

Resources

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages

0