Air Date Fixer — Corrects upcoming dates for your timezone outside the US

[Blueskies278 89]

Currently Alpha, Not Yet Released

 

If you're outside the US, you've probably noticed some shows appear in your Upcoming/Latest lists a day early (or late) — a show airing at 8–10pm US Eastern actually lands in the early hours of the next day in UK/European time, but Emby often shows the raw US broadcast date instead.

I originally built this as a standalone Docker container/script. After 3 months of testing ironing out the bugs, I decided it was worth turning into a proper Emby plugin so it's easier to set up and run natively.

I'm now running the plugin version on my UGEEN iDX6011 Pro through about 4 weeks of real-world testing before considering a beta release. If there's genuine interest, I'll release the first beta once testing wraps up — just wanted to gauge interest and share what's coming.

Air Date Fixer corrects this automatically, using Trakt's timezone-aware broadcast schedule data:

• Pulls each show's real broadcast timezone and converts it properly to your own local date
• Only touches US/Canada-broadcast shows — everything else is left untouched
• Works across three levels: episodes you already have files for, episodes already in your library without files yet, and future/upcoming episodes that only exist in cached metadata (so it also fixes what shows up under "Yesterday"/upcoming date headings, not just episode detail pages)
• Runs automatically in the background — no manual scripts or cron jobs needed
• Self-heals if Emby's own metadata refresh reverts a date

Requires a (free) Trakt account and API app (no VIP needed) — this is needed because Trakt is the only source that tells the plugin what time of day and timezone a show actually airs in (e.g. "8pm US Eastern"), which is the missing piece needed to work out whether it lands on a different calendar day once converted to your local time. Metadata sources like TMDB only give a plain date with no time/timezone attached, so there's nothing there to calculate the correction from.

Edited July 11 by Blueskies278

[sh0rty 768]

Really interested. The upcomng section for non US users was always bothering me. There was a project almost a decade ago that replaced US airdates with european ones, but it unfortunately died.

[Blueskies278 89]

9 hours ago, sh0rty said:

Really interested. The upcomng section for non US users was always bothering me. There was a project almost a decade ago that replaced US airdates with european ones, but it unfortunately died.

The date issues for non-US users also bothered me. Air Date Fixer is created from the ground up. The Alpha plugin is about 97% done, just a few more tweaks.

[Blueskies278 89]

I’ve encountered a significant bug that requires a full rebuild. I apologize for the delay and will keep you updated on our progress.

[Blueskies278 89]

Please note that Alpha 1 is in very early development. Unfortunately, it's only compatible with Emby Server version 4.9.5.0.

While I haven't encountered any issues with Alpha 1, there may be many bugs you might encounter with your setup. Please use with caution.

I'm currently working on a more robust version of the Air Date Fixer plugin, and it's looking very promising so far.

 

 

 

 

 

EmbyAirDateFixer.dll

Edited July 26 by Blueskies278

[sh0rty 768]

OK, I set everything up. But thhe Plugin does not work on my system. Airdates in TV Show Forecast did not change.

2026-07-27 11:26:21.347 Error App: [AirDateFixer] Failed to write external token backup to 'C:\Users\blingbling\AppData\Roaming\Emby-Server\programdata\plugins\AirDateFixerBackup' - fresh-install self-healing will not work until this path is writable
	*** Error Report ***
	Version: 4.9.5.0
	Command line: C:\Users\blingbling\AppData\Roaming\Emby-Server\system\EmbyServer.dll -service
	Operating system: Microsoft Windows 10.0.26200
	OS/Process: x64/x64
	Framework: .NET 8.0.27
	Runtime: C:/Users/blingbling/AppData/Roaming/Emby-Server/system/System.Private.CoreLib.dll
	Processor count: 4
	Data path: C:\Users\blingbling\AppData\Roaming\Emby-Server\programdata
	Application path: C:\Users\blingbling\AppData\Roaming\Emby-Server\system
	System.UnauthorizedAccessException: System.UnauthorizedAccessException: Access to the path 'C:\Users\blingbling\AppData\Roaming\Emby-Server\programdata\plugins\AirDateFixerBackup' is denied.
	   at Microsoft.Win32.SafeHandles.SafeFileHandle.CreateFile(String fullPath, FileMode mode, FileAccess access, FileShare share, FileOptions options)
	   at Microsoft.Win32.SafeHandles.SafeFileHandle.Open(String fullPath, FileMode mode, FileAccess access, FileShare share, FileOptions options, Int64 preallocationSize, Nullable`1 unixCreateMode)
	   at System.IO.File.WriteToFile(String path, FileMode mode, String contents, Encoding encoding)
	   at EmbyAirDateFixer.TraktEntryPoint.SaveTokens(TokenData tokens)
	Source: System.Private.CoreLib
	TargetSite: Microsoft.Win32.SafeHandles.SafeFileHandle CreateFile(System.String, System.IO.FileMode, System.IO.FileAccess, System.IO.FileShare, System.IO.FileOptions)
	
2026-07-27 11:26:21.347 Info App: [AirDateFixer] === LoadOrSeedTokens returned: non-null ===
2026-07-27 11:26:21.347 Info App: [AirDateFixer] Starting refresh. Target timezone: W. Europe Standard Time
2026-07-27 11:26:21.902 Error App: [AirDateFixer] Failed to fetch episode from https://api.trakt.tv/shows/agatha-all-along/next_episode?extended=full
	*** Error Report ***
	Version: 4.9.5.0
	Command line: C:\Users\blingbling\AppData\Roaming\Emby-Server\system\EmbyServer.dll -service
	Operating system: Microsoft Windows 10.0.26200
	OS/Process: x64/x64
	Framework: .NET 8.0.27
	Runtime: C:/Users/blingbling/AppData/Roaming/Emby-Server/system/System.Private.CoreLib.dll
	Processor count: 4
	Data path: C:\Users\blingbling\AppData\Roaming\Emby-Server\programdata
	Application path: C:\Users\blingbling\AppData\Roaming\Emby-Server\system
	System.Text.Json.JsonReaderException: System.Text.Json.JsonReaderException: The input does not contain any JSON tokens. Expected the input to start with a valid JSON token, when isFinalBlock is true. LineNumber: 0 | BytePositionInLine: 0.
	   at System.Text.Json.ThrowHelper.ThrowJsonReaderException(Utf8JsonReader& json, ExceptionResource resource, Byte nextByte, ReadOnlySpan`1 bytes)
	   at System.Text.Json.JsonDocument.Parse(ReadOnlySpan`1 utf8JsonSpan, JsonReaderOptions readerOptions, MetadataDb& database, StackRowStack& stack)
	   at System.Text.Json.JsonDocument.Parse(ReadOnlyMemory`1 utf8Json, JsonReaderOptions readerOptions, Byte[] extraRentedArrayPoolBytes, PooledByteBufferWriter extraPooledByteBufferWriter)
	   at System.Text.Json.JsonDocument.ParseAsyncCore(Stream utf8Json, JsonDocumentOptions options, CancellationToken cancellationToken)
	   at EmbyAirDateFixer.TraktEntryPoint.FetchAndCacheEpisode(String url, String tmdbId, TokenData tokens, TimeZoneInfo targetTz, String showTimezoneId)
	Source: System.Text.Json
	TargetSite: Void ThrowJsonReaderException(System.Text.Json.Utf8JsonReader ByRef, System.Text.Json.ExceptionResource, Byte, System.ReadOnlySpan`1[System.Byte])
	
2026-07-27 11:26:22.928 Error App: [AirDateFixer] Failed to fetch episode from https://api.trakt.tv/shows/ahsoka/next_episode?extended=full
	*** Error Report ***
	Version: 4.9.5.0
	Command line: C:\Users\blingbling\AppData\Roaming\Emby-Server\system\EmbyServer.dll -service
	Operating system: Microsoft Windows 10.0.26200
	OS/Process: x64/x64
	Framework: .NET 8.0.27
	Runtime: C:/Users/blingbling/AppData/Roaming/Emby-Server/system/System.Private.CoreLib.dll
	Processor count: 4
	Data path: C:\Users\blingbling\AppData\Roaming\Emby-Server\programdata
	Application path: C:\Users\blingbling\AppData\Roaming\Emby-Server\system
	System.Text.Json.JsonReaderException: System.Text.Json.JsonReaderException: The input does not contain any JSON tokens. Expected the input to start with a valid JSON token, when isFinalBlock is true. LineNumber: 0 | BytePositionInLine: 0.
	   at System.Text.Json.ThrowHelper.ThrowJsonReaderException(Utf8JsonReader& json, ExceptionResource resource, Byte nextByte, ReadOnlySpan`1 bytes)
	   at System.Text.Json.JsonDocument.Parse(ReadOnlySpan`1 utf8JsonSpan, JsonReaderOptions readerOptions, MetadataDb& database, StackRowStack& stack)
	   at System.Text.Json.JsonDocument.Parse(ReadOnlyMemory`1 utf8Json, JsonReaderOptions readerOptions, Byte[] extraRentedArrayPoolBytes, PooledByteBufferWriter extraPooledByteBufferWriter)
	   at System.Text.Json.JsonDocument.ParseAsyncCore(Stream utf8Json, JsonDocumentOptions options, CancellationToken cancellationToken)
	   at EmbyAirDateFixer.TraktEntryPoint.FetchAndCacheEpisode(String url, String tmdbId, TokenData tokens, TimeZoneInfo targetTz, String showTimezoneId)
	Source: System.Text.Json
	TargetSite: Void ThrowJsonReaderException(System.Text.Json.Utf8JsonReader ByRef, System.Text.Json.ExceptionResource, Byte, System.ReadOnlySpan`1[System.Byte])

Clicking a Series Link form the error logs gives me this:

Edited July 27 by sh0rty

[Blueskies278 89]

7 hours ago, sh0rty said:

OK, I set everything up. But thhe Plugin does not work on my system. Airdates in TV Show Forecast did not change.

2026-07-27 11:26:21.347 Error App: [AirDateFixer] Failed to write external token backup to 'C:\Users\blingbling\AppData\Roaming\Emby-Server\programdata\plugins\AirDateFixerBackup' - fresh-install self-healing will not work until this path is writable
	*** Error Report ***
	Version: 4.9.5.0
	Command line: C:\Users\blingbling\AppData\Roaming\Emby-Server\system\EmbyServer.dll -service
	Operating system: Microsoft Windows 10.0.26200
	OS/Process: x64/x64
	Framework: .NET 8.0.27
	Runtime: C:/Users/blingbling/AppData/Roaming/Emby-Server/system/System.Private.CoreLib.dll
	Processor count: 4
	Data path: C:\Users\blingbling\AppData\Roaming\Emby-Server\programdata
	Application path: C:\Users\blingbling\AppData\Roaming\Emby-Server\system
	System.UnauthorizedAccessException: System.UnauthorizedAccessException: Access to the path 'C:\Users\blingbling\AppData\Roaming\Emby-Server\programdata\plugins\AirDateFixerBackup' is denied.
	   at Microsoft.Win32.SafeHandles.SafeFileHandle.CreateFile(String fullPath, FileMode mode, FileAccess access, FileShare share, FileOptions options)
	   at Microsoft.Win32.SafeHandles.SafeFileHandle.Open(String fullPath, FileMode mode, FileAccess access, FileShare share, FileOptions options, Int64 preallocationSize, Nullable`1 unixCreateMode)
	   at System.IO.File.WriteToFile(String path, FileMode mode, String contents, Encoding encoding)
	   at EmbyAirDateFixer.TraktEntryPoint.SaveTokens(TokenData tokens)
	Source: System.Private.CoreLib
	TargetSite: Microsoft.Win32.SafeHandles.SafeFileHandle CreateFile(System.String, System.IO.FileMode, System.IO.FileAccess, System.IO.FileShare, System.IO.FileOptions)
	
2026-07-27 11:26:21.347 Info App: [AirDateFixer] === LoadOrSeedTokens returned: non-null ===
2026-07-27 11:26:21.347 Info App: [AirDateFixer] Starting refresh. Target timezone: W. Europe Standard Time
2026-07-27 11:26:21.902 Error App: [AirDateFixer] Failed to fetch episode from https://api.trakt.tv/shows/agatha-all-along/next_episode?extended=full
	*** Error Report ***
	Version: 4.9.5.0
	Command line: C:\Users\blingbling\AppData\Roaming\Emby-Server\system\EmbyServer.dll -service
	Operating system: Microsoft Windows 10.0.26200
	OS/Process: x64/x64
	Framework: .NET 8.0.27
	Runtime: C:/Users/blingbling/AppData/Roaming/Emby-Server/system/System.Private.CoreLib.dll
	Processor count: 4
	Data path: C:\Users\blingbling\AppData\Roaming\Emby-Server\programdata
	Application path: C:\Users\blingbling\AppData\Roaming\Emby-Server\system
	System.Text.Json.JsonReaderException: System.Text.Json.JsonReaderException: The input does not contain any JSON tokens. Expected the input to start with a valid JSON token, when isFinalBlock is true. LineNumber: 0 | BytePositionInLine: 0.
	   at System.Text.Json.ThrowHelper.ThrowJsonReaderException(Utf8JsonReader& json, ExceptionResource resource, Byte nextByte, ReadOnlySpan`1 bytes)
	   at System.Text.Json.JsonDocument.Parse(ReadOnlySpan`1 utf8JsonSpan, JsonReaderOptions readerOptions, MetadataDb& database, StackRowStack& stack)
	   at System.Text.Json.JsonDocument.Parse(ReadOnlyMemory`1 utf8Json, JsonReaderOptions readerOptions, Byte[] extraRentedArrayPoolBytes, PooledByteBufferWriter extraPooledByteBufferWriter)
	   at System.Text.Json.JsonDocument.ParseAsyncCore(Stream utf8Json, JsonDocumentOptions options, CancellationToken cancellationToken)
	   at EmbyAirDateFixer.TraktEntryPoint.FetchAndCacheEpisode(String url, String tmdbId, TokenData tokens, TimeZoneInfo targetTz, String showTimezoneId)
	Source: System.Text.Json
	TargetSite: Void ThrowJsonReaderException(System.Text.Json.Utf8JsonReader ByRef, System.Text.Json.ExceptionResource, Byte, System.ReadOnlySpan`1[System.Byte])
	
2026-07-27 11:26:22.928 Error App: [AirDateFixer] Failed to fetch episode from https://api.trakt.tv/shows/ahsoka/next_episode?extended=full
	*** Error Report ***
	Version: 4.9.5.0
	Command line: C:\Users\blingbling\AppData\Roaming\Emby-Server\system\EmbyServer.dll -service
	Operating system: Microsoft Windows 10.0.26200
	OS/Process: x64/x64
	Framework: .NET 8.0.27
	Runtime: C:/Users/blingbling/AppData/Roaming/Emby-Server/system/System.Private.CoreLib.dll
	Processor count: 4
	Data path: C:\Users\blingbling\AppData\Roaming\Emby-Server\programdata
	Application path: C:\Users\blingbling\AppData\Roaming\Emby-Server\system
	System.Text.Json.JsonReaderException: System.Text.Json.JsonReaderException: The input does not contain any JSON tokens. Expected the input to start with a valid JSON token, when isFinalBlock is true. LineNumber: 0 | BytePositionInLine: 0.
	   at System.Text.Json.ThrowHelper.ThrowJsonReaderException(Utf8JsonReader& json, ExceptionResource resource, Byte nextByte, ReadOnlySpan`1 bytes)
	   at System.Text.Json.JsonDocument.Parse(ReadOnlySpan`1 utf8JsonSpan, JsonReaderOptions readerOptions, MetadataDb& database, StackRowStack& stack)
	   at System.Text.Json.JsonDocument.Parse(ReadOnlyMemory`1 utf8Json, JsonReaderOptions readerOptions, Byte[] extraRentedArrayPoolBytes, PooledByteBufferWriter extraPooledByteBufferWriter)
	   at System.Text.Json.JsonDocument.ParseAsyncCore(Stream utf8Json, JsonDocumentOptions options, CancellationToken cancellationToken)
	   at EmbyAirDateFixer.TraktEntryPoint.FetchAndCacheEpisode(String url, String tmdbId, TokenData tokens, TimeZoneInfo targetTz, String showTimezoneId)
	Source: System.Text.Json
	TargetSite: Void ThrowJsonReaderException(System.Text.Json.Utf8JsonReader ByRef, System.Text.Json.ExceptionResource, Byte, System.ReadOnlySpan`1[System.Byte])

Clicking a Series Link form the error logs gives me this:

So sorry for the delay! The new version is a total rewrite with a completely different approach—I genuinely thought it would take weeks. Somehow I've made amazing progress and am just fixing a few minor bugs now. Fingers crossed! If all goes well, V2 will be up in a few hours. I can see why the other developer abandoned his project. This project is very complicated but I'm not going to give up.

Edited July 27 by Blueskies278

[Blueskies278 89]

@sh0rty

Almost done, just cleaning up V2! I was going to give it a few more days of testing, but if you're eager to try it out, let me know and I'll upload it soon—as soon as I finish rewriting the new Air Date Fixer document. Update: Discovered a new bug.

Edited July 27 by Blueskies278

[sh0rty 768]

3 hours ago, Blueskies278 said:

@sh0rty

Almost done, just cleaning up V2! I was going to give it a few more days of testing, but if you're eager to try it out, let me know and I'll upload it soon—as soon as I finish rewriting the new Air Date Fixer document. Update: Discovered a new bug.

Now that Trakt only allows one device without VIP, have you thought about using Simkl? It seems they also provide region based Release Data on the Web page. The API provides broadcast data not as region based but ISO with Offset, but couldn't that be converted by the plugin based on the timezone setting set in it? Souce -> https://api.simkl.org/conventions/dates

    {
        "title": "Faceless Men",
        "description": "While Rhaenyra and Daemon focus on how best to deal with Ormund, tensions among their neglected allies begin to erupt.",
        "season": 3,
        "episode": 6,
        "type": "episode",
        "aired": true,
        "img": "20\/203532593c102da18e",
        "date": "2026-07-26T21:00:00-04:00",
        "ids": {
            "simkl_id": 14767323
        }
    }

 

[Blueskies278 89]

4 hours ago, sh0rty said:

Now that Trakt only allows one device without VIP, have you thought about using Simkl? It seems they also provide region based Release Data on the Web page. The API provides broadcast data not as region based but ISO with Offset, but couldn't that be converted by the plugin based on the timezone setting set in it? Souce -> https://api.simkl.org/conventions/dates

    {
        "title": "Faceless Men",
        "description": "While Rhaenyra and Daemon focus on how best to deal with Ormund, tensions among their neglected allies begin to erupt.",
        "season": 3,
        "episode": 6,
        "type": "episode",
        "aired": true,
        "img": "20\/203532593c102da18e",
        "date": "2026-07-26T21:00:00-04:00",
        "ids": {
            "simkl_id": 14767323
        }
    }

Once I have Air Date Fixer stable I will add SimkI to my roadmap.

Thanks


 

 

[Blueskies278 89]

I may need to scrap this project, it turns out this type of plugin isn't as universal as hoped. I'm exploring a different approach and will keep you updated.

Edited July 30 by Blueskies278

[Blueskies278 89]

UPDATE: Rebuilt from the ground up again. So far, early indications are looking good, just a few more bugs to iron out. One of the biggest changes: the Air Date fixer is no longer tied to Emby 4.9.5.0. Currently testing with 4.10.0.22 beta.

[Blueskies278 89]

Trakt Air Dates — Beta Tester Guide

Plugin version 5.0.0.0 · Updated 9 August 2026

This plugin has been rewritten from the ground up five times, because of how complex it turned out to be. What sounds simple — show the right date — runs into the fact that Emby, TMDB and Trakt each handle dates differently, and that the episodes most in need of fixing are the ones Emby knows least about. Each earlier version worked until it hit something Emby's plugin system doesn't allow; the last one broke outright when TheMovieDb provider changed how it stores data, and no amount of patching would have saved that approach.

It isn't perfect. The limitations below are real, and most of them aren't things I can code around — they're the boundary of what a plugin is permitted to do inside Emby. Within those limits, this is the best I've been able to manage, and the parts that do work have been tested.

If you tested an earlier version: this was previously called Air Date Fixer. Same project, renamed to Trakt Air Dates now that Trakt — not TMDB — is where the dates come from. It installs as a separate plugin, so remove any old EmbyAirDateFixer.dll before using this one. The plugin icon will still show the old name for now — that's expected, and the name in Emby's plugin list is the one to go by.

Please read the Limitations section before installing. It lists the cases where this plugin will quietly do nothing — knowing them up front saves you chasing a problem that isn't a bug.

---

What it fixes

US and Canadian shows air in the evening Eastern time, which is already the next day across Europe and anywhere further east. TMDB stores those broadcast dates as a bare date with no time or timezone, so Emby shows the episodes on the wrong calendar day for those viewers.

Trakt publishes each episode's air time as a true UTC instant, so it converts correctly for any timezone. This plugin uses Trakt as the reference and corrects Emby's dates to match.

Only US and Canadian shows are touched. British, Australian and European shows are left exactly as they are.

---

Two halves, and they're independent

	Already-downloaded episodes	Upcoming (not yet downloaded)
How it's fixed	Corrected directly in your library	Served with corrected dates by a built-in listener
Setup needed	Just two API keys	Keys plus a port change
Works on	Every client, always	Every client that reaches the listener

You can stop after the first half. Library corrections need no port changes and carry no risk. The port swap is only needed if you want Upcoming fixed on TV apps and phones as well as the browser.

---

Pros

• No extra container, no compose changes. One DLL. Everything runs inside Emby.
• Upcoming loads instantly. The list is cached in memory and refreshed in the background — typically well under a millisecond, versus Emby's own endpoint which is occasionally very slow. If Upcoming has ever failed to load in an app until you opened the web UI first, this fixes that.
• Corrections stick. If a later metadata refresh overwrites a corrected date, the plugin notices and puts it back.
• Immune to TheMovieDb provider updates. An earlier version of this plugin worked by editing that provider's cache files, and broke completely when the provider stopped using them. This design never touches them.
• Survives Emby updates. Nothing is injected into Emby's web files, so an update can't wipe it.
• Recovers from port conflicts on its own. If the port it needs is busy, it keeps retrying and starts the moment it's free — no restart, no intervention.
• Fails safe. If Trakt is unreachable, the plugin can't start, or Emby is being slow, you get uncorrected or slightly stale dates — never an empty screen or a dead server.

---

Cons and trade-offs

• Upcoming corrections require moving Emby's own HTTP port. Not difficult, but it is a change to your server's configuration, and you should be comfortable doing it.
• The plugin sits in front of your server. With the listener enabled, all client traffic passes through it on its way to Emby. That's the only way to reach not-yet-downloaded episodes — Emby has no plugin hook that fires for them — but it does mean a bug here can affect more than air dates.
• Changing the listener port can lock you out of the settings page. If you're viewing the dashboard through the listener's port and you change that port, the page disappears mid-edit. The way back in is Emby's own port — e.g. http://YOUR-SERVER:8098/web/index.html. Worth noting before you touch that field, not after.
• The first Upcoming load after an Emby restart is slow. The cache is empty and has to be built. Everything after that is instant.
• Upcoming data can be up to about five minutes old. Irrelevant for air dates, but worth knowing.

---

Limitations — where it will do nothing

These aren't bugs. If you're in one of these situations, expect no corrections.

HTTPS traffic bypasses the plugin entirely. The listener is HTTP-only. If your clients connect over HTTPS (commonly port 8920), they reach Emby directly and see uncorrected dates, with no error anywhere. There is currently no workaround other than using HTTP on your local network.

Remote/WAN access bypasses it unless your router's port forward points at the listener's port rather than Emby's. Otherwise, away-from-home clients get uncorrected dates.

The Android app may drift back to Emby's real port. Emby's apps trust the address the server reports about itself, and Android re-checks it — so even after you type the listener's address manually, it can revert to Emby's real port on a later restart. When it does, everything works normally except that Upcoming dates are uncorrected, with nothing to indicate anything changed.

To check: in the app, look at the server address under its connection/server settings. If it shows Emby's real port (e.g. :8098) rather than the listener's (:8096), that's why. Re-adding the server manually fixes it until the next drift.

I've requested a "lock custom server address" option in the app — somewhere to tell it to keep the address you typed and stop switching to the one the server reports. Realistically I don't expect it to be implemented; the response so far has been that it would cause more problems than it solves and affects very few people.

There is no server-side fix available to me. The plugin already reports the correct address, but the app also learns the real one through network discovery, and a plugin can't intercept that.

Realtime features are under observation. The plugin relays the apps' live-updates connection to Emby. This is working in testing, but some earlier connection drops aren't fully explained. It doesn't affect dates, browsing or playback — potentially things like remote control and instant library refresh. Please report anything odd.

Only US and Canadian shows are adjusted, and only by one day. Shows from elsewhere are deliberately untouched.

Tested on Emby 4.9.5.0, in Docker, on Linux. That's it. Other versions and platforms are untested — which is rather the point of a beta, but please mention your setup when reporting anything.

---

What you'll need

• A Trakt Client ID — from trakt.tv/oauth/applications. Free and instant. Only the Client ID; no login, no OAuth, no tokens.
• A TMDB API Key (v3 auth) — from themoviedb.org/settings/api. Free and instant.

The TMDB key is needed because Emby's own metadata doesn't reliably record which country a show comes from — on the library this was built against, that field was empty for every show. The plugin asks TMDB directly and caches the answer permanently, once per show.

---

Setup

Part 1 — library corrections (no risk, no port changes)

1. Copy TraktAirDates.dll into your Emby plugins folder and restart Emby.
2. Dashboard → Plugins → Trakt Air Dates.
3. Paste in both keys.
4. Turn on Enable corrections. Save.

Downloaded episodes start being corrected within about 30 seconds. If you only use a web browser, you're done.

Part 2 — Upcoming on TV apps and phones

Emby apps request the upcoming list by a fixed address that plugins aren't allowed to answer. The workaround is to have the plugin answer on the port your devices already use, and move Emby itself to a different one. Your devices don't change.

1. On the settings page, turn on Enable native app listener. Leave the port as the one your devices already use — usually 8096. Save.
2. Dashboard → Networking → change Local HTTP port number to something free, e.g. 8098. Save and restart Emby.
3. Existing devices keep working with the address they already have — nothing to do.

Adding a device after the port swap: don't let the app find the server by itself. Emby's automatic discovery answers with Emby's real port (8098), which goes straight past the plugin — the app will connect and work perfectly, but Upcoming dates won't be corrected and nothing will indicate why. Choose the manual / "add server by address" option instead and type the listener's address in full, e.g. http://192.168.0.160:8096.

The same applies if you ever sign out and back in, or reinstall an app.

Change Emby's port from Dashboard → Networking only. Editing system.xml by hand doesn't reliably take effect.

Check it worked: the Native App Listener box on the settings page should be green and read "Active — listening on port 8096, forwarding everything else to Emby on port 8098." If it's red, see below. You don't need to read a server log.

If you've just saved and the text still looks red while the tick is green, reload the page — the colour can lag behind the status.

Running Emby in Docker

Nothing extra for network_mode: host. If you publish ports explicitly (-p 8096:8096), that mapping keeps working — the plugin answers on 8096 inside the container and reaches Emby on 8098 internally. You do not need to publish 8098.

Running Emby on Windows

Windows restricts which programs may listen on a port. Emby normally runs as your user account, which isn't allowed to claim a port for all addresses — so the listener may fail with "Access is denied". That's Windows policy, not a plugin fault.

Either of these fixes it:

• Run Emby as Administrator — simplest, but you have to keep doing it.
• Grant a one-off permission (preferred). In an Administrator Command Prompt, replacing the name with your Windows account:

 

  netsh http add urlacl url=http://+:8096/ user=%USERNAME%

Then restart Emby. This persists, and doesn't require running Emby elevated.

To undo it later: netsh http delete urlacl url=http://+:8096/

Untested on Windows. The library-correction half needs none of this and should work normally either way. If you try the listener on Windows, please tell me what happened — good or bad.

Running Emby on macOS or native Linux

No special permissions needed for port 8096. Ports below 1024 would need elevated rights, but there's no reason to use one. Both are untested — reports welcome.

---

Troubleshooting

Red box: "Could not start on port 8096 … Retrying automatically every 15s"

No rush — it will start on its own the moment the port is free, and the attempt counter shows it's still trying. Causes, in order of likelihood:

1. Emby hasn't actually moved off that port yet — do Part 2 step 2, and make sure Emby restarted.
2. A second Emby or Jellyfin container is running. Easy to miss, and cost a full afternoon during development. Two Emby containers on host networking will silently fight over the same port. docker ps -a — if more than one Emby container is running, stop the one you don't use, and set it not to come back: docker update --restart=no <container_name>.
3. Something unrelated holds the port. On Linux: sudo netstat -tlnp | grep :8096.

Confirming it's genuinely working: sudo netstat -tlnp | grep -E ':(8096|8098)' should show one process ID holding both ports — the plugin runs inside Emby, so they share a process. Two different IDs means something else has taken the port.

I can't reach the dashboard after changing the listener port

Use Emby's own port: http://YOUR-SERVER:8098/web/index.html. Set the listener port back from there.

Dates are right in the browser but wrong in an app

The app is probably reaching Emby directly rather than through the listener. Check the server address saved in the app — it should use the listener's port (8096), not Emby's new one. See the Android note under Limitations.

Nothing is being corrected at all

Check the Last Refresh box. If it reports 0 of N series matched as US/Canada, the TMDB key is likely wrong or missing. Remember only US and Canadian shows are adjusted.

Upcoming was slow once, then instant

Expected — see Cons. If an app gave up on that first load, open it again; the result is kept even if the app stopped waiting.

---

Reporting a problem

If there are TV shows missing from your Upcoming listing, please let me know and I'll do my best to fix it.Missing shows are just as useful to hear about as wrong dates — the plugin merges its own data with Emby's, and a show disappearing means something didn't line up.

Please include:

• The exact text of any red status box — it's generated live from what actually failed.
• Your Emby version, platform, and whether you're using Docker.
• Whether your clients connect over HTTP or HTTPS, and locally or remotely.
• For a wrong date: the show, season and episode number, the date shown, and the date you expected.

If you send a server log, please check it for access tokens before sharing publicly.

---

Uninstalling

Remove the plugin DLL and restart Emby. If you did the port swap, set Emby's port back to 8096 in Dashboard → Networking first — otherwise your devices won't find the server.

Dates already corrected in your library stay as they are. They're ordinary Emby metadata now.

TraktAirDates.dll

Trakt-Air-Dates-Beta-Tester-Guide.pdf

Edited 19 hours ago by Blueskies278

[Blueskies278 89]

UPDATE: Tested on Emby 4.9.5.0 and 4.10.0.23 (beta channel), in Docker, on Linux. It

survived that version jump with settings intact and needed no changes. Other versions

and platforms are untested — which is rather the point of a beta, but please mention your

setup when reporting anything

 Emby performance note (separate issue)

/Shows/Upcoming intermittently takes ~120s instead of ~0.1s. Investigated at length 25–26 July: not caused by plugins, TheTVDB, host resources, or Emby version (4.10.0.19 vs 4.10.0.20 — GetUpcomingEpisodes byte-identical). Emby's own log shows ~8,864 sequential TMDB HttpClient calls in a 6-minute window, each ~100ms apart, all "served from cache" — enough serialized latency to explain the stall. Root cause unconfirmed.

Still present on 4.10.0.23 — reported to Emby (7 Aug 2026)

Confirmed unchanged, and this time cleanly isolated: a single Emby container, request made directly to Emby on 8098with the plugin entirely out of the path, same ~120s failure. Two failures also seen through the listener at 121915ms and 120638ms. The 4.10.0.23 changelog contains nothing addressing it (search performance and a SQLite bump are the only performance-adjacent entries).

Reported to the Emby team; awaiting a fix. This isolation is what the July investigation lacked — specific version, single instance, plugin excluded, reproducible timings.

The plugin's Upcoming cache is now load-bearing, not a nicety. It is the only reason Upcoming is usable on this server: clients are served from memory in ~0.0007s while the background refresh quietly absorbs Emby's stall. Previously the retired emby-cache container did this job at 0.007s.

PDF information update

Trakt-Air-Dates-Beta-Tester-Guide.pdf

Edited 14 hours ago by Blueskies278

[Blueskies278 89]

Updated release notes for version 5.0.0.0 

Trakt Air Dates Release Notes

Version 5.0.0.0

Changes

5.0.0.0

• Fifth ground-up rewrite — no longer depends on TheMovieDb provider's cache files, so provider updates can't break it
• Corrects already-downloaded episodes directly in the library, with automatic re-correction if a later metadata refresh overwrites them
• Corrects the Upcoming view for every client via a built-in listener — the only mechanism that can reach not-yet-downloaded episodes
• Upcoming responses now cached in memory and refreshed in the background — typically under a millisecond instead of waiting on Emby
• Upcoming no longer fails when Emby's own endpoint stalls: falls back after 15 seconds and completes the full list in the background
• Listener now retries automatically if its port is busy, and rebinds itself if it stops — a port conflict no longer requires a restart or leaves the server unreachable
• Settings page now reports retry attempts instead of appearing dead
• Emby's reported server address now corrected in both formats, so clients on Emby 4.10 don't drift onto the wrong port
• WebSocket connections relayed to Emby, so live updates and remote control work through the listener
• Plugin scripts can now be injected into the web client without writing to Emby's own web files — see below
• Diagnostic logging reduced, and credentials redacted from logs
• Plugin version now reported correctly in the plugin list and server log
• Renamed from Air Date Fixer to Trakt Air Dates, with a new plugin icon

Web script injection

Plugins that add behaviour to Emby's web client normally have to write into Emby's own dashboard-ui folder — which every Emby update wipes, and which Docker often blocks without a root chown.

Trakt Air Dates can now serve those scripts itself and insert them into the page as it passes through, so Emby's files are never touched. Any plugin dropping a .js into plugins/webinject/ is picked up automatically.

TV Show Status 2.5.12.0 uses this — with both plugins installed, its badge survives Emby updates with no chown and nothing to redeploy.

Notes

• Tested on Emby 4.9.5.0 and 4.10.0.23 (beta), Docker on Linux. Survived that version jump with settings intact
• Upcoming corrections require moving Emby's own HTTP port — see the setup guide
• HTTPS and remote/WAN traffic bypass the listener and are not corrected
• The Android app may revert to Emby's real port after a restart; re-enter the address manually if Upcoming dates look wrong

 

TraktAirDates.dll

Edited 5 hours ago by Blueskies278

[Blueskies278 89]

Trakt Air Dates Release Notes

Version 5.0.6.0

Changes

5.0.6.0

• Removed temporary diagnostic logging added while investigating an app connection issue

5.0.4.0

• Fixed "Fetch is aborted" in the iOS app — Upcoming no longer makes clients wait on a slow Emby
• Reduced the wait for Emby's own Upcoming from 15 seconds to 5 before falling back
• Once Emby is seen stalling, the wait is skipped entirely for later clients until it recovers

5.0.2.0

• Fixed apps reporting "unable to reach server" while browsers connected fine — the injected index.html response was dropping Emby's CORS and Private Network Access headers, which apps require and browsers don't
• All of Emby's response headers are now preserved when injecting

TraktAirDates.dll

Edited 45 minutes ago by Blueskies278