Vivid
Set up TMDb, MDBList, Simkl and OpenSubtitles, and see what each one adds.
Home · Documentation · Contributing · Releases
Vivid works fine without plugins. TMDb is built in. MDBList and OpenSubtitles are optional connections to a free service, using your own personal key, and Simkl signs in with your Simkl account. Each adds something on top of your media server. This guide walks through setting each one up and what you get once it's connected.
| Plugin | What you get | What you need |
|---|---|---|
| TMDb | Trailers, TMDb ratings, Studios & Networks on Home and movie collection rows | Nothing. It's built in |
| MDBList | Finished movies and episodes sent to MDBList, and your watchlist kept in sync both ways | A free MDBList account and API key |
| Simkl | Finished movies and episodes sent to Simkl, and your watchlist kept in step with Simkl's Plan to Watch | A free Simkl account, signed in on each device |
| OpenSubtitles | Subtitles searched and downloaded from a movie or episode page, or while you watch | A free OpenSubtitles.com account and API key |
Important
Sign in to your server and choose your profile before connecting a plugin. Each connection belongs to the server account and profile you're using, so another profile or saved account needs its own key.
To find the plugins:
- iPhone and iPad: tap your profile picture in the tab bar to open Settings, then choose Plugins.
- Apple TV: select your profile picture in the top bar to open Settings, then choose Plugins.
TMDb and OpenSubtitles come first, then MDBList and Simkl under Watchlists.
| iPhone | Apple TV |
|---|---|
![]() |
![]() |
Tip
Keys are saved in Keychain and sync through Vivid's encrypted iCloud vault to your other iPhone, iPad and Apple TV for the same server account and profile. Set a plugin up on your iPhone or iPad and it comes through to Apple TV once it syncs, so you don't need to type a long key with the remote. Simkl is the exception: it signs in on each device with a short code, so there's no key to type.
TMDb (The Movie Database) adds trailers, ratings, Studios & Networks and collection rows to Vivid. There's nothing to set up: Vivid's TMDb lookups go through Vivid's TMDb relay, which uses Vivid's own TMDb key. Settings > Plugins > TMDb shows Status Connected with a green dot, and TMDb's logo and attribution. Vivid deletes any personal TMDb key an earlier version saved, for every saved profile on the device, and the deletion syncs to your other devices.
| Feature | Where it shows up |
|---|---|
| Trailers | A Trailers row on movie and series pages, just before Cast & Crew. It shows up to three trailers with the official ones first, and series show trailers for their latest season. Episode pages show their series' trailers. On iPhone and iPad, tapping a trailer asks first: Open plays it in the YouTube app, or on youtube.com if the app isn't installed, and Cancel keeps you in Vivid. On Apple TV they play in the YouTube app, so it needs to be installed. |
| TMDb rating | TMDb's user score on movie and series pages, next to the other badges. It only appears when TMDb has votes for the title. |
| Studios & Networks | A row of up to 20 studio and network logos pinned under the Spotlight on Home. Each one opens a page for that studio or network with Popular TV Shows and Popular Movies (led by what's trending on TMDb this week and filled from its popular titles, without talk shows or anime except on Crunchyroll and Studio Ghibli; each row shows once at least six of your titles match), plus All in Your Library: every title in your library from that studio or network, with a filter. |
| Collections | On a movie that's part of a collection, a row such as "Scream Collection" with the films from it that are in your library, in release order. It appears when you have at least two of them. |
| TMDb rating | Trailers | Studios & Networks |
|---|---|---|
![]() |
![]() |
![]() |
On Apple TV, the TMDb rating sits after the quality badges, trailers sit just above Cast & Crew, and Studios & Networks runs across Home under the Spotlight, six tiles at a time, scrolling sideways to the rest.
| TMDb rating on Apple TV | Trailers on Apple TV |
|---|---|
![]() |
![]() |
These screenshots use sample text wordmarks in place of the real studio and network logos that the app shows.
Studios & Networks is on from the start. Its first load happens while Vivid prepares Home after you sign in or set up a profile: Vivid reads your library, with the networks and studios your server lists for each title, and matches it with TMDb, downloading TMDb's lists at the same time, and Home opens once it's done, so the row is already there. On a large library that can take a minute or two. Home stops waiting after two minutes, or if the load fails, and the row then appears once it's ready. After that it loads straight away and refreshes daily. It chooses from Netflix, HBO, Apple TV, Disney+, Prime Video, Hulu, Peacock, Paramount+, Stan, BritBox, AMC, FX, Crunchyroll, Hallmark, Pixar, Marvel Studios, A24, Lucasfilm, DreamWorks, Studio Ghibli, Sony Pictures, Warner Bros., Universal, Walt Disney Pictures, DC and 20th Century Studios, and uses the 20 with the most matching titles in your library unless you pick your own. A studio or network only shows once at least six titles in your library match it.
To choose your own, open Settings → General and choose Studios & Networks under the Home Screen heading. From there you can:
- turn Show on Home on or off
- pick six to 20 from Networks and Studios (fewer only when fewer than six brands match your library)
- use Reset to Automatic to go back to Vivid's picks
- Trailers, ratings and collection rows need your server to have identified the title. Silo needs a TMDb ID. Emby and Jellyfin can also use an IMDb ID, which Vivid looks up on TMDb. TMDb's Studios & Networks lists, and the other films in a collection row, are matched with your library by TMDb ID where your server lists one, and otherwise by exact title and year. All in Your Library also has every title your server tags with that network or studio, even one with no TMDb ID or year.
- More Like This comes from your server and works without TMDb.
- Collection names and the Calendar's Trending titles and overviews come back in Vivid's language when TMDb has a translation, and in English when it doesn't. Studios & Networks stays in English. MDBList and OpenSubtitles messages follow Vivid's language too. Simkl's page and messages are in English for now. See Localisation.
- This product uses the TMDB API but is not endorsed or certified by TMDB.
- No trailers, ratings or Studios & Networks. Check you're signed in to a server and have chosen a profile. If you have, Vivid's TMDb relay may be busy or over its daily limit, so try again later.
- No trailers on Apple TV. Install the YouTube app from the App Store.
- Studios & Networks stopped loading after Vivid closed while it loaded. If Vivid closes twice in a row while Studios & Networks is loading, it stops loading on its own so Vivid can still open. With no row saved yet, choose Try Again in Settings → General → Studios & Networks. Otherwise it tries again a day later, or after an app update.
MDBList keeps your watched history and a watchlist in one place that other apps can use too. Vivid sends your finished movies and episodes to it and keeps your watchlist in sync both ways.
- Sign in at mdblist.com. It's free.
- Open Preferences and copy your API key. If there isn't one yet, generate it there.
- In Vivid, open Settings → Plugins → MDBList. On iPhone and iPad, Get your free API key opens the same page.
- Paste it into MDBList API key (on Apple TV, Personal API key) and choose Connect.
- Status shows Connected with a green dot, and the first sync starts straight away.
| iPhone | Apple TV |
|---|---|
![]() |
![]() |
| Feature | How it works |
|---|---|
| Watched history | When you finish a movie or episode, or mark one as watched, Vivid sends it to MDBList once your server has saved it. Downloads you watch offline are sent once your server catches up. |
| Watchlist sync | Movies and series you add to or remove from your watchlist in Vivid change on MDBList too, and changes made on MDBList come back to Vivid. The first sync combines both lists. Titles from MDBList are added when they're on the server you're using. On Emby and Jellyfin this is Vivid's watchlist, not your server favourites. |
| Background sync | While Vivid is open it syncs about every ten minutes, and sooner after you finish something or change your watchlist. Sync now runs a sync straight away, and the MDBList page shows its progress. |
This works with Silo, Emby and Jellyfin on iPhone, iPad and Apple TV. The Emby and Jellyfin logos on the MDBList page show that MDBList also works with those servers. Vivid itself only connects to MDBList.
- It doesn't bring history from MDBList into Vivid or your server. Watched status and resume points still come from your server.
- Marking a whole season or series as watched isn't sent. The individual episodes you finish are.
- Marking something unwatched doesn't remove it from MDBList.
- Disconnecting keeps your existing history and watchlist on MDBList.
- "Check your MDBList API key and try again." Copy the key again from your MDBList Preferences.
- "MDBList's request limit was reached. Sync will try again later." Vivid waits an hour before trying again, and Sync now waits too.
- "Sync finished. … watched items could not be matched or confirmed and will be retried." Vivid matches watched items by their TMDb or IMDb ID (or TVDB for episodes), so titles your server hasn't identified stay unmatched and are tried again later.
- A watchlist title from MDBList doesn't appear in Vivid. Vivid only adds it when it finds the same title on your server by name and ID. If your server names it differently, it stays unmatched and is tried again later.
- "This batch is synced. More watchlist changes remain for the next check." Each sync changes up to 32 watchlist titles, so a large first sync carries on at the next check, about ten minutes later.
Simkl tracks the movies, shows and anime you watch, and keeps a Plan to Watch list. Vivid sends your finished movies and episodes to Simkl and keeps Plan to Watch in step with your Vivid watchlist.
- Create a free account at simkl.com if you don't have one.
- In Vivid, open Settings > Plugins > Simkl and choose Sign in with Simkl.
- Approve Vivid on Simkl:
- iPhone and iPad: Vivid shows your code. Choose Open Simkl to approve it in your browser, where the code is usually filled in (if it isn't, enter the code Vivid shows), or go to simkl.com/pin on another device and enter it. Sign in, allow Vivid, then come back to Vivid.
- Apple TV: scan the QR code with your phone, or go to simkl.com/pin on any device and enter the code shown.
- Status shows Connected with a green dot, and the first sync starts straight away.
Note
Simkl signs in on each device separately. Simkl ends a sign-in's old access each time it's renewed, so one sign-in shared between devices would keep cutting the others off. The sign-in stays in that device's Keychain and isn't synced through iCloud, so sign in on your iPhone, iPad and Apple TV one at a time. Each one only takes a code.
Vivid never sees your Simkl password. It asks Simkl for permission to read and update your lists, and the code stops working after 15 minutes.
| Feature | How it works |
|---|---|
| Watched history | When you finish a movie or episode, or mark one as watched, Vivid sends it to Simkl once your server has saved it, with the time you finished. Downloads you watch offline are sent once your server catches up. Episodes are sent with the show's IDs and their season and episode numbers, numbered the way your server numbers them, anime included. |
| Plan to Watch sync | Movies and series you add to your Vivid watchlist go on Simkl's Plan to Watch, and titles you add to Plan to Watch on Simkl come to your Vivid watchlist when they're on the server you're using. Removing a title from your Vivid watchlist takes it off Plan to Watch, as long as you haven't watched any of it. The first sync combines both lists. On Emby and Jellyfin this is Vivid's watchlist, not your server favourites. |
| Once you start watching | Simkl moves a title from Plan to Watch to Watching or Completed once you watch it, and Vivid keeps it on your watchlist. Deleting a title from your Simkl library, or marking it Dropped, takes it off your Vivid watchlist. |
| Background sync | Vivid checks Simkl when you open it, a minute or two after you finish something or change your watchlist, and about once an hour while it stays open. Sync now runs a check straight away, and the Simkl page shows its progress. Most checks only ask Simkl whether anything has changed, so they use very little of Simkl's daily request allowance. If a check fails, the next automatic one waits, 5 minutes at first and longer each time up to 2 hours, even if you open Vivid again. Sync now doesn't wait, except after Simkl's daily limit or while Simkl is limiting Vivid's requests. |
This works with Silo, Emby and Jellyfin on iPhone, iPad and Apple TV.
- It doesn't bring history from Simkl into Vivid or your server. Watched status and resume points still come from your server.
- It doesn't send what you watched before connecting. Only what you finish after that is sent.
- Marking a whole season or series as watched isn't sent. The individual episodes you finish are.
- Marking something unwatched doesn't remove it from Simkl.
- It never moves a title Simkl already has as Watching, Completed, On Hold or Dropped back to Plan to Watch, and never removes a title you've watched any of.
- Ratings, rewatches, live "now watching" scrobbling and custom lists aren't synced.
- Disconnecting keeps your history and lists on Simkl.
- "The Simkl code expired. Sign in again to get a new one." The code lasts 15 minutes. Choose Sign in with Simkl again.
- "Simkl didn't allow Vivid to update your lists. Sign in again and allow access." Vivid needs permission to update your lists as well as read them. Sign in again and allow it.
- "Your Simkl sign-in has ended. Sign in again to keep syncing." Vivid was removed from Simkl's Connected Apps, or the sign-in went unused for six months. Sign in again. Vivid carries on from where it was for the same Simkl account.
- "Simkl's daily request limit was reached. Sync will continue after it resets." Simkl gives each account a daily request allowance, shared by every app you've connected to it. Vivid stops a little before it runs out and carries on after Simkl resets it at midnight US Eastern time.
- "Simkl is unavailable. Sync will try again later." Vivid couldn't reach Simkl, or Simkl had a problem. Vivid waits before checking again, 5 minutes at first and longer each time it fails in a row, up to 2 hours, even if you open it again. Choose Sync now to try straight away.
- "Simkl is busy. Sync will try again shortly." Simkl asked Vivid to slow down. It checks again in 5 minutes.
- "Simkl is limiting requests from Vivid. Sync will try again later." Simkl has paused Vivid's access for now. Vivid waits six hours before trying again, and Sync now waits too.
- "Sync finished. … watched items could not be matched or confirmed and will be retried." Vivid matches by TMDb, IMDb or TVDB ID, so titles your server hasn't identified stay unmatched. They're tried a few more times, then left.
- A Plan to Watch title from Simkl doesn't appear in Vivid. Vivid only adds it when it finds the same title on your server by name and ID. If your server names it differently, it stays unmatched and is tried again the next day.
- You also use a Simkl plugin on Emby or Jellyfin. Both can send the same watch. Simkl ignores a watch it already has, so you won't see it twice.
OpenSubtitles lets you search for and download subtitles when your server doesn't have the one you want.
- Create a free account at opensubtitles.com and sign in.
- Open API consumers, create a new consumer (call it something like Vivid) and copy its API key.
- In Vivid, open Settings → Plugins → OpenSubtitles. On iPhone and iPad, Get your API key opens the same page.
- Paste it into OpenSubtitles API key (on Apple TV, Personal API key) and choose Save Connection.
- Status shows Connected with a green dot.
Vivid only needs the API key. It never asks for your OpenSubtitles username or password.
| iPhone | Apple TV |
|---|---|
![]() |
![]() |
| Where | How to use it |
|---|---|
| Player on iPhone and iPad | Tap the Subtitles button and choose Find on OpenSubtitles. Check the title, enter a two-letter language code such as en or fr, then tap Search. Pick the release that matches your file and Vivid downloads it and switches to it. It shows in the subtitle list as "OpenSubtitles · file name". |
| Player on Apple TV | Open the Subtitles menu and choose Find on OpenSubtitles at the bottom. Vivid searches straight away in your subtitle language from Settings → Subtitles, or English. Use Language to search in another language, then choose a result. |
| Movie and episode pages | The Subtitles selector also has Find on OpenSubtitles. The subtitle you pick is used when you start playing. Auto shows what your Subtitles settings will pick for that file instead, such as English (Forced), and the selector is there even for a file without subtitles of its own. |
| Next time you watch | Vivid remembers the subtitle you chose for each title (your 40 most recent), so it comes back when you play that title again. The Subtitles selector on the movie or episode page lists it as "OpenSubtitles · file name" with a tick, so you can see it's kept. It stays until you choose another subtitle, Off or Auto, or disconnect. Apple TV may clear these to free up space. |
This works with Silo, Emby and Jellyfin on iPhone, iPad and Apple TV.
- Each download counts towards OpenSubtitles' download limit. Vivid connects with the API key only and doesn't sign in to your OpenSubtitles account, so account allowances don't apply.
- Searches use the title, plus the season and episode for episodes. They don't match your exact file, so choose a release that matches yours. If the timing is still off on Apple TV, use Subtitle Delay in the player settings. It moves that subtitle up to 10 seconds either way and remembers the setting. iPhone and iPad don't have a subtitle delay control yet.
- Downloaded subtitles stay on your device. Nothing is uploaded to your server.
- Disconnecting removes the key for this server and profile and forgets the subtitle Vivid remembered for each title.
- Subtitles your Silo server stores for a file (downloaded, uploaded or made by Silo's AI) don't need the plugin. They're listed in the Subtitles menus with the file's own tracks.
- "Check your OpenSubtitles API key. An account may be required by OpenSubtitles for this download." Copy the key again from your API consumers page.
- "OpenSubtitles' download or request limit has been reached. Try again after your quota resets." You've used your downloads for now. Try again once OpenSubtitles resets your limit.
- "Connect OpenSubtitles in Settings → Plugins before searching for subtitles." This profile isn't connected yet. Each profile needs its own connection.
- "The connection or playing item changed. Please search again." when saving or disconnecting the key. Sign in to a server and choose your profile first, then try again.
- "No subtitles found. Try another title or language." Try the original title, or another language.
Screenshots are from iPhone and Apple TV. iPad looks much the same as iPhone.
Server Connections covers how plugin keys sync, what's stored on each device and current verification limits. Seerr requests aren't a plugin: they have their own Settings → Seerr page, covered in Server Connections. The in-app Privacy Policy under Settings → About explains what TMDb, MDBList, Simkl and OpenSubtitles receive.












