--
- -
-
-
-
-
-
-
-
-
-
-
-- -
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
+1. Pod A starts an HLS transcode and writes a `TranscodeSession` to Redis with a 30-second lease.
+2. Pod A renews the lease every `LeaseDurationSeconds / 2` seconds.
+3. If Pod A dies, the lease expires in Redis after 30 seconds.
+4. Pod B receives a client request for the same play session, calls `TryTakeoverAsync`, and atomically claims ownership via a Lua script.
+5. Pod B resumes FFmpeg from the last durable segment index. The client sees a brief stutter, not an error.
---
-## Jellyfin Server
+## Quick Start
-This repository contains the code for Jellyfin's backend server. Note that this is only one of many projects under the Jellyfin GitHub [organization](https://github.com/jellyfin/) on GitHub. If you want to contribute, you can start by checking out our [documentation](https://jellyfin.org/docs/general/contributing/index.html) to see what to work on.
+### Single instance (no Redis)
-## Server Development
+No configuration required. `NullTranscodeSessionStore` is used automatically. Behavior is identical to upstream Jellyfin.
-These instructions will help you get set up with a local development environment in order to contribute to this repository. Before you start, please be sure to completely read our [guidelines on development contributions](https://jellyfin.org/docs/general/contributing/development.html). Note that this project is supported on all major operating systems except FreeBSD, which is still incompatible.
+```bash
+dotnet run --project Jellyfin.Server/Jellyfin.Server.csproj -- \
+ --datadir /var/lib/jellyfin \
+ --webdir /usr/share/jellyfin/web
+```
+
+### HA mode with Redis
+
+Set the `Jellyfin:TranscodeStore:RedisConnectionString` configuration key. You can pass it as an environment variable, a `DOTNET_` prefixed env var, or in a JSON config file.
+
+**Environment variable:**
+
+```bash
+export Jellyfin__TranscodeStore__RedisConnectionString="redis:6379"
+export Jellyfin__TranscodeStore__LeaseDurationSeconds="30"
+
+dotnet run --project Jellyfin.Server/Jellyfin.Server.csproj -- \
+ --datadir /var/lib/jellyfin \
+ --webdir /usr/share/jellyfin/web
+```
+
+**`appsettings.json` section:**
+
+```json
+{
+ "Jellyfin": {
+ "TranscodeStore": {
+ "RedisConnectionString": "redis:6379,abortConnect=false",
+ "LeaseDurationSeconds": 30
+ }
+ }
+}
+```
+
+When `RedisConnectionString` is set, `RedisTranscodeSessionStore` is registered in DI. If the Redis connection fails at startup, the server throws and refuses to start — this is intentional so you don't silently fall back to broken HA behavior.
+
+---
+
+## Configuration Reference
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `Jellyfin:TranscodeStore:RedisConnectionString` | _(empty)_ | StackExchange.Redis connection string. Empty = single-instance mode. |
+| `Jellyfin:TranscodeStore:LeaseDurationSeconds` | `30` | How long a pod's transcode lease is valid before another pod may take over. |
+
+### Redis connection string examples
+
+```
+# Standalone Redis
+redis:6379
+
+# With password
+redis:6379,password=secret
+
+# With TLS
+redis.example.com:6380,ssl=true,abortConnect=false
+
+# Redis Sentinel
+sentinel-host:26379,serviceName=mymaster
+```
+
+Standard [StackExchange.Redis connection string format](https://stackexchange.github.io/StackExchange.Redis/Configuration) is accepted.
+
+---
+
+## Docker / Kubernetes
+
+The `Dockerfile.runtime` in this repo produces a runtime-only image. The `.NET publish` step is intended to run on the CI host (not inside Docker) for I/O performance reasons.
+
+```bash
+# Build locally
+dotnet publish Jellyfin.Server/Jellyfin.Server.csproj \
+ --configuration Release \
+ --runtime linux-x64 \
+ --self-contained false \
+ --output ./publish-output
+
+# Build image
+docker build -f Dockerfile.runtime -t jellyfin-ha:local \
+ --platform linux/amd64 .
+```
+
+**Kubernetes environment variables for HA:**
+
+```yaml
+env:
+ - name: Jellyfin__TranscodeStore__RedisConnectionString
+ valueFrom:
+ secretKeyRef:
+ name: jellyfin-redis
+ key: connection-string
+ - name: Jellyfin__TranscodeStore__LeaseDurationSeconds
+ value: "30"
+ - name: JELLYFIN_HA_POD_NAME
+ valueFrom:
+ fieldRef:
+ fieldPath: metadata.name
+```
+
+Shared storage (NFS, Longhorn RWX, or similar) must be mounted at the same path on all pods for segment file access to work across pod boundaries.
+
+---
+
+## PostgreSQL (experimental)
+
+This fork includes a PostgreSQL database provider under `src/Jellyfin.Database/Jellyfin.Database.Providers.PostgreSQL`. It is experimental — the SQLite provider remains the default and the recommended choice for most deployments.
+
+To use PostgreSQL, set the migration provider at startup and run migrations:
+
+```bash
+dotnet ef migrations add InitialCreate \
+ --project "src/Jellyfin.Database/Jellyfin.Database.Providers.PostgreSQL" \
+ -- --migration-provider Jellyfin-PostgreSQL
+```
+
+See `src/Jellyfin.Database/readme.md` for full migration instructions.
+
+---
+
+## Building and Testing
### Prerequisites
-Before the project can be built, you must first install the [.NET 9.0 SDK](https://dotnet.microsoft.com/download/dotnet) on your system.
+- [.NET 10 SDK](https://dotnet.microsoft.com/download/dotnet/10.0)
+
+### Build
+
+```bash
+dotnet build Jellyfin.Server/Jellyfin.Server.csproj
+```
+
+### Run all tests
+
+```bash
+dotnet test Jellyfin.sln \
+ --configuration Release \
+ --filter "Category!=RequiresDocker&FullyQualifiedName!~Integration"
+```
+
+### Run HA-specific tests
+
+The transcode session store and HA recovery tests live in:
+
+- `tests/Jellyfin.Server.Implementations.Tests/MediaEncoding/RedisTranscodeSessionStoreTests.cs`
+- `tests/Jellyfin.MediaEncoding.Tests/Fakes/InMemoryTranscodeSessionStore.cs`
+
+```bash
+dotnet test tests/Jellyfin.Server.Implementations.Tests \
+ --configuration Release \
+ --filter "FullyQualifiedName~TranscodeSession"
+```
+
+### Run with code coverage
+
+```bash
+dotnet test Jellyfin.sln \
+ --configuration Release \
+ --collect:"XPlat Code Coverage" \
+ --settings tests/coverletArgs.runsettings
+```
+
+---
+
+## Project Structure
+
+```
+MediaBrowser.Controller/MediaEncoding/
+ ITranscodeSessionStore.cs ← Interface (DI contract)
+ TranscodeSession.cs ← Session record model
+ TranscodeStoreOptions.cs ← Configuration options
+ NullTranscodeSessionStore.cs ← No-op, single-instance fallback
+
+Emby.Server.Implementations/MediaEncoding/
+ RedisTranscodeSessionStore.cs ← Redis-backed HA implementation
+
+src/Jellyfin.Database/
+ Jellyfin.Database.Providers.PostgreSQL/ ← Experimental PostgreSQL provider
+
+tests/
+ Jellyfin.Server.Implementations.Tests/MediaEncoding/
+ RedisTranscodeSessionStoreTests.cs
+ Jellyfin.MediaEncoding.Tests/Fakes/
+ InMemoryTranscodeSessionStore.cs
+```
+
+---
+
+## Contributing
+
+This is a personal experiment, not an officially maintained fork. Issues and PRs are welcome but response time may vary.
+
+If you're interested in getting proper HA transcoding into upstream Jellyfin, that conversation belongs in the [upstream repo](https://github.com/jellyfin/jellyfin). The changes here are deliberately narrow and designed to be upstream-friendly if there's maintainer interest.
+
+**Code conventions** follow the upstream Jellyfin rules:
+- `async`/`await` everywhere — no `.Result` or `.Wait()`
+- All public members need XML doc comments
+- Use `Directory.Packages.props` for NuGet versions — never add `Version=` to a `
-
+