linux-jellyfin-hotcache

alan/linux-jellyfin-hotcache

Fork 0

4 releases 4 tags

RSS feed

v1.0.3 42ea06c0d4

v1.0.3

All checks were successful

CI / fast-tests (push) Successful in 8s

Details

CI / postgresql-18 (push) Successful in 12s

Details

CI / jellyfin-sqlite (jellyfin/jellyfin:12.1) (push) Successful in 14s

Details

CI / jellyfin-sqlite (jellyfin/jellyfin:10.11.11) (push) Successful in 25s

Details

Release Build / build-release (push) Successful in 29s

Details

Stable
alan released this 2026-09-30 11:36:42 +00:00 | 0 commits to main since this release

Signed by alan

SSH key fingerprint: SHA256:yvtkLe2vkdG0Y1CCxra56JR6gjOJFURf52LUTVpWqPw
Jellyfin Hotcache v1.0.3

Jellyfin Hotcache v1.0.3 is a reporting and operator-visibility release. It builds on the cache-state reconciliation and container-safety work introduced in v1.0.1 and v1.0.2, with a clearer model for describing what happened to each promotion candidate during a run.

There are no intentional changes to the underlying cache promotion thresholds or cache-movement policy in this release.

Jellyfin Hotcache is a helper program for Jellyfin that supports both SQLite and PostgreSQL playback databases and works with bare-metal or containerized Jellyfin installations on Ubuntu and compatible Linux systems.

Hotcache identifies frequently and recently played media that meets configurable thresholds, copies it from slower storage to a specified cache location, such as an SSD, and replaces the media file at Jellyfin's original path with a symlink to the cached copy. The original media remains safely preserved on the slower storage with a renamed filename, so Jellyfin reads the SSD copy instead.

This can reduce unnecessary spin-up of NAS hard drives and provide faster access and playback startup for frequently watched media. When an item is no longer considered "hot," Hotcache can optionally demote it back to normal storage automatically.

Perfect for the kid who wants to watch the same show over and over!

Highlights

Clear final-state reporting

Qualifying media now ends each run in one mutually exclusive promotion state:
- PROMOTED — the file was successfully promoted to the hot cache.
- WAITING FOR SPACE — the item qualifies for promotion, but cache or filesystem capacity is currently insufficient. It will be reconsidered on a later run.
- DEFERRED — promotion is temporarily unsafe, such as when the media file is actively being streamed.
- BLOCKED BY POLICY — the item is excluded by a configured per-file promotion limit.
- ATTENTION REQUIRED — Hotcache found inconsistent or untracked cache state, or a promotion operation failed.
Healthy media that is already managed in the hot cache is treated as cache state rather than as a new promotion candidate.

Media below its configured promotion threshold continues to be monitored silently.

Candidate-report cleanup

The previous generic Candidates section has been removed.

A successfully promoted file can no longer also appear as an uncached candidate in the same report, and normal capacity or active-stream conditions are no longer reported as generic SKIPPED PROMOTE events.

The Hotcache summary now includes counts for:
- Pending candidates
- Waiting for space
- Deferred items
- Policy-blocked items
- Items requiring operator attention
Explicit application version

Hotcache now reports its application version directly.

Every run report includes:
```
Version: 1.0.3
```
The command-line interface also supports:
```
jellyfin-hotcache --version
```
Preflight output includes the running application version as well, and the Jellyfin API client identification now uses the actual Hotcache version rather than a fixed 1.0 value.

Operator behavior

A normal run with all qualifying media already cached should now be concise and free of false promotion noise. For example:
```
Hotcache:
  Promoted files:       109
  Hot already promoted: 109
  Pending candidates:   0
  Waiting for space:    0
  Deferred:             0
  Blocked by policy:    0
  Attention required:   0

Promoted this run:
  - None

Waiting for space:
  - None

Deferred:
  - None

Blocked by policy:
  - None

Attention required:
  - None
```
Conditions that require action are separated from temporary conditions such as capacity constraints or active playback.

Documentation and testing

This release also:
- Updates the Debian man page for --version and the new reporting states.
- Extends regression coverage for final-state reporting.
- Adds tests for promotion-outcome classification.
- Removes the obsolete internal generic candidate-report bucket.
- Updates Debian packaging to 1.0.3-1.
Release engineering

The repository now includes a Forgejo-native release-build workflow.

The workflow:
- Validates application and Debian package versions.
- Verifies release tags match the application version.
- Builds the Debian package with dpkg-buildpackage.
- Runs the package test suite.
- Runs Lintian.
- Verifies the built package metadata and packaged executable version.
- Produces release manifests and SHA-256 checksums.
- Uploads the completed artifact set for release staging.
Qualification

v1.0.3 was qualified through the normal Forgejo CI and release-build paths, including:
- Pull-request CI: PASS
- Merge CI: PASS
- Fast/unit regression tests: PASS
- PostgreSQL 18 integration: PASS
- Jellyfin SQLite integration against supported test images: PASS
- Debian package build: PASS
- Package metadata/version validation: PASS
- Lintian validation: PASS
- Forgejo release-artifact upload: PASS
The v1.0.2 production-test baseline also confirmed that existing managed cache state is reconciled correctly before the v1.0.3 reporting changes were applied.

Package

Debian package:
```
jellyfin-hotcache_1.0.3-1_all.deb
```
Release artifacts also include the corresponding .changes, .buildinfo, release manifest, and SHA-256 checksum file.

Upgrade

Existing v1.0.2 installations can be upgraded normally with the v1.0.3 Debian package.

No configuration migration is required for the reporting changes in this release.

After upgrading, verify the installed application version with:
```
jellyfin-hotcache --version
```
and optionally run a preflight check:
```
jellyfin-hotcache --config /etc/jellyfin-hotcache/config.yml --check
```
Downloads
- Source code (ZIP)
  0 downloads
- Source code (TAR.GZ)
  0 downloads
- jellyfin-hotcache-1.0.3-RELEASE-MANIFEST.txt
  0 downloads · 2026-09-30 13:25:31 +00:00 · 389 B
- jellyfin-hotcache-1.0.3-SHA256SUMS
  0 downloads · 2026-09-30 13:25:31 +00:00 · 425 B
- jellyfin-hotcache_1.0.3-1_all.deb
  0 downloads · 2026-09-30 13:25:31 +00:00 · 36 KiB
- jellyfin-hotcache_1.0.3-1_amd64.buildinfo
  0 downloads · 2026-09-30 13:25:31 +00:00 · 5.3 KiB
- jellyfin-hotcache_1.0.3-1_amd64.changes
  0 downloads · 2026-09-30 13:25:31 +00:00 · 1.5 KiB

v1.0.2 1b5adae307

v1.0.2

All checks were successful

CI / fast-tests (push) Successful in 29s

Details

CI / jellyfin-sqlite (jellyfin/jellyfin:10.11.11) (push) Successful in 34s

Details

CI / postgresql-18 (push) Successful in 39s

Details

CI / jellyfin-sqlite (jellyfin/jellyfin:12.1) (push) Successful in 45s

Details

Stable
alan released this 2026-09-27 20:00:31 +00:00 | 7 commits to main since this release

Signed by alan

SSH key fingerprint: SHA256:yvtkLe2vkdG0Y1CCxra56JR6gjOJFURf52LUTVpWqPw
Jellyfin Hotcache v1.0.2

This is a safety release for containerized Jellyfin installations.

Hotcache now verifies that the running Jellyfin process can access the configured
cache directory at the same absolute path before replacing media files with
cache symlinks. If Jellyfin is containerized and the cache path is not mounted
into the container correctly, Hotcache refuses real promotions instead of
creating media links Jellyfin cannot access.

Changes
- Detect bare-metal versus isolated/containerized Jellyfin processes.
- Verify that Jellyfin can access the configured cache root at the same absolute path.
- Refuse real promotions when Jellyfin cannot access Hotcache targets.
- Add Docker/Compose cache-bind guidance.
- Add consumer-visibility checks to --check.
- Add regression coverage for bare-metal and containerized installations.
Qualification
- CI 19: PASS
- Unit/regression suite: 56 passed, 2 expected skips
- Consumer visibility tests: PASS
- PostgreSQL 18 integration: PASS
- Production PostgreSQL preflight: PASS
- Production Jellyfin container cache visibility: PASS
- Production web playback: PASS
- Hotcache symlink audit: 98 total, 0 broken
- Debian package build: PASS
- Signed tag verification: PASS
Package

jellyfin-hotcache_1.0.2-1_all.deb

SHA256:

df312c09193d1092c543a28f35cf1b9cfcc771e7df0e70d796202d82862e2ab6
EOF
Downloads
- Source code (ZIP)
  0 downloads
- Source code (TAR.GZ)
  0 downloads
- jellyfin-hotcache-1.0.2-RELEASE-MANIFEST.txt
  0 downloads · 2026-09-27 20:02:59 +00:00 · 251 B
- jellyfin-hotcache-1.0.2-SHA256SUMS
  0 downloads · 2026-09-27 20:02:59 +00:00 · 314 B
- jellyfin-hotcache_1.0.2-1_all.deb
  1 download · 2026-09-27 20:03:00 +00:00 · 36 KiB
- jellyfin-hotcache_1.0.2-1_amd64.buildinfo
  0 downloads · 2026-09-27 20:03:00 +00:00 · 6.5 KiB
- jellyfin-hotcache_1.0.2-1_amd64.changes
  0 downloads · 2026-09-27 20:03:00 +00:00 · 1.5 KiB

v1.0.1 b2edca83be

v1.0.1

All checks were successful

CI / fast-tests (push) Successful in 8s

Details

CI / jellyfin-sqlite (jellyfin/jellyfin:10.11.11) (push) Successful in 24s

Details

CI / postgresql-18 (push) Successful in 31s

Details

CI / jellyfin-sqlite (jellyfin/jellyfin:12.1) (push) Successful in 37s

Details

Stable
alan released this 2026-09-27 14:34:58 +00:00 | 9 commits to main since this release

Signed by alan

SSH key fingerprint: SHA256:yvtkLe2vkdG0Y1CCxra56JR6gjOJFURf52LUTVpWqPw
Jellyfin Hotcache v1.0.1

This release expands playback-history compatibility, cache reporting, ZFS awareness, and managed cache-state reconciliation.

Changes
- Add stock Jellyfin core SQLite playback-history support.
- Load the optional environment file directly for command-line runs.
- Use explicit IEC units and expanded cache/category reporting.
- Add ZFS dataset, quota, refquota, pool, and available-space reporting.
- Add configurable cold-cache demotion with a 14-day default.
- Correct projected cache accounting after demotion and restore operations.
- Reconcile existing manifest-managed cache entries against on-disk state.
- Distinguish current promoted state from promotion actions and uncached candidates.
- Add promoted-file count and promoted-size reporting.
- Expand Docker-based PostgreSQL and Jellyfin integration qualification.
Qualification
- Unit suite: 49 passed, 2 expected skips
- PostgreSQL 18 integration: PASS
- Jellyfin 10.11.11 core SQLite integration: PASS
- Jellyfin 12.1 core SQLite integration: PASS
- Production --check: PASS, 0 warnings
- Production ZFS dry-run: PASS
- Debian package build: PASS
- Lintian Debian profile: clean
- SHA256 verification: PASS
Package

jellyfin-hotcache_1.0.1-1_all.deb

SHA256:

6199ca5fb3bfad58830333a06a5c9a579d791ff1524372d6fa30a7ede1ac16ca
Downloads
- Source code (ZIP)
  0 downloads
- Source code (TAR.GZ)
  0 downloads
- jellyfin-hotcache-1.0.1-RELEASE-MANIFEST.txt
  0 downloads · 2026-09-27 14:36:52 +00:00 · 252 B
- jellyfin-hotcache-1.0.1-SHA256SUMS
  0 downloads · 2026-09-27 14:36:52 +00:00 · 314 B
- jellyfin-hotcache_1.0.1-1_all.deb
  0 downloads · 2026-09-27 14:36:52 +00:00 · 33 KiB
- jellyfin-hotcache_1.0.1-1_amd64.buildinfo
  0 downloads · 2026-09-27 14:36:52 +00:00 · 6.5 KiB
- jellyfin-hotcache_1.0.1-1_amd64.changes
  0 downloads · 2026-09-27 14:36:52 +00:00 · 1.7 KiB

v1.0.0 c6a846a1df

v1.0.0 Stable
alan released this 2026-09-27 00:13:07 +00:00 | 21 commits to main since this release

Signed by alan

SSH key fingerprint: SHA256:yvtkLe2vkdG0Y1CCxra56JR6gjOJFURf52LUTVpWqPw
Jellyfin Hotcache 1.0.0

First formal release of Jellyfin Hotcache.

Jellyfin Hotcache maintains a local hot cache of frequently accessed Jellyfin media while preserving the original Jellyfin library paths.

Highlights
- Playback-aware media promotion and demotion
- PostgreSQL and SQLite playback-history support
- Active-stream protection
- Preserved source originals with symlink-based cache routing
- Per-category cache limits for video and music
- Manifest tracking and orphan detection
- Single-run locking
- Fail-closed Jellyfin session and playback-history checks
- Read-only --check preflight mode
- Environment-based secret handling
- Debian package with systemd service and timer
- GPL-3.0-or-later
Validation

This release was qualified with:
- 22 passing regression tests
- PostgreSQL 18 integration testing
- Clean Debian package build
- Clean Lintian result
- Production migration from the previous manual installation
- Successful production cache population
- Post-run integrity check: CHECK: PASS (0 warnings)
Installation

Install the Debian package:
```
sudo apt install ./jellyfin-hotcache_1.0.0-1_all.deb
```
Create the operator-owned configuration:
```
sudo cp /usr/share/jellyfin-hotcache/config.yml.example \
    /etc/jellyfin-hotcache/config.yml

sudo chmod 0600 /etc/jellyfin-hotcache/config.yml
```
Secrets may be placed in:
```
/etc/jellyfin-hotcache/environment
```
Before enabling scheduled operation:
```
sudo jellyfin-hotcache --check
```
The package intentionally does not enable or start the timer automatically.

After configuration and a successful preflight check, enable the timer with:
```
sudo systemctl enable --now jellyfin-hotcache.timer
```
Release identity

Tag:
```
v1.0.0
```
Commit:
```
c6a846a1df853f987048e905237e7422f30a0140
```
Tree:
```
7874e5063792ef48c6a14546e7e50777fe63ed7d
```
Debian package:
```
jellyfin-hotcache_1.0.0-1_all.deb
```
SHA256:
```
cc28b75d8d4472ae1b6f51cdad07048203a7e48364223d69e4f2f755b8f57d90
```
Release assets
- jellyfin-hotcache_1.0.0-1_all.deb
- jellyfin-hotcache_1.0.0-1_amd64.buildinfo
- jellyfin-hotcache-1.0.0-RELEASE-MANIFEST.txt
- jellyfin-hotcache-1.0.0-SHA256SUMS
Downloads
- Source code (ZIP)
  0 downloads
- Source code (TAR.GZ)
  0 downloads
- jellyfin-hotcache-1.0.0-RELEASE-MANIFEST.txt
  0 downloads · 2026-09-27 00:25:21 +00:00 · 252 B
- jellyfin-hotcache-1.0.0-SHA256SUMS
  0 downloads · 2026-09-27 00:25:21 +00:00 · 319 B
- jellyfin-hotcache_1.0.0-1_all.deb
  0 downloads · 2026-09-27 00:25:21 +00:00 · 24 KiB
- jellyfin-hotcache_1.0.0-1_amd64.buildinfo
  0 downloads · 2026-09-27 00:25:21 +00:00 · 6.5 KiB
- jellyfin-hotcache_1.0.0-1_amd64.changes
  0 downloads · 2026-09-27 00:25:21 +00:00 · 1.4 KiB

Jellyfin Hotcache v1.0.3

Highlights

Clear final-state reporting

Candidate-report cleanup

Explicit application version

Operator behavior

Documentation and testing

Release engineering

Qualification

Package

Upgrade

Jellyfin Hotcache v1.0.2

Changes

Qualification

Package

Jellyfin Hotcache v1.0.1

Changes

Qualification

Package

v1.0.0 Stable

Jellyfin Hotcache 1.0.0

Highlights

Validation

Installation

Release identity

Release assets