4 releases 4 tags

RSS feed

• v1.0.3 42ea06c0d4

  Compare

  v1.0.3 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