Plugin: Temporal - A per-library "Date Added" control

[CrowTC 22]

  Temporal: Time Management

I've wanted to build this for years, as my own library has grown larger and more complex. Temporal replaces Emby's "Date Added" value with one derived from an item's own metadata, chosen independently for each library. No more one-size-fits-all date handling across a varied collection that doesn't work that way.

NOTE: It was compiled for Emby Server 4.10+. Source is closed, but it's free to use.

The problem

Emby's built-in "Date added behavior for new content" handling gives you a global choice: date scanned, or file creation date. That's fine until you have libraries where you want different logic. Other plugins I have used are basically an "all or nothing" that is more like a blunt instrument than a precision tool. Maybe you have a "New Releases" library where file date is genuinely useful, but you have a general TV Show/Movies library where you'd rather sort by Air Date/Premiere Date, and an old-film collection where all you really want is the production year. There was also no quick way to recover an item's original date once something has overwritten it.

Temporal makes the date source a per-library choice, and gives you an actual undo path.

What it actually changes

• Each library gets its own rule, and every rule is disabled by default. Temporal touches nothing until you explicitly turn a library on.
• Pick exactly one date source per library: Premiere Date, Production Year (Jan 1), File Created Date, or File Modified Date. No fallback chains. If the source you picked can't be resolved for an item, that item is left completely alone and shows up as "unresolved" in the run summary. It will never quietly substitute a different source.
• It only ever touches Emby's own DateCreated/DateModified fields on the items it manages. It never writes to any file on disk; file dates are read-only inputs, never outputs.
• Items with any locked metadata field are skipped by default (there's a per-library toggle if you want Temporal to override locks instead).
• Series/Season with a file-based source use the earliest file date among their child episodes, scoped to just that season, or the whole series.
• Undo is via named Library Snapshots. Save one manually from the config page at any time, and restore it later if a rule change didn't do what you wanted. Snapshots are exportable, pinnable, and covered by retention settings so they don't grow forever. (An automatic "snapshot before rule change" prompt is planned but not wired up yet. For now, snapshotting is a manual step you take yourself.)

Scope for v1: Movies, Series, Seasons, and Episodes only. No Music/Books/Photos yet. I have a few other time-related functions I've been wanting to add, so we'll see how it pans out going forward.

Real-world testing

I've been running Temporal in it's current state for about a week on a Linux/Docker Emby host, against a networked media library over CIFS. I have had no issues so far, including on the file-date sources, but see the caveat below on FileCreatedDate, since CIFS/SMB is one of the setups where filesystem "birthtime" support can be inconsistent.

Installing it

1. Unzip and drop "Emby.Temporal.Plugin.dll" into your Emby Server plugins folder.
2. Restart your Emby Server, it should pick up the plugin right away.
3. It will show up under Emby Server in the left-hand Dashboard menu as Temporal. Click it to open the config page.

Here's what the config page looks like, live on my server:

Configuring a library

On the Temporal config page, each of your libraries shows up with its own rule. I don't have any gating yet on which libraries show up, so you will just see all your libraries in the list.

Simply choose a library and the rule configuration will pop up on the right:

• Enabled: off by default. Turning it off later pauses management without undoing anything already written.
• Item Types: which of Movie/Series/Season/Episode this rule covers.
• Date Source: the single field to resolve dates from.
• Offset (days): shift the resolved date forward or backward.
• Time of Day: Midnight, Preserve Original Time, or Run Time.
• Respect Item Exclusions: on by default; controls whether locked items get skipped.

Be sure to click Save Rule if you edit the settings. 

Preview (dry-run diff, no writes) and Run Now (runs immediately, bypassing the Enabled flag) are both on the same page.

Snapshots

Before making any changes, or hitting run, it's a good idea to make a snapshot of the library, just in case the date change didn't turn out like you expected. You can optionally name snapshots for your own reference. Each snapshot can be Restored, Pinned, Exported or Deleted, everything should work as you would expect it to.

Just click Save Snapshot Now, and you don't have to worry if it messes up your dates.

NOTE: Export is mostly for reference right now, but I will support import in the future.

Global settings 

A separate tab on the config page controls settings shared across every library:

• Dry Run Default (on): whether Preview opens with dry-run pre-selected.
• Batch Size (200): items written per batch during a run.
• Throttle (ms) (250): delay between write batches, to avoid hammering the Emby database on large libraries.
• Log Verbosity (Normal): Minimal / Normal / Verbose logging.
• Max Snapshots Per Library (10): snapshot retention limit (0 = unlimited); pinned snapshots are exempt.
• Max Snapshot Age (days) (90): snapshot retention age limit (0 = unlimited); pinned snapshots are exempt.

Scheduling

Everything runs through Emby's own Scheduled Tasks, no custom scheduler:

• Temporal: Incremental Date Update: safe to run hourly or more. Only touches items changed since the library's last successful run, and skips no-op writes.
• Temporal: Full Validation Pass: re-checks every item regardless of watermark. Heavier; good for a daily/weekly cadence or a manual "Run now" after a rule change or metadata refresh.

Both respect each library's Enabled flag and skip orphaned rules (rules pointing at a library you've since removed get flagged, not deleted).

---

Feedback is welcome, especially from anyone with unusual library setups (network shares, mixed filesystems), since the file-date sources are best-effort on some of those.

Emby.Temporal.Plugin.1.0.0.40.zip

 

Edited 32 minutes ago by CrowTC
Fixing Images, removing extra file