K-TV turns your Jellyfin library (or any compatible media source) into broadcast-style TV channels with wall-clock scheduling. Instead of scrolling for what to watch, you tune into your "90s Sitcom Network" or "Friday Night Horror" channel and let the schedule run.

Architecture

The backend is a Cargo workspace with three crates following Hexagonal (Ports & Adapters) architecture:

k-tv-backend/
├── domain/   # Pure business logic — no I/O, no frameworks
├── infra/    # Adapters: SQLite/Postgres repositories, Jellyfin HTTP client
└── api/      # Axum HTTP server — routes, DTOs, startup wiring

The domain defines ports (traits). Infra implements them. The API wires everything together. The domain never imports from infra or api.

Quick Start

cp .env.example .env
# Edit .env — minimum required: JELLYFIN_BASE_URL, JELLYFIN_API_KEY, JELLYFIN_USER_ID
cargo run

The API is available at http://localhost:3000/api/v1/.

Configuration

All configuration is via environment variables. See .env.example.

Server

Variable	Default	Description
`HOST`	`127.0.0.1`	Bind address
`PORT`	`3000`	Listen port

Database

Variable	Default	Description
`DATABASE_URL`	`sqlite:data.db?mode=rwc`	SQLite or Postgres connection string
`DB_MAX_CONNECTIONS`	`5`	Connection pool max size
`DB_MIN_CONNECTIONS`	`1`	Connection pool min size

Authentication

Variable	Default	Description
`JWT_SECRET`	(insecure dev default)	Signing key for JWT tokens (min 32 chars in production)
`JWT_EXPIRY_HOURS`	`24`	Token lifetime in hours
`JWT_ISSUER`	—	Optional issuer claim embedded in tokens
`JWT_AUDIENCE`	—	Optional audience claim embedded in tokens
`COOKIE_SECRET`	(insecure dev default)	Encrypts OIDC state cookie (min 64 chars in production)
`SECURE_COOKIE`	`false`	Set `true` when serving over HTTPS

OIDC (optional — requires `auth-oidc` feature)

Variable	Description
`OIDC_ISSUER`	Identity provider URL (Keycloak, Auth0, Zitadel, etc.)
`OIDC_CLIENT_ID`	OIDC client ID
`OIDC_CLIENT_SECRET`	OIDC client secret
`OIDC_REDIRECT_URL`	Callback URL — must be `http(s)://<host>/api/v1/auth/callback`
`OIDC_RESOURCE_ID`	Optional audience claim to verify

OIDC state (CSRF token, PKCE verifier, nonce) is stored in a short-lived encrypted cookie — no database session table required.

Jellyfin

Variable	Description
`JELLYFIN_BASE_URL`	Base URL of your Jellyfin instance, e.g. `http://192.168.1.10:8096`
`JELLYFIN_API_KEY`	API key — Jellyfin Dashboard → API Keys
`JELLYFIN_USER_ID`	User ID used for library browsing

If Jellyfin variables are not set, the server starts normally but schedule generation endpoints return an error. Channel CRUD and auth still work.

CORS & Production

Variable	Default	Description
`CORS_ALLOWED_ORIGINS`	`http://localhost:5173`	Comma-separated allowed origins
`PRODUCTION`	`false`	Enforces minimum secret lengths when `true`

Feature Flags

# api/Cargo.toml defaults
default = ["sqlite", "auth-jwt", "jellyfin"]

Feature	Description
`sqlite`	SQLite database (default)
`postgres`	PostgreSQL database
`auth-jwt`	JWT Bearer token authentication
`auth-oidc`	OpenID Connect integration
`jellyfin`	Jellyfin media provider adapter

API Reference

All endpoints are under /api/v1/. Endpoints marked Bearer require an Authorization: Bearer <token> header.

Authentication

Method	Path	Auth	Description
`POST`	`/auth/register`	—	Register with email + password → JWT
`POST`	`/auth/login`	—	Login with email + password → JWT
`POST`	`/auth/logout`	—	Returns 200; client discards the token
`GET`	`/auth/me`	Bearer	Current user info
`POST`	`/auth/token`	Bearer	Issue a fresh JWT (`auth-jwt`)
`GET`	`/auth/login/oidc`	—	Start OIDC flow (`auth-oidc`)
`GET`	`/auth/callback`	—	Complete OIDC flow → JWT (`auth-oidc`)

Channels

Method	Path	Auth	Description
`GET`	`/channels`	Bearer	List all channels owned by the current user
`POST`	`/channels`	Bearer	Create a channel
`GET`	`/channels/:id`	Bearer	Get a channel
`PUT`	`/channels/:id`	Bearer	Update a channel — only provided fields change
`DELETE`	`/channels/:id`	Bearer	Delete a channel and all its schedules

Schedule & Broadcast

Method	Path	Auth	Description
`POST`	`/channels/:id/schedule`	Bearer	Generate a fresh 48-hour schedule (replaces existing)
`GET`	`/channels/:id/schedule`	Bearer	Get the currently active 48-hour schedule
`GET`	`/channels/:id/now`	Bearer	What is playing right now — `204` means no-signal (gap between blocks)
`GET`	`/channels/:id/epg?from=&until=`	Bearer	EPG slots overlapping a time window (RFC3339 datetimes)
`GET`	`/channels/:id/stream`	Bearer	`307` redirect to the current item's stream URL — `204` if no-signal

Other

Method	Path	Auth	Description
`GET`	`/config`	—	Server configuration flags

Examples

Register and get a token

curl -s -X POST http://localhost:3000/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "password": "yourpassword"}' | jq .

# → {"access_token": "eyJ...", "token_type": "Bearer", "expires_in": 86400}
TOKEN="eyJ..."

Create a channel

curl -s -X POST http://localhost:3000/api/v1/channels \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "90s Sitcom Network",
    "description": "Nothing but classic sitcoms, all day",
    "timezone": "America/New_York"
  }' | jq .id

Design a schedule

The schedule_config is the shareable programming template. Each block describes a time window and how to fill it. The channel's timezone determines when each block starts.

curl -s -X PUT http://localhost:3000/api/v1/channels/<id> \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule_config": {
      "blocks": [
        {
          "id": "00000000-0000-0000-0000-000000000001",
          "name": "Evening Sitcoms",
          "start_time": "20:00:00",
          "duration_mins": 120,
          "content": {
            "type": "algorithmic",
            "filter": {
              "content_type": "episode",
              "genres": ["Comedy"],
              "decade": 1990,
              "min_duration_secs": 1200,
              "max_duration_secs": 1800,
              "collections": [],
              "tags": []
            },
            "strategy": "random"
          }
        },
        {
          "id": "00000000-0000-0000-0000-000000000002",
          "name": "Late Night Movie",
          "start_time": "22:00:00",
          "duration_mins": 150,
          "content": {
            "type": "algorithmic",
            "filter": {
              "content_type": "movie",
              "genres": ["Comedy"],
              "decade": null,
              "min_duration_secs": null,
              "max_duration_secs": null,
              "collections": [],
              "tags": []
            },
            "strategy": "best_fit"
          }
        }
      ]
    }
  }' | jq .

Blocks that don't cover the full 24 hours leave gaps — the client renders those as a no-signal screen.

For a manual block, use "type": "manual" with an "items" array of Jellyfin item IDs:

{
  "type": "manual",
  "items": ["abc123", "def456", "ghi789"]
}

Generate and tune in

# Generate the 48-hour schedule from now
curl -s -X POST http://localhost:3000/api/v1/channels/<id>/schedule \
  -H "Authorization: Bearer $TOKEN" | jq '{generation: .generation, slots: (.slots | length)}'

# What is playing right now?
curl -s http://localhost:3000/api/v1/channels/<id>/now \
  -H "Authorization: Bearer $TOKEN" \
  | jq '{title: .slot.item.title, offset_secs: .offset_secs}'
# → 204 No Content if the channel is in a gap between blocks

# EPG for the next 4 hours (RFC3339 datetimes)
FROM=$(date -u +%Y-%m-%dT%H:%M:%SZ)
UNTIL=$(date -u -d '+4 hours' +%Y-%m-%dT%H:%M:%SZ)   # Linux
# UNTIL=$(date -u -v+4H +%Y-%m-%dT%H:%M:%SZ)          # macOS
curl -s "http://localhost:3000/api/v1/channels/<id>/epg?from=$FROM&until=$UNTIL" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '[.[] | {title: .item.title, start: .start_at, end: .end_at}]'

# Get the stream redirect for the current item (feed into your player)
curl -s -I http://localhost:3000/api/v1/channels/<id>/stream \
  -H "Authorization: Bearer $TOKEN"
# → HTTP/1.1 307 Temporary Redirect
# → Location: http://jellyfin:8096/Videos/<id>/stream?static=true&api_key=...

Key Domain Concepts

Channel

A named broadcast channel owned by a user. Holds a schedule_config (the programming template) and a recycle_policy.

ScheduleConfig

The shareable programming template: an ordered list of ProgrammingBlocks. Channels do not need to cover all 24 hours — gaps are valid and produce a no-signal state.

ProgrammingBlock

Each block occupies a time-of-day window and is either:

Algorithmic — the engine selects items from the media provider using a MediaFilter and a FillStrategy
Manual — the user hand-picks specific items by ID in a specific order

MediaFilter

Provider-agnostic filter used by algorithmic blocks:

Field	Description
`content_type`	`"movie"`, `"episode"`, or `"short"`
`genres`	List of genre strings, e.g. `["Comedy", "Action"]`
`decade`	Starting year of a decade — `1990` means 1990–1999
`tags`	Provider tag strings
`min_duration_secs` / `max_duration_secs`	Duration bounds for item selection
`collections`	Abstract groupings (Jellyfin library IDs, Plex sections, folder paths, etc.)

FillStrategy

How an algorithmic block fills its time budget:

Value	Behaviour
`best_fit`	Greedy bin-packing — picks the longest item that still fits, minimises dead air
`sequential`	Items in provider order — good for series where episode sequence matters
`random`	Shuffle pool then fill — good for variety channels

RecyclePolicy

Controls when previously aired items become eligible again:

Field	Description
`cooldown_days`	Don't replay an item within this many calendar days
`cooldown_generations`	Don't replay within this many schedule generations
`min_available_ratio`	Always keep at least this fraction (0.0–1.0) of the matching pool selectable, even if their cooldown hasn't expired. Prevents small libraries from running dry.

No-signal state

GET /channels/:id/now and GET /channels/:id/stream return 204 No Content when the current time falls in a gap between blocks. The frontend should display static / noise in this case — matching the broadcast TV experience.

GeneratedSchedule

A resolved 48-hour program: concrete UTC wall-clock timestamps for every scheduled item. Generated on demand via POST /channels/:id/schedule. The generation counter increments on each regeneration and drives the recycle policy.

Development

Run tests

cargo test            # all crates
cargo test -p domain  # domain unit tests only

Run migrations manually

sqlx migrate run --source migrations_sqlite    # SQLite
sqlx migrate run --source migrations_postgres  # PostgreSQL

Build variants

# Default: SQLite + JWT + Jellyfin
cargo build

# Add OIDC
cargo build -F sqlite,auth-jwt,auth-oidc,jellyfin

# PostgreSQL variant
cargo build --no-default-features -F postgres,auth-jwt,jellyfin

Docker

docker compose up

See compose.yml for the configuration.

Project Structure

k-tv-backend/
├── domain/src/
│   ├── entities.rs           # Channel, ProgrammingBlock, GeneratedSchedule,
│   │                         #   ScheduledSlot, MediaItem, PlaybackRecord, User, ...
│   ├── value_objects.rs      # MediaFilter, FillStrategy, RecyclePolicy,
│   │                         #   MediaItemId, ContentType, Email, ...
│   ├── ports.rs              # IMediaProvider trait
│   ├── repositories.rs       # ChannelRepository, ScheduleRepository, UserRepository
│   ├── services.rs           # ChannelService, ScheduleEngineService, UserService
│   └── errors.rs             # DomainError
│
├── infra/src/
│   ├── channel_repository.rs    # SQLite + Postgres ChannelRepository adapters
│   ├── schedule_repository.rs   # SQLite + Postgres ScheduleRepository adapters
│   ├── user_repository.rs       # SQLite + Postgres UserRepository adapters
│   ├── jellyfin.rs              # Jellyfin IMediaProvider adapter
│   ├── auth/
│   │   ├── jwt.rs               # JWT create + validate
│   │   └── oidc.rs              # OIDC flow (stateless cookie state)
│   ├── db.rs                    # Connection pool
│   └── factory.rs               # Repository builder functions
│
├── api/src/
│   ├── routes/
│   │   ├── auth.rs              # /auth/* endpoints
│   │   ├── channels.rs          # /channels/* endpoints (CRUD, EPG, broadcast)
│   │   └── config.rs            # /config endpoint
│   ├── config.rs                # Config::from_env()
│   ├── state.rs                 # AppState
│   ├── extractors.rs            # CurrentUser (JWT Bearer extractor)
│   ├── error.rs                 # ApiError → HTTP status mapping
│   ├── dto.rs                   # All request + response types
│   └── main.rs                  # Startup wiring
│
├── migrations_sqlite/
├── migrations_postgres/
├── .env.example
└── compose.yml

License

MIT

README.md Unescape Escape

K-TV Backend

Architecture

Quick Start

Configuration

Server

Database

Authentication

OIDC (optional — requires auth-oidc feature)

Jellyfin

CORS & Production

Feature Flags

API Reference

Authentication

Channels

Schedule & Broadcast

Other

Examples

Register and get a token

Create a channel

Design a schedule

Generate and tune in

Key Domain Concepts

Channel

ScheduleConfig

ProgrammingBlock

MediaFilter

FillStrategy

RecyclePolicy

No-signal state

GeneratedSchedule

Development

Run tests

Run migrations manually

Build variants

Docker

Project Structure

License

README.md

OIDC (optional — requires `auth-oidc` feature)