TV Air Dates — corrects US and Canadian broadcast times to your timezone

[Blueskies278 144]

 

TV Air Dates — what it is and how to use it

An unofficial Emby Server plugin. Version 8.16.0.0, September 2026.

---

The problem it solves

A US show airs at 9pm Eastern on a Tuesday. TMDB records that as "Tuesday", because TMDB stores a plain calendar date with no time attached.

In the UK that broadcast is 2am on Wednesday. In central Europe it is 3am Wednesday. So Emby shows the episode a day earlier than it actually reaches you, and your Upcoming list is wrong by one day for every US and Canadian show you follow.

TV Air Dates fixes that. It fetches the real broadcast instant — date and time and timezone — from Trakt or Simkl, converts it to your server's local time, and keeps the calendar day that actually results.

It only touches US and Canadian shows. A British or Australian show is already on the right day for a British viewer, and "correcting" it would create the very problem this solves.

What it actually changes

Two separate things:

Episodes you already have. Their air dates are corrected in your library, one day forward where the conversion calls for it. This is a real edit to your metadata.

Episodes you do not have yet. Emby has no data at all for an episode you have not downloaded, so Upcoming would be empty without help. This plugin supplies Emby with a full episode list for every show in your library, using the real air times, so Upcoming is both populated and on the right day.

Optionally it can also write "Season Premiere" or "Season Finale" in front of an episode's title, which is the only way to mark those on clients that cannot draw badges.

---

Before you start

Back up your Emby server. This plugin writes to your library. If something goes wrong you want a way back. This is not boilerplate — take the backup.

If you run Emby in Docker, that means the config folder. If you run a NAS package, use the NAS's own backup. On Windows, macOS or Linux, copy the Emby Server data folder somewhere safe while the server is stopped.

---

Step 1 — get your keys

You need two: TMDB, plus one air-date source.

TMDB (required)

1. Go to themoviedb.org/settings/api
2. Create a free account if you do not have one, and request an API key
3. Copy the API Key (v3 auth) value — not the read access token

Free, instant, no approval. It is used to find out which shows are US or Canadian broadcasts, looked up once per show and cached permanently.

Then one of these two

Simkl — free, and the easier of the two:

1. Go to simkl.com/settings/developer
2. Create an app. Any name and redirect URL will do
3. Copy the Client ID

That page shows a Client ID and a Client Secret side by side and they look alike. The secret will not work. If dates stop being corrected the moment you switch to Simkl, this is almost always why — the log says so plainly.

Trakt — the original source, but harder to get now:

1. Go to trakt.tv/oauth/applications
2. Create an application and copy the Client ID

 Since late July 2026, creating a Trakt API application requires an active VIP membership (around $4.99/month). It applies even though this plugin only ever reads public data, because a Client ID exists only as part of a registered app. Trakt has called the restriction temporary and its own API documentation does not mention it, so it is worth trying — but expect a wall if you are starting fresh. Free-account applications were reported removed at the same time, so a Client ID that worked before may have stopped.

 Separately, a free account can connect only one Community App at a time. This one is Trakt's own published rule, announced 22 July 2026, and it covers apps you authorise under Settings → Apps → Connected Apps. Existing connections above the limit are allowed to continue, but reconnecting one counts as new — so do not disconnect an app you depend on. This plugin is not one of those apps: it never authorises against your account and never appears in that list, so it should not use up your one connection.

If any of that blocks you, use Simkl. Free, instant, no membership, and one setting away.

Only the Client ID is needed either way. No login, no OAuth, no tokens.

---

Step 2 — install the plugin

The file is TVAirDates.dll. It goes in the plugins folder directly below your Emby Server data folder.

Stop Emby Server first. Emby holds plugin files open while running.

Where the data folder is

Platform	Data folder
Windows	C:\Users\<you>\AppData\Roaming\Emby-Server\programdata
macOS	/Users/<you>/.config/emby-server (older installs: /Users/<you>/emby-server)
Linux (deb/rpm)	/var/lib/emby
Docker	whatever you mapped to /config inside the container
Synology DSM 7	/volume1/@appdata/EmbyServer
Synology DSM 6	/volume1/Emby
QNAP	/share/CACHEDEV1_DATA/.qpkg/EmbyServer/programdata
Asustor / TerraMaster	/home/emby

So on Windows the plugin goes in …\programdata\plugins\TVAirDates.dll, on Linux in /var/lib/emby/plugins/TVAirDates.dll, and so on.

If you are not sure, Emby tells you: Dashboard → Help → Support → Server Paths shows the data folder for your install.

Upgrading from Trakt Air Dates

Delete the old TraktAirDates.dll from the plugins folder. If both files are present Emby tries to load the same plugin twice. Your settings are carried over automatically on first start — you do not need to re-enter your keys.

Platform notes

Windows — copy the DLL in, start Emby. Nothing else to do.

macOS — the .config folder is hidden in Finder. Press Cmd+Shift+G and paste the path. Copy the DLL in, start Emby.

Linux — the DLL must be readable by the user Emby runs as, usually emby. After copying:

 

sudo chown emby:emby /var/lib/emby/plugins/TVAirDates.dll
sudo chmod 644 /var/lib/emby/plugins/TVAirDates.dll

Docker — copy into the mapped config folder from the host, or:

 

sudo docker cp TVAirDates.dll <container>:/config/plugins/TVAirDates.dll
sudo docker restart <container>

NAS (Synology, QNAP, UGREEN, Asustor, TerraMaster) — same as Linux, and the permissions step matters most here.

If the plugin never appears in the plugin list, this is almost always why. A file copied over SMB or through a file manager often arrives readable only by the account that copied it. Emby then cannot read it, loads nothing, and logs nothing — which looks exactly like an incompatible build. Check with ls -la in the plugins folder: the file should look like -rw-r--r--, matching the other plugins beside it. If it does not, chmod 644 it and restart.

---

Step 3 — set it up

Start Emby, then Dashboard → Plugins → TV Air Dates.

Fill it in in this order:

1. Air date source — Trakt or Simkl. Only the matching key box is shown
2. Trakt Client ID or Simkl Client ID — whichever you chose
3. TMDB API Key
4. Supply episode lists from the selected source — turn this on. This is the main setting; without it the plugin corrects only episodes you already have, and Upcoming is untouched
5. Enable corrections — turn this on
6. Press Save

Saving clears every cached answer and starts a fresh fetch, so the first Upcoming refresh afterwards is slow while it rebuilds. That is expected. It is also how you force fresh data any time later.

Worth tuning

How far ahead to show (days) — default 60. Every Emby app fetches a fixed number of Upcoming items and cuts the list by item count, not by day, so the last day you see can be a partial one with some of that day's shows missing. A smaller window means less reach but every day complete. On a busy library at roughly two episodes a day: 21 days ≈ 45 items, 30 days ≈ 70, 60 days ≈ 107.

Keep these shows out of Upcoming — a daily show can eat fifteen or more of those slots on its own and push everything else off the end. Naming it here leaves it in your library untouched but keeps it out of Upcoming, including the Yesterday row at the top of that view.

Mark season premieres and finales in the episode name — off by default, and it edits real episode titles. Turn it on only if you want those marked on clients that cannot show badges. Turning it back off restores the plain titles immediately.

---

Step 4 — check it worked

Open the settings page again and read the three status boxes at the bottom:

• Shows Being Covered — how many of your shows have an answer
• Unaired Episode Probe — how many future episodes are visible and dated
• Last Refresh — when the last pass ran and how many dates it corrected

Then open Upcoming and compare a US show against its real broadcast day. A Tuesday-night US show should now read Wednesday for a UK viewer.

---

Keeping your settings safe

Your settings live in one file named after the plugin, and they include all your API keys. The plugin protects them two ways:

Automatically, every time you press Save. Two copies are written, and it is worth knowing which is which.

A dated copy goes to plugins/configurations/tvairdates-settings-backups/, beside Emby's own configuration files. That is the safety net: if your settings are ever found empty on startup, the newest one is restored by itself. How many backups to keep sets how many are kept — 10 by default, 0 keeps everything.

At the same time, your current settings are written to the folder you set in Folder for exported settings, as a single file named TV Air Dates-settings-current.json, overwritten on each save. That folder therefore always holds your live configuration, somewhere you can reach it. Leave the folder empty and nothing is written there; the dated backups carry on regardless.

After each save the Settings backup box names the file it just wrote, so you can see it happened rather than take it on trust.

On demand — in Dashboard → Scheduled Tasks, under "TV Air Dates":

• Export TV Air Dates settings — writes a dated snapshot to the same folder, alongside the always-current file. Runs weekly on Sundays; press the play button to run it now. Use it to capture a known-good configuration before changing something, or before rebuilding a server
• Import TV Air Dates settings — reads the newest dated snapshot back. Only runs when you press it, and backs up what it is replacing first

These files contain your API keys in plain text. Treat the folder like a password.

---

If something is wrong

The plugin does not appear in the list — permissions, nine times out of ten. See the NAS note above. Also check you deleted the old TraktAirDates.dll.

Dates are not being corrected — check the Client ID is the ID and not the secret. Check Enable corrections and Supply episode lists from the selected source are both on. Then press Save to force a fresh fetch.

Dates stopped being corrected on Trakt, having worked before — check the application still exists on your Trakt account. Free-account applications were reported deleted in late July 2026, and a revoked Client ID fails in exactly the same way as a wrong one. Switching to Simkl is one setting away.

Upcoming is empty or short — give it a few minutes after saving; it rebuilds every show from scratch. If it stays short, look at How far ahead to show and at whether your app is cutting the list by item count.

A show is missing from Upcoming — the plugin refuses to send Emby an episode list shorter than what you already have on disk, on purpose: a wrong date is recoverable, a show that vanishes is not. The log says which show and why.

Everything is slow after saving — expected, once. Saving clears the caches deliberately.

The server log is the place to look: Dashboard → Logs. Every line from this plugin is prefixed [TraktAirDates], which is the internal name and has deliberately not been renamed, so older troubleshooting notes still apply.

---

Disclaimer

This is an unofficial, hobby-built plugin. It is not made by, endorsed by, or affiliated with Emby, Trakt, Simkl or TMDB. It uses the Trakt API, the Simkl API and TMDB, none of whom endorse or certify it.

It is beta software and it writes to your library: it changes the air dates of episodes you already have, and optionally adds "Season Premiere" or "Season Finale" to episode names. Those are real edits to your metadata. Take a backup of your Emby server before installing, and keep one. It is supplied as-is, with no warranty of any kind — you run it at your own risk, and I cannot be held responsible for anything it does to your library, your server or your data.

You supply your own API keys and remain bound by the terms of whichever services you use.

Please report bugs along with your Emby log. Thanks

 

TV Air Dates 8.16.0.0

The plugin has been renamed. It was Trakt Air Dates; it is now TV Air Dates, because Trakt is no longer the only source it can use. Your settings carry over automatically the first time it starts — nothing to re-enter, including your API keys.

Installing this version: the file is now TVAirDates.dll. Delete the old TraktAirDates.dll from your plugins folder. If both are present Emby will try to load the same plugin twice.

This release covers everything since 8.11.0.0.

---

New

• Air date source — choose between Trakt and Simkl. They are mutually exclusive: whichever you pick is the only one contacted, and the other's key box is hidden. Trakt stays the default, so nothing changes unless you change it.
• Simkl Client ID — free from simkl.com/settings/developer. No membership, no approval. This matters because since late July 2026 creating a Trakt API application requires an active VIP membership, which locks out anyone starting fresh. Trakt separately limits a free account to one connected Community App, but that covers apps you authorise against your account under Settings → Apps → Connected Apps, and this plugin is not one of them — it only ever reads public data, so it should not use up that connection. Careful: that page shows a Client ID and a Client Secret side by side and they look alike. The secret will not work. If corrections stop the moment you switch to Simkl, check which one you pasted — the log now says so in plain words instead of failing silently.
• Automatic settings backup — every time you press Save, a dated copy of your settings is kept beside Emby's plugin configurations, and a single always-current copy is written to the folder you choose in Folder for exported settings, so that folder always holds your live configuration. The Settings backup box names the file it just wrote. If your settings are ever lost, the newest dated copy is restored on startup. How many backups to keep controls the history: 10 by default, 0 keeps everything and deletes nothing.
• Export and import, in Dashboard → Scheduled Tasks under "TV Air Dates". Export writes a dated snapshot into that same folder, alongside the always-current file — useful for capturing a known-good configuration before you change something. It runs weekly on Sundays and can be run on demand; import reads the newest dated snapshot back, only when you press its button, and backs up your current settings first. These files contain your API keys, so keep the folder private.

Fixed

• Excluded shows stayed out of the future but came back in the past. Keep these shows out of Upcoming held back episodes still to air, but Emby's Upcoming view opens with a Yesterday row — so an excluded show reappeared there the morning after each new episode. For a daily show that meant nearly every day. The cutoff now reaches two days back, so nothing an excluded show airs can land in that row.
• Invented episodes no longer appear in Upcoming. A source can list an episode that does not exist — one show gained a seventh episode of a six-episode season that had already finished. An episode is now dropped only when it sits beyond the end of TMDB's list for that season and has no title, so genuinely unannounced episodes still appear.
• "Season Finale" is no longer written into an episode name while a season is still being published. Two shows were marked as ending with most of their season still to run. The marker is now withheld when the episode has no real title yet, or when the season is running far shorter than that show's completed seasons.
• Shows with short seasons were being skipped entirely. An internal rule refused any answer containing fewer than ten episodes, so a six-part documentary or a four-part drama got no date corrections at all, silently, with nothing in the log to explain it. That rule is gone. The real safety check remains: no episode list shorter than what you already have on disk is ever sent to Emby.
• The Trakt Client ID setting now tells the truth. It said creating an app was "free, instant, and needs no approval". Since Trakt's July 2026 change that is false, and it sent new users to a wall. The text at the top of the page says the same thing before you start.
• Stale text removed. The settings page referred to a "native listener" that was retired in August, and Supply episode lists from Trakt was renamed to Supply episode lists from the selected source, since Trakt is no longer the only one.

Known limitations

• Leaving the Client ID empty is allowed and nothing breaks, but upcoming episodes then come from TMDB with uncorrected dates — which is the thing the plugin exists to fix.
• If you are on Trakt and corrections stop having previously worked, check your Trakt account still has the application. When the July 2026 restrictions came in, applications belonging to free accounts were reported deleted rather than left alone, and a revoked Client ID fails in exactly the same way as a wrong one. Switching to Simkl is one setting away.
• Simkl's catalogue is shallower than Trakt's for some long-running shows, and occasionally deeper. Both were measured against each other and agreed on every corrected date where both could answer, but if a show you follow looks thin on Simkl, switching back to Trakt is one setting away.
• Saving the settings page clears every cached answer, so the next Upcoming refresh is slower while it rebuilds. That is also how to force fresh data after changing a key or the source.

---

Disclaimer

This is an unofficial, hobby-built plugin. It is not made by, endorsed by, or affiliated with Emby, Trakt, Simkl or TMDB. It uses the Trakt API, the Simkl API and TMDB, none of whom endorse or certify it.

It is beta software and it writes to your library: it changes the air dates of episodes you already have, and optionally adds "Season Premiere" or "Season Finale" to episode names. Those are real edits to your metadata. Take a backup of your Emby server before installing, and keep one. It is supplied as-is, with no warranty of any kind — you run it at your own risk, and I cannot be held responsible for anything it does to your library, your server or your data.

You supply your own API keys and remain bound by the terms of whichever services you use. Exported settings files contain those keys in plain text; treat them as passwords.

Please report bugs along with your Emby log. Thanks

New plugin name

 

 

 

 

 

TVAirDates.dll TV-Air-Dates-settings-8_16_0_0.pdf TV-Air-Dates-guide-8_16_0_0.pdf

Edited 23 hours ago by Blueskies278

[Blueskies278 144]

A big thanks to sh0rty for his invaluable help implementing Simkl. He was extremely patient.

TV Air Dates 8.33.0.0

Nothing you have saved changes — every setting keeps its name and default, and your API keys and Simkl sign-in carry over untouched.

If your Upcoming has ever shown episodes a day early while the episode page had the right date, read the first section. It is a settings step, not a code fix, and it has been missing from every guide.

This release covers everything since 8.26.0.0.

---

The one step that was never documented

Emby has to be told to ask this plugin for episode lists, and told to prefer its answer over TheMovieDb's. On a fresh install it is not, because the plugin deliberately ranks itself below TheMovieDb by default. Until you move it, TheMovieDb's episode list wins, and your Upcoming carries TMDB's bare US dates no matter what the plugin has worked out.

Do this once:

1. Dashboard → Library, three dots on your TV Shows library, Manage Library, then Metadata
2. Under Series Metadata Downloaders, tick Trakt Air Dates and drag it to the top — above TheMovieDb
3. Run a library scan. This is not optional: the change is not picked up until a scan runs
4. Open the plugin settings and press Save to rebuild

Then read the new Metadata downloader order box on the plugin's settings page. It should say "ranked 1 of N, ABOVE TheMovieDb, and it is ticked" for your TV library. If it says the plugin is not in the list, or is below TheMovieDb, Upcoming is not getting corrected dates yet.

It appears in that list as Trakt Air Dates, not TV Air Dates — that is the provider's original name, and it stays that way on purpose for now: Emby stores your ranking against the name, so renaming it would silently reset everyone's order. It will be renamed later, deliberately, with notice.

Measured on two servers on 20 September: one with the plugin ranked first showed every upcoming episode on the right day; one with it unticked showed the same episodes a day early on the same Emby build, from the same data, an hour apart in the same part of the world. Ticking it, ranking it first and scanning fixed the second server outright.

New

• Metadata downloader order — a read-only status box on the settings page. It reports, for each TV library, where Trakt Air Dates sits in the Series downloader list relative to TheMovieDb and whether it is ticked, and tells you where to change it. Mixed libraries are mentioned but not judged. This is the box that would have found the problem above in five seconds instead of six weeks.
• A clickable link to the Simkl approval page. While a sign-in code is waiting, a link appears under the Simkl sign-in box that opens the right page directly. If Simkl supplies a URL with the code already in it, approving is one click and nothing is typed; if it does not, the link still opens the page and you type the 8 characters. The log says which happened — search for link offered.
• Sign out of Simkl — a switch directly under the sign-in box. Turn it on and press Save, and the stored sign-in is forgotten: the next Save issues a fresh code. It touches nothing else — your Client ID, your source and every cached answer stay, so nothing is rebuilt and no Simkl requests are spent. The switch turns itself back off once it has run. The warning is written under the switch permanently rather than popping up, because a settings page cannot show a dialog; it is on screen before, during and after the decision. To withdraw the plugin's access at Simkl's end, use Connected apps on simkl.com.

Fixed

• The Simkl sign-in box forgot itself after every restart. It went back to "Not checked yet this session — press Save and the sign-in code appears" on a server that was signed in perfectly well, and anyone believing it would press Save and rebuild for nothing. It now reads the stored sign-in when the page opens and says "Signed in to Simkl" straight away.
• Cache files now say which source dated an episode. A cached answer built from Simkl was labelled "Trakt Air Dates", identically to one built from Trakt, so a cache file could not tell you which service it came from. Simkl answers are now labelled Trakt Air Dates (Simkl) and Trakt answers Trakt Air Dates (Trakt). Existing entries keep their old label until they expire.

Known limitations

• The sign-in box cannot update while you are looking at it. After approving the code at simkl.com/pin, reload the settings page to see it confirmed. The sign-in completes either way.
• Nothing on the settings page can react to a switch before you press Save. That is a limit of Emby's plugin settings pages, tested and confirmed in this release, which is why the sign-out warning is permanent text rather than something that appears when you flip the switch.
• Simkl free accounts get 500 API requests per day, shared across all your Simkl apps. A full rebuild of a 130-show library costs about 260 of them and every press of Save forces another. On Simkl, save once and let it settle.
• A show your source has never heard of cannot have a broadcast slot measured, so those episodes keep TMDB's date. The log names them: search for SLOT:.
• Leaving the Client ID empty is allowed and nothing breaks, but upcoming episodes then come from TMDB with uncorrected dates — which is the thing the plugin exists to fix.
• Saving the settings page clears every cached answer, so the next Upcoming refresh is slower while it rebuilds. That is also how to force fresh data after changing a key or the source.

---

Disclaimer

This is an unofficial, hobby-built plugin. It is not made by, endorsed by, or affiliated with Emby, Trakt, Simkl or TMDB. It uses the Trakt API, the Simkl API and TMDB, none of whom endorse or certify it.

It is beta software and it writes to your library: it changes the air dates of episodes you already have, and optionally adds "Season Premiere" or "Season Finale" to episode names. Those are real edits to your metadata. Take a backup of your Emby server before installing, and keep one. It is supplied as-is, with no warranty of any kind — you run it at your own risk, and I cannot be held responsible for anything it does to your library, your server or your data.

You supply your own API keys and remain bound by the terms of whichever services you use. Exported settings files contain those keys — and your Simkl sign-in — in plain text; treat them as passwords.

Please report bugs along with your Emby log. Thanks

Important: please read the guide & settings

TVAirDates.dll TV-Air-Dates-guide-8_33_0_0.pdf TV-Air-Dates-settings-8_33_0_0.pdf

Edited 18 minutes ago by Blueskies278