Vesper settings reference
Every setting a Vesper settings file can carry, generated from the app.
224 settings in 21 categories, from Vesper 1.0.2 (26). Markdown: https://watchvesper.app/docs/settings-reference.md. JSON: https://watchvesper.app/settings-reference.json.
How a settings file works
- A settings file has a
categoriesobject; each category holds the settings below under their keys. - A file may hold only the settings to change: a setting missing from it, or a category missing from it, is left as it is on the device (the one exception: a
libraryScreencategory withoutlibraryRowsputs the Library rows back to the default). - A group setting is replaced whole, so give all of its fields.
- Import a file in Vesper on iPhone, iPad, Mac or Apple Vision Pro, under Settings > Share & Backup > Import a File; the preview lists what will change and anything skipped.
- Apple TV can't open a file: import it on one of those devices first, then on the Apple TV open Settings > Share & Backup > Receive with a Code, and on the other device choose Share & Backup > Send Once, the settings to send, and Send to Another Device.
- The guide, the FAQ and where to send feedback: https://watchvesper.app/llms.txt
What a file can't do
- Sign in to Trakt, SIMKL, MDBList, WeTrakr or Plex. Those sign-ins happen in the app on each device.
- Set a profile PIN or the Parental Controls passcode.
- Set something for one person on a shared profile: every setting in a file applies to the whole profile it's imported into.
- Change device or TV output settings, such as the Apple TV's video format, frame rate matching or audio output; those live in the device's own Settings app.
A file that changes one setting
{
"categories": {
"playback": {
"skipTVIntros": true
}
}
}Markers
- Secret
- Left out of a file unless you choose to include it when you export.
- Stays on this device
- Not synced to your other devices through iCloud. Importing sets it on the device that imports the file.
- Not in Settings
- Has no control of its own in Settings, so the name here describes it.
Playback & Video Player
playback · Quality, auto-play, player selection, gestures, handoff
Resume Playback
playback.resumePlayback · Not in Settings
Starts a movie or episode where you stopped watching instead of at the beginning.
- Values
trueorfalse- Default
true
Auto-Play Next Episode
playback.autoPlayNextEpisode
Starts the next episode on its own when one ends.
- Values
trueorfalse- Default
true
Automatically Skip Intros
playback.skipTVIntros
Skips an episode's intro once enough community timestamps agree on where it is.
- Values
trueorfalse- Default
false
Automatically Skip Recaps
playback.skipTVRecaps
Skips the recap at the start of an episode once enough community timestamps agree on where it is.
- Values
trueorfalse- Default
false
Use Timestamps From My Server
playback.useMediaServerIntroMarkers
Uses the intro and recap markers your own media server publishes before the community timestamps.
- Values
trueorfalse- Default
true
Skip Intro Button
playback.showSkipIntroButton
Shows a Skip button in the player during an intro or recap.
- Values
trueorfalse- Default
true
Next Episode Countdown
playback.showNextEpisodeCountdown
Shows a card near the end of an episode that counts down to the next one.
- Values
trueorfalse- Default
true
Countdown Starts
playback.nextEpisodeCountdownSeconds
How many seconds before the end of an episode the next-episode card appears.
- Values
15,30,45,60or90seconds- Default
30seconds
Preferred Quality (Playback)
playback.preferredQuality · Not in Settings
Not used by this version of Vesper; Settings > Downloads > Preferred Quality is the quality setting that still applies.
- Values
- One of these
"Auto""4K""1080p""720p"
- Default
"Auto"
Auto-Select Stream
playback.autoSelectStream
Plays the best version that meets your stream requirements as soon as you press Play, instead of showing the stream picker.
- Values
trueorfalse- Default
true
Gesture Controls
playback.playerBrightnessGesturesEnabled
Swiping up or down on the left side of the player changes the screen brightness.
- Values
trueorfalse- Default
false- Devices
- iPhone and iPad
Gesture Controls
playback.playerVolumeGesturesEnabled
Swiping up or down on the right side of the player changes the volume.
- Values
trueorfalse- Default
false- Devices
- iPhone and iPad
Gesture Controls
playback.playerDoubleTapSeekEnabled
Double tapping near either edge of the player skips 10 seconds back or forward.
- Values
trueorfalse- Default
true- Devices
- iPhone and iPad
Gesture Controls
playback.playerHoldToSpeedEnabled
Touching and holding the video plays it at double speed until you let go.
- Values
trueorfalse- Default
true- Devices
- iPhone and iPad
Show Loading Progress
playback.playerShowLoadingProgress
Shows a progress bar with a percentage while the built-in player opens a video.
- Values
trueorfalse- Default
true
Show Remaining Time
playback.playerShowRemainingTime
Shows the time left in the video instead of its total length.
- Values
trueorfalse- Default
true
Show Intro & Recap Markers
playback.playerShowIntroRecapMarkers
Marks where intros and recaps are on the player's progress bar.
- Values
trueorfalse- Default
true
Streaming Buffer
playback.playerNetworkBufferDepth
How much video the built-in player loads ahead; a larger buffer rides out connection drops but uses more storage while playing.
- Values
- One of these
"automatic": Automatic"one_minute": 1 Minute"five_minutes": 5 Minutes"maximum": Maximum (10 Minutes)
- Default
"automatic"(Automatic)
Enhanced Upscaling
playback.playerEnhancedUpscaling · Stays on this device
Sharpens video below 1080p on this device as it plays; On + Animation also sharpens animated titles.
- Values
- One of these
"off": Off"on": On"on_with_animation": On + Animation
- Default
"off"(Off)
Fast-Forward Speed
playback.playerSeekAcceleration
How quickly holding left or right on the Apple TV remote moves through a video.
- Values
- One of these
"relaxed": Relaxed"standard": Standard"fast": Faster"fastest": Fastest
- Default
"standard"(Standard)- Devices
- Apple TV
Lossless Audio
playback.playerLosslessSurroundAudio · Stays on this device
Plays Dolby TrueHD and DTS-HD Master Audio uncompressed, up to 7.1, for a receiver connected over HDMI or eARC. It is set on each device on its own, since speakers differ.
- Values
trueorfalse- Default
false- Devices
- Apple TV and Mac
Open When Playback Starts
playback.screeningRoomOpensAutomatically · Stays on this device
Opens the Screening Room around the video whenever playback starts on Apple Vision Pro.
- Values
trueorfalse- Default
true- Devices
- Apple Vision Pro
Audio Track
playback.audioLanguagePreference
Which audio track the built-in player picks: the video's own default, your preferred stream language, or the title's original language.
- Values
- One of these
"videoDefault": Default"preferredStreamLanguage": Preferred Stream Language"originalLanguage": Original Language
- Default
"videoDefault"(Default)
Remember TV Show Choices
playback.rememberTVShowLanguageChoices
Carries the audio and subtitle tracks you pick in one episode over to the show's other episodes.
- Values
trueorfalse- Default
true
Remembered TV Show Languages
playback.tvShowLanguagePreferences · Not in Settings
The audio and subtitle choices remembered for each show, by its TMDB show number.
- Values
- A list; each entry is a show's remembered audio and subtitle choice
- Default
- An empty list
Remember Speed for TV Shows
playback.rememberTVShowPlaybackSpeed
Plays every episode of a show at the speed you last chose for it.
- Values
trueorfalse- Default
true
Remembered TV Show Speeds
playback.tvShowPlaybackRatePreferences · Not in Settings
The playback speed remembered for each show, by its TMDB show number.
- Values
- A list; each entry is a show's remembered playback speed
- Default
- An empty list
Player Mode
playback.playerSelectionMode
Whether one player plays everything or movies and TV shows each have their own.
- Values
- One of these
"same_for_all": Same for all content"by_content_type": Choose by content type
- Default
"same_for_all"(Same for all content)
Default Player
playback.preferredPlayer
The player that opens videos when one player plays everything.
- Values
- One of these
"builtin": Built-in Player"infuse": Infuse"senplayer": SenPlayer"vidhub": VidHub"vlc": VLC"outplayer": Outplayer"forward": Forward
- Default
"builtin"(Built-in Player)
Movies
playback.preferredPlayerMovies
The player that opens movies when movies and TV shows each have their own player.
- Values
- One of these
"builtin": Built-in Player"infuse": Infuse"senplayer": SenPlayer"vidhub": VidHub"vlc": VLC"outplayer": Outplayer"forward": Forward
- Default
"builtin"(Built-in Player)
TV Shows
playback.preferredPlayerShows
The player that opens episodes when movies and TV shows each have their own player.
- Values
- One of these
"builtin": Built-in Player"infuse": Infuse"senplayer": SenPlayer"vidhub": VidHub"vlc": VLC"outplayer": Outplayer"forward": Forward
- Default
"builtin"(Built-in Player)
Open Music In
playback.preferredMusicApp
The app that opens soundtrack albums and recognized songs.
- Values
- One of these
"appleMusic": Apple Music"spotify": Spotify"youtubeMusic": YouTube Music"tidal": TIDAL
- Default
"appleMusic"(Apple Music)
Show Where to Watch
playback.showWatchProviders
Shows which streaming services carry a title on its details page.
- Values
trueorfalse- Default
true
Edit Services
playback.selectedWatchServices
The streaming services you subscribe to, used for Where to Watch, service shelves and Show When Playing.
- Values
- A list; each entry is a streaming service
- Default
- An empty list
Where to Watch
playback.watchProviderDisplayMode
Whether Where to Watch lists every service, puts yours first, or shows only yours.
- Values
- One of these
"show_all": Show All"my_services_first": Put My Services First"my_services_only": Show Only My Services
- Default
"show_all"(Show All)
Availability Types
playback.enabledWatchAvailabilityTypes
Which kinds of availability Where to Watch includes, such as subscription, free, rent or buy.
- Values
- A list of any of these
"flatrate": Included with Subscription"free": Free"ads": Free with Ads"rent": Rent"buy": Buy
- Default
["flatrate","free","ads"](Included with Subscription, Free, Free with Ads)
Watch Region
playback.watchProviderRegionCode · Stays on this device
The country whose streaming catalogs Where to Watch uses; auto follows this device's region.
- Values
- One of these
"auto": Automatic"AC": Ascension Island"AD": Andorra"AE": United Arab Emirates"AF": Afghanistan"AG": Antigua & Barbuda"AI": Anguilla"AL": Albania"AM": Armenia"AO": Angola"AQ": Antarctica"AR": Argentina"AS": American Samoa"AT": Austria"AU": Australia"AW": Aruba"AX": Åland Islands"AZ": Azerbaijan"BA": Bosnia & Herzegovina"BB": Barbados"BD": Bangladesh"BE": Belgium"BF": Burkina Faso"BG": Bulgaria"BH": Bahrain"BI": Burundi"BJ": Benin"BL": St. Barthélemy"BM": Bermuda"BN": Brunei"BO": Bolivia"BQ": Caribbean Netherlands"BR": Brazil"BS": Bahamas"BT": Bhutan"BV": Bouvet Island"BW": Botswana"BY": Belarus"BZ": Belize"CA": Canada"CC": Cocos (Keeling) Islands"CD": Congo - Kinshasa"CF": Central African Republic"CG": Congo - Brazzaville"CH": Switzerland"CI": Côte d’Ivoire"CK": Cook Islands"CL": Chile"CM": Cameroon"CN": China mainland"CO": Colombia"CP": Clipperton Island"CQ": Sark"CR": Costa Rica"CU": Cuba"CV": Cape Verde"CW": Curaçao"CX": Christmas Island"CY": Cyprus"CZ": Czechia"DE": Germany"DG": Diego Garcia"DJ": Djibouti"DK": Denmark"DM": Dominica"DO": Dominican Republic"DZ": Algeria"EA": Ceuta & Melilla"EC": Ecuador"EE": Estonia"EG": Egypt"EH": Western Sahara"ER": Eritrea"ES": Spain"ET": Ethiopia"FI": Finland"FJ": Fiji"FK": Falkland Islands"FM": Micronesia"FO": Faroe Islands"FR": France"GA": Gabon"GB": United Kingdom"GD": Grenada"GE": Georgia"GF": French Guiana"GG": Guernsey"GH": Ghana"GI": Gibraltar"GL": Greenland"GM": Gambia"GN": Guinea"GP": Guadeloupe"GQ": Equatorial Guinea"GR": Greece"GS": So. Georgia & So. Sandwich Isl."GT": Guatemala"GU": Guam"GW": Guinea-Bissau"GY": Guyana"HK": Hong Kong"HM": Heard & McDonald Islands"HN": Honduras"HR": Croatia"HT": Haiti"HU": Hungary"IC": Canary Islands"ID": Indonesia"IE": Ireland"IL": Israel"IM": Isle of Man"IN": India"IO": Chagos Archipelago"IQ": Iraq"IR": Iran"IS": Iceland"IT": Italy"JE": Jersey"JM": Jamaica"JO": Jordan"JP": Japan"KE": Kenya"KG": Kyrgyzstan"KH": Cambodia"KI": Kiribati"KM": Comoros"KN": St. Kitts & Nevis"KP": North Korea"KR": South Korea"KW": Kuwait"KY": Cayman Islands"KZ": Kazakhstan"LA": Laos"LB": Lebanon"LC": St. Lucia"LI": Liechtenstein"LK": Sri Lanka"LR": Liberia"LS": Lesotho"LT": Lithuania"LU": Luxembourg"LV": Latvia"LY": Libya"MA": Morocco"MC": Monaco"MD": Moldova"ME": Montenegro"MF": St. Martin"MG": Madagascar"MH": Marshall Islands"MK": North Macedonia"ML": Mali"MM": Myanmar (Burma)"MN": Mongolia"MO": Macao"MP": Northern Mariana Islands"MQ": Martinique"MR": Mauritania"MS": Montserrat"MT": Malta"MU": Mauritius"MV": Maldives"MW": Malawi"MX": Mexico"MY": Malaysia"MZ": Mozambique"NA": Namibia"NC": New Caledonia"NE": Niger"NF": Norfolk Island"NG": Nigeria"NI": Nicaragua"NL": Netherlands"NO": Norway"NP": Nepal"NR": Nauru"NU": Niue"NZ": New Zealand"OM": Oman"PA": Panama"PE": Peru"PF": French Polynesia"PG": Papua New Guinea"PH": Philippines"PK": Pakistan"PL": Poland"PM": St. Pierre & Miquelon"PN": Pitcairn Islands"PR": Puerto Rico"PS": Palestinian Territories"PT": Portugal"PW": Palau"PY": Paraguay"QA": Qatar"RE": Réunion"RO": Romania"RS": Serbia"RU": Russia"RW": Rwanda"SA": Saudi Arabia"SB": Solomon Islands"SC": Seychelles"SD": Sudan"SE": Sweden"SG": Singapore"SH": St. Helena"SI": Slovenia"SJ": Svalbard & Jan Mayen"SK": Slovakia"SL": Sierra Leone"SM": San Marino"SN": Senegal"SO": Somalia"SR": Suriname"SS": South Sudan"ST": São Tomé & Príncipe"SV": El Salvador"SX": Sint Maarten"SY": Syria"SZ": Eswatini"TA": Tristan da Cunha"TC": Turks & Caicos Islands"TD": Chad"TF": French Southern Territories"TG": Togo"TH": Thailand"TJ": Tajikistan"TK": Tokelau"TL": Timor-Leste"TM": Turkmenistan"TN": Tunisia"TO": Tonga"TR": Türkiye"TT": Trinidad & Tobago"TV": Tuvalu"TW": Taiwan"TZ": Tanzania"UA": Ukraine"UG": Uganda"UM": U.S. Outlying Islands"US": United States"UY": Uruguay"UZ": Uzbekistan"VA": Vatican City"VC": St. Vincent & Grenadines"VE": Venezuela"VG": British Virgin Islands"VI": U.S. Virgin Islands"VN": Vietnam"VU": Vanuatu"WF": Wallis & Futuna"WS": Samoa"XK": Kosovo"YE": Yemen"YT": Mayotte"ZA": South Africa"ZM": Zambia"ZW": Zimbabwe
- Default
"auto"(Automatic)
Show When Playing
playback.offerServicesInStreamPicker
Offers to open a title in one of your streaming services from the stream picker.
- Values
trueorfalse- Default
true
Services First (Older Builds)
playback.showServicesFirstInStreamPicker · Not in Settings
Replaced by Stream Picker Sections; a file from an older build that sets only this still puts your services first.
- Values
trueorfalse- Default
false
Quick Play
playback.quickPlayContinueWatching
Pressing a Continue Watching card starts playing right away instead of opening the details page.
- Values
trueorfalse- Default
false
Suggest What to Watch Next
playback.showPostPlaySuggestions
Suggests similar titles you haven't watched when a movie ends or after a show's latest episode.
- Values
trueorfalse- Default
true
Share What I'm Watching
playback.discordPresenceEnabled
Shows what this profile is watching on its linked Discord account.
- Values
trueorfalse- Default
false- Devices
- iPhone, iPad and Mac
What Friends See
playback.discordPresenceDetail
How much of the title Discord shows your friends.
- Values
- One of these
"titleEpisodeAndPoster": Title, Episode and Poster"titleAndEpisode": Title and Episode"titleOnly": Title Only"somethingOnVesper": Something on Vesper
- Default
"titleEpisodeAndPoster"(Title, Episode and Poster)- Devices
- iPhone, iPad and Mac
Watch Together
playback.watchTogetherDisplayName
The name the people you watch with see; empty uses the profile's name.
- Values
- Text: a name
- Default
- Empty
Subtitles
subtitles · Language, appearance, delay
Auto-Load Subtitles
subtitles.autoLoadSubtitles
Turns subtitles on in your preferred languages whenever a video starts.
- Values
trueorfalse- Default
false
Only When Needed
subtitles.autoLoadSubtitlesOnlyWhenNeeded
With Auto-Load Subtitles on, keeps subtitles off while the audio is already in one of your preferred languages.
- Values
trueorfalse- Default
false
First Preferred Language
subtitles.preferredSubtitleLanguage · Not in Settings
The first of your preferred subtitle languages, written for older builds; Preferred Languages wins when the file has both.
- Values
- Text: a language code, such as en or pt-BR
- Default
"en"
Preferred Languages
subtitles.preferredSubtitleLanguages
The subtitle languages you want, in order of preference.
- Values
- A list of text; each entry is a language code, such as en or pt-BR
- Default
["en"]
Only Show Preferred Languages
subtitles.showOnlyPreferredSubtitleLanguages
Lists only subtitles in your preferred languages in the player's subtitle menu.
- Values
trueorfalse- Default
true
Show Forced Subtitles
subtitles.automaticForcedSubtitles
Shows the forced subtitles a video marks for foreign-language lines while normal subtitles are off.
- Values
trueorfalse- Default
true
Show When Muted
subtitles.automaticSubtitlesWhenMuted
Shows subtitles in your preferred language while the built-in player is muted.
- Values
trueorfalse- Default
true
Show on Skip Back
subtitles.automaticSubtitlesOnSkipBack
Shows subtitles for a few seconds after you skip back, so you catch the line you missed.
- Values
trueorfalse- Default
true
Subtitles From the Video's Source
subtitles.enableStreamProvidedSubtitles · Not in Settings
Retired: subtitles that come with a video always show now. Kept so older builds and files still read.
- Values
trueorfalse- Default
true- On import
- Retired. Import reads it so older files still open, and changes nothing.
Embedded Subtitles
subtitles.enableEmbeddedSubtitles · Not in Settings
Retired: subtitle tracks inside a video file always show now. Kept so older builds and files still read.
- Values
trueorfalse- Default
true- On import
- Retired. Import reads it so older files still open, and changes nothing.
Auto Captions
subtitles.enableAISubtitles
Makes captions on this device from what is said when a video has no subtitles in your language.
- Values
trueorfalse- Default
false
Translate Subtitles (Older Builds)
subtitles.enableAISubtitleTranslation · Not in Settings
The on or off form of Translate Subtitles that older builds write; used only when the file has no translation mode.
- Values
trueorfalse- Default
false
Translate Subtitles
subtitles.subtitleTranslationMode
Whether subtitles in other languages are translated into your first preferred language, on this device when it can or always by your AI provider.
- Values
- One of these
"off": Off"automatic": Automatic"provider": AI Provider
- Default
"off"(Off)
Online Subtitles
subtitles.enableSubtitleProviders
Searches online subtitle sites when a video has no subtitles in your language.
- Values
trueorfalse- Default
true
Subtitle Search Limit
subtitles.subtitleProviderMaxResults
How many online subtitle results to show for each video.
- Values
5,10,15or25- Default
10
OpenSubtitles
subtitles.enableOpenSubtitles
Includes OpenSubtitles in online subtitle searches.
- Values
trueorfalse- Default
true
OpenSubtitles API Key
subtitles.openSubtitlesCredential · Secret
Your own OpenSubtitles API key, used instead of Vesper's shared one.
- Values
- Text
- On import
- A value in the file replaces the device's; an empty one never clears it.
OpenSubtitles Account
subtitles.openSubtitlesUsername · Secret
The user name of your OpenSubtitles account; downloads then count against its own daily allowance.
- Values
- Text
- On import
- A value in the file replaces the device's; an empty one never clears it.
OpenSubtitles Account
subtitles.openSubtitlesPassword · Secret
The password of your OpenSubtitles account; it imports only together with the user name.
- Values
- Text
- On import
- A value in the file replaces the device's; an empty one never clears it.
SubDL
subtitles.enableSubDL
Includes SubDL in online subtitle searches; it needs your own API key.
- Values
trueorfalse- Default
false
SubDL API Key
subtitles.subDLCredential · Secret
Your SubDL API key.
- Values
- Text
- On import
- A value in the file replaces the device's; an empty one never clears it.
Addic7ed
subtitles.enableAddic7ed
Includes Addic7ed in online subtitle searches for TV episodes; it needs no key or account.
- Values
trueorfalse- Default
false
Subtitle Delay (Older Builds)
subtitles.subtitleDelay · Not in Settings
Retired: a fixed subtitle offset in seconds; Automatic Subtitle Timing replaced it and import leaves it alone.
- Values
- A number
- Default
0- On import
- Retired. Import reads it so older files still open, and changes nothing.
Automatic Subtitle Timing
subtitles.automaticSubtitleTiming
Lines up an added subtitle with the video by matching it against a subtitle track the file already has.
- Values
trueorfalse- Default
true
Dim Subtitles in HDR
subtitles.dimSubtitlesInHDR
Softens subtitle brightness while HDR or Dolby Vision video plays in the built-in player.
- Values
trueorfalse- Default
true
Appearance
subtitles.subtitleAppearance
How subtitles look in the built-in player: font, size, colors, outline, background and position. Import replaces the whole group, so keep every field when changing one.
- Values
- A group: subtitle font, size, colors, outline, background and position
sizeScale: Text size as a multiple of the normal size; 1 is normal, 1.25 a quarter larger. A number from0.5to2.5, in steps of0.05.bold: Bold text.trueorfalse.italic: Italic text.trueorfalse.fontFamily: The typeface. One of these."default": Default"rounded": Rounded"serif": Serif"monospaced": Monospaced
textColor: The text color. A group: the text color as red, green, blue and alpha, each from 0 to 1.red: How much red, from 0 to 1. A number from0to1.green: How much green, from 0 to 1. A number from0to1.blue: How much blue, from 0 to 1. A number from0to1.alpha: How opaque, from 0 (see-through) to 1 (solid). A number from0to1.
outlineColor: The outline color. A group: the outline color as red, green, blue and alpha, each from 0 to 1.red: How much red, from 0 to 1. A number from0to1.green: How much green, from 0 to 1. A number from0to1.blue: How much blue, from 0 to 1. A number from0to1.alpha: How opaque, from 0 (see-through) to 1 (solid). A number from0to1.
outlineWidth: How thick the outline around the text is; 0 is none. A number from0to8, in steps of0.5.backgroundColor: The box behind the text; an alpha of 0 means no box. A group: the background color as red, green, blue and alpha, each from 0 to 1.red: How much red, from 0 to 1. A number from0to1.green: How much green, from 0 to 1. A number from0to1.blue: How much blue, from 0 to 1. A number from0to1.alpha: How opaque, from 0 (see-through) to 1 (solid). A number from0to1.
verticalPlacement: Where subtitles sit on screen. One of these."bottom": Bottom"center": Middle"top": Top
horizontalPlacement: How lines are aligned. One of these."leading": Left"center": Center"trailing": Right
verticalMargin: How far subtitles sit from the top or bottom edge, in points. A number from0to200points, in steps of1.leftMargin: Space kept clear on the left, in points. A number from0to200points, in steps of1.rightMargin: Space kept clear on the right, in points. A number from0to200points, in steps of1.stripEmbeddedStyle: On ignores the fonts and colors a subtitle track brings and uses these instead.trueorfalse.useSystemCaptionStyle: On uses the caption style from the device's Accessibility settings in place of these.trueorfalse.imageSubtitleScale: Size of picture-based subtitles, such as those on Blu-ray discs; 1 is their own size. A number from0.1to2, in steps of0.05.imageSubtitleOffsetX: Moves picture-based subtitles left or right, in points. A number from-200to200points, in steps of1.imageSubtitleOffsetY: Moves picture-based subtitles up or down, in points. A number from-200to200points, in steps of1.
- Default
{ "backgroundColor": { "alpha": 0, "blue": 0, "green": 0, "red": 0 }, "bold": false, "fontFamily": "default", "horizontalPlacement": "center", "imageSubtitleOffsetX": 0, "imageSubtitleOffsetY": 0, "imageSubtitleScale": 1, "italic": false, "leftMargin": 10, "outlineColor": { "alpha": 1, "blue": 0, "green": 0, "red": 0 }, "outlineWidth": 1, "rightMargin": 10, "sizeScale": 1, "stripEmbeddedStyle": true, "textColor": { "alpha": 1, "blue": 1, "green": 1, "red": 1 }, "useSystemCaptionStyle": false, "verticalMargin": 10, "verticalPlacement": "bottom" }
Trailers
trailers · Trailer playback and audio preferences
Autoplay Trailers
trailers.enableTrailers
Plays trailers on their own on the Home screen and on movie and show pages. This is the main switch: Play in Home Cards on Apple TV needs it on too.
- Values
trueorfalse- Default
false
Play Trailers with Audio
trailers.trailerAudioEnabled
Starts trailers with sound instead of muted.
- Values
trueorfalse- Default
false
Skip for Shows I'm Watching
trailers.skipTrailersForWatchingShows
Doesn't play trailers on the pages of shows you're already watching.
- Values
trueorfalse- Default
true
Data Usage
trailers.disableTrailersOnCellular
On means trailers play only on Wi-Fi; off lets them play on cellular data too.
- Values
trueorfalse- Default
false- Devices
- iPhone and iPad
Rotate to Full Screen
trailers.trailerRotateToFullScreen
Turning the iPhone sideways while a trailer plays opens it full screen.
- Values
trueorfalse- Default
true- Devices
- iPhone
Play in Home Cards
trailers.playTrailersInHomeCards
Plays a title's trailer inside its card on the Apple TV Home screen in the Shelves layout. It works only while Autoplay Trailers is on; with that off, no trailer plays whatever this says.
- Values
trueorfalse- Default
true- Devices
- Apple TV
Trailer Language
trailers.trailerLanguage
Which language a trailer is picked in: app for Vesper's language, original for the title's own, or lang: and a language code.
- Values
- One of these
"app": Same as Vesper"original": Original Language"lang:aa": Afar"lang:ab": Abkhazian"lang:ae": Avestan"lang:af": Afrikaans"lang:ak": Akan"lang:am": Amharic"lang:an": Aragonese"lang:ar": Arabic"lang:as": Assamese"lang:av": Avaric"lang:ay": Aymara"lang:az": Azerbaijani"lang:ba": Bashkir"lang:be": Belarusian"lang:bg": Bulgarian"lang:bi": Bislama"lang:bm": Bambara"lang:bn": Bangla"lang:bo": Tibetan"lang:br": Breton"lang:bs": Bosnian"lang:ca": Catalan"lang:ce": Chechen"lang:ch": Chamorro"lang:co": Corsican"lang:cr": Cree"lang:cs": Czech"lang:cu": Church Slavic"lang:cv": Chuvash"lang:cy": Welsh"lang:da": Danish"lang:de": German"lang:dv": Dhivehi"lang:dz": Dzongkha"lang:ee": Ewe"lang:el": Greek"lang:en": English"lang:eo": Esperanto"lang:es": Spanish"lang:et": Estonian"lang:eu": Basque"lang:fa": Persian"lang:ff": Fula"lang:fi": Finnish"lang:fj": Fijian"lang:fo": Faroese"lang:fr": French"lang:fy": Western Frisian"lang:ga": Irish"lang:gd": Scottish Gaelic"lang:gl": Galician"lang:gn": Guarani"lang:gu": Gujarati"lang:gv": Manx"lang:ha": Hausa"lang:he": Hebrew"lang:hi": Hindi"lang:ho": Hiri Motu"lang:hr": Croatian"lang:ht": Haitian Creole"lang:hu": Hungarian"lang:hy": Armenian"lang:hz": Herero"lang:ia": Interlingua"lang:id": Indonesian"lang:ie": Interlingue"lang:ig": Igbo"lang:ii": Liangshan Yi"lang:ik": Inupiaq"lang:io": Ido"lang:is": Icelandic"lang:it": Italian"lang:iu": Inuktitut"lang:ja": Japanese"lang:jv": Javanese"lang:ka": Georgian"lang:kg": Kongo"lang:ki": Kikuyu"lang:kj": Kuanyama"lang:kk": Kazakh"lang:kl": Kalaallisut"lang:km": Khmer"lang:kn": Kannada"lang:ko": Korean"lang:kr": Kanuri"lang:ks": Kashmiri"lang:ku": Kurdish"lang:kv": Komi"lang:kw": Cornish"lang:ky": Kyrgyz"lang:la": Latin"lang:lb": Luxembourgish"lang:lg": Ganda"lang:li": Limburgish"lang:ln": Lingala"lang:lo": Lao"lang:lt": Lithuanian"lang:lu": Luba-Katanga"lang:lv": Latvian"lang:mg": Malagasy"lang:mh": Marshallese"lang:mi": Māori"lang:mk": Macedonian"lang:ml": Malayalam"lang:mn": Mongolian"lang:mr": Marathi"lang:ms": Malay"lang:mt": Maltese"lang:my": Burmese"lang:na": Nauru"lang:nb": Norwegian Bokmål"lang:nd": North Ndebele"lang:ne": Nepali"lang:ng": Ndonga"lang:nl": Dutch"lang:nn": Norwegian Nynorsk"lang:no": Norwegian"lang:nr": South Ndebele"lang:nv": Navajo"lang:ny": Nyanja"lang:oc": Occitan"lang:oj": Ojibwa"lang:om": Oromo"lang:or": Odia"lang:os": Ossetic"lang:pa": Punjabi"lang:pi": Pali"lang:pl": Polish"lang:ps": Pashto"lang:pt": Portuguese"lang:qu": Quechua"lang:rm": Romansh"lang:rn": Rundi"lang:ro": Romanian"lang:ru": Russian"lang:rw": Kinyarwanda"lang:sa": Sanskrit"lang:sc": Sardinian"lang:sd": Sindhi"lang:se": North Sámi"lang:sg": Sango"lang:si": Sinhala"lang:sk": Slovak"lang:sl": Slovenian"lang:sm": Samoan"lang:sn": Shona"lang:so": Somali"lang:sq": Albanian"lang:sr": Serbian"lang:ss": Swati"lang:st": Southern Sotho"lang:su": Sundanese"lang:sv": Swedish"lang:sw": Swahili"lang:ta": Tamil"lang:te": Telugu"lang:tg": Tajik"lang:th": Thai"lang:ti": Tigrinya"lang:tk": Turkmen"lang:tn": Tswana"lang:to": Tongan"lang:tr": Turkish"lang:ts": Tsonga"lang:tt": Tatar"lang:tw": Twi"lang:ty": Tahitian"lang:ug": Uyghur"lang:uk": Ukrainian"lang:ur": Urdu"lang:uz": Uzbek"lang:ve": Venda"lang:vi": Vietnamese"lang:vo": Volapük"lang:wa": Walloon"lang:wo": Wolof"lang:xh": Xhosa"lang:yi": Yiddish"lang:yo": Yoruba"lang:za": Zhuang"lang:zh": Chinese"lang:zu": Zulu
- Default
"app"(Same as Vesper)
Home Screen & Shelves
homeScreen · Custom shelves and hero carousel configuration
Home Rows
homeScreen.homeShelfWidgets
The rows on the Home screen, in order, with what each one shows.
- Values
- A list; each entry is a Home row
Showcases
homeScreen.catalogHubCollections
The Showcase folders on the Home screen and the catalogs and lists inside them.
- Values
- A list; each entry is a Showcase folder
Hero Carousel
homeScreen.homeHeroConfiguration
What the large carousel at the top of the Home screen shows and how many titles it holds.
- Values
- A group: the carousel's source, content, item count, filters and order
source: Where the titles come from. One of these."trending": Trending"popular": Popular"discover": Discover"continueWatching": Continue Watching"existingShelf": Home Shelves
mediaSelection: Movies, TV shows or both. One of these."movies": Movies"tvShows": TV Shows"mixed": Mixed
itemCount: How many titles the carousel holds. A whole number from4to20, in steps of1.shuffle: Shows the titles in a fresh order.trueorfalse.filters: Genre, year and rating filters, the same ones a Home row has. A group: a Home row's filters.existingShelfIDs: With the Home Shelves source, the ids of the Home rows it draws from. A list of text; each entry is a Home row's id.
- Default
{ "existingShelfIDs": [], "filters": { "availability": "Any", "minVoteCount": 50, "sortBy": "popularity.desc" }, "itemCount": 8, "mediaSelection": "mixed", "shuffle": true, "source": "trending" }
Home Personalization
homeScreen.homePersonalizationMode
Whether personalization only suggests rows for you to add or also places rows on Home itself.
- Values
- One of these
"suggestions_only": Suggestions Only"automatic_home": Automatic Home
- Default
"automatic_home"(Automatic Home)
Shuffle Titles
homeScreen.shuffleHomeTitles
Shows each Home row's titles in a fresh order on each launch, except rows whose order means something.
- Values
trueorfalse- Default
false
Coming Soon Row
homeScreen.homeComingSoonRowEnabled
Shows a Coming Soon row with upcoming episodes and releases next to Continue Watching.
- Values
trueorfalse- Default
false
Library Screen
libraryScreen · Row order and visibility on the Library page
Library Rows
libraryScreen.libraryRows
The rows on the Library page, in order, and whether each one shows; a file that has this category without the key puts the rows back to the default.
- Values
- A list; each entry is a Library row: its kind and whether it shows
- Default
[ { "enabled": true, "kind": "movieWatchlist" }, { "enabled": true, "kind": "tvWatchlist" }, { "enabled": true, "kind": "favorites" }, { "enabled": true, "kind": "comingSoon" }, { "enabled": true, "kind": "recentlyReleased" }, { "enabled": true, "kind": "history" } ]- On import
- Replaces the device's value; a file that has this category but leaves this key out puts it back to the default.
Streams & Sorting
streams · Sort order, display mode, language, limits
Preset
streams.streamSortPreset
How streams are ranked: Quality, Speed and Server Order each rank in their own fixed way, and Custom uses streamSortPriorities. To switch ranking, changing this alone is enough; the priorities left from the export follow it.
- Values
- One of these
"quality": Quality"speed": Speed"providerOrder": Server Order"custom": Custom
- Default
"speed"(Speed)
Custom
streams.streamSortPriorities
The ranking order, highest priority first, used by the Custom preset. A file whose list differs from every preset's own ranking makes the preset Custom on import.
- Values
- A list; each entry is a sort criterion and its direction
- Default
[ { "direction": "descending", "type": "cached" }, { "direction": "ascending", "type": "size" }, { "direction": "descending", "type": "resolution" }, { "direction": "descending", "type": "hdr" }, { "direction": "descending", "type": "language" }, { "direction": "descending", "type": "atmos" }, { "direction": "descending", "type": "sourceQuality" }, { "direction": "descending", "type": "audioFormat" }, { "direction": "descending", "type": "audioChannels" } ]
Custom
streams.customStreamSortPriorities
Your own ranking order, kept for when you pick the Custom preset; an empty list means none saved.
- Values
- A list; each entry is a sort criterion and its direction
- Default
- An empty list
Sort Order (Older Builds)
streams.streamSortOrder · Not in Settings
The single sort order older builds used before presets; kept so their files still read.
- Values
- One of these
"default": Default"resolution": Resolution"size": Size"cached": Ready to Play"hdr": HDR / Dolby Vision"atmos": Dolby Atmos
- Default
"default"(Default)- On import
- Retired. Import reads it so older files still open, and changes nothing.
Sort Direction (Older Builds)
streams.streamSortDirection · Not in Settings
The sort direction older builds used before presets; kept so their files still read.
- Values
- One of these
"descending": Highest First"ascending": Lowest First
- Default
"descending"(Highest First)- On import
- Retired. Import reads it so older files still open, and changes nothing.
Display Mode
streams.streamDisplayMode
Whether stream cards show tidy details and icons or the raw names your sources give them.
- Values
- One of these
"polished": Polished"original": Original
- Default
"polished"(Polished)
Card Layout
streams.streamCardLayout
Which details a polished stream card shows; they always appear in Vesper's fixed order.
- Values
- A list of any of these
"fileSize": File Size"runtime": Runtime"availability": Availability"languages": Languages"rating": Rating"ageRating": Age Rating"provider": Provider"edition": Edition"releaseGroup": Release Group"tags": Stream Tags"releaseName": Release Name
- Default
[ "fileSize", "runtime", "languages", "provider", "edition", "releaseGroup", "tags" ]
Stream Picker Sections
streams.streamPickerSourceOrder
The order of the media server, network share and streaming service sections in the stream picker.
- Values
- A list of any of these
"mediaServers": Media Servers"networkShares": Network Shares"services": Your Services
- Default
["mediaServers","networkShares","services"](Media Servers, Network Shares, Your Services)
Preferred Stream Language
streams.preferredStreamLanguage
The language Vesper favors when ranking streams and, if Audio Track says so, when picking audio.
- Values
- One of these
"English""Español""Français""Deutsch""Italiano""Português""Русский""日本語""한국어""中文""हिन्दी""العربية"
- Default
"English"
Allowed Resolutions
streams.streamAllowedResolutions
Only versions at these resolutions are picked automatically; an empty list allows every resolution.
- Values
- A list of any of these
"4K""1440p""1080p""720p""480p"
- Default
["4K","1440p","1080p"](4K, 1440p, 1080p)
Required Languages
streams.streamRequiredLanguages
Only versions in at least one of these languages are picked automatically; an empty list allows any.
- Values
- A list of any of these
"English""Español""Français""Deutsch""Italiano""Português""Русский""日本語""한국어""中文""हिन्दी""العربية"
- Default
- An empty list
Excluded Resolutions
streams.streamExcludedResolutions
Versions at these resolutions are never picked automatically.
- Values
- A list of any of these
"4K""1440p""1080p""720p""480p"
- Default
- An empty list
Excluded Languages
streams.streamExcludedLanguages
Versions in these languages are never picked automatically.
- Values
- A list of any of these
"English""Español""Français""Deutsch""Italiano""Português""Русский""日本語""한국어""中文""हिन्दी""العربية"
- Default
- An empty list
Allowed Sources
streams.streamRequiredQualities
Only versions from these kinds of source, such as Blu-ray or web, are picked automatically; an empty list allows any.
- Values
- A list of any of these
"remux": Remux"bluRay": BluRay"webDL": WEB-DL"webRip": WEBRip"bdRip": BDRip"hdRip": HDRip"hdtv": HDTV"dvdRip": DVDRip"dvd": DVD"screener": Screener"telecine": TC"telesync": TS"cam": CAM
- Default
- An empty list
Excluded Sources
streams.streamExcludedQualities
Versions from these kinds of source are never picked automatically.
- Values
- A list of any of these
"remux": Remux"bluRay": BluRay"webDL": WEB-DL"webRip": WEBRip"bdRip": BDRip"hdRip": HDRip"hdtv": HDTV"dvdRip": DVDRip"dvd": DVD"screener": Screener"telecine": TC"telesync": TS"cam": CAM
- Default
- An empty list
Ready to Play Only
streams.streamRequireCached
Only versions that can start playing right away are picked automatically.
- Values
trueorfalse- Default
false
Require Dolby Atmos
streams.streamRequireDolbyAtmos
Only versions with Dolby Atmos audio are picked automatically.
- Values
trueorfalse- Default
false
Require Dolby Vision
streams.streamRequireDolbyVision
Only versions in Dolby Vision are picked automatically.
- Values
trueorfalse- Default
false
Size Limit (Older Builds)
streams.autoSelectMaxSizeGB · Not in Settings
The single size limit older builds used, in GB; it sets both the movie and episode limits when a file has neither, and is ignored next to either of them.
- Values
- A number from
0to1000GB - Default
0GB
Movie Size Limit
streams.streamMovieMaxSizeGB
The largest movie file Auto-Select picks, in GB; 0 means no limit.
- Values
- A number from
0to1000GB. Settings offers0,5,10,15,20,25,30,40,50,60,80or100 - Default
0GB
TV Episode Size Limit
streams.streamEpisodeMaxSizeGB
The largest episode file Auto-Select picks, in GB; 0 means no limit.
- Values
- A number from
0to1000GB. Settings offers0,1,2,3,5,8,10,15or20 - Default
0GB
Cellular Size Limit
streams.streamCellularMaxSizeGB
The largest file Auto-Select picks while on cellular data, in GB; 0 means the normal limits apply. A version you pick yourself in the stream picker isn't limited, but when you resume on cellular a remembered version larger than this is passed over and Auto-Select chooses again.
- Values
- A number from
0to1000GB. Settings offers0,1,2,3,5,8,10,15or20 - Default
0GB- Devices
- iPhone and iPad
Match Connection Speed
streams.streamMatchConnectionSpeed
Skips versions too large for your connection to play smoothly when picking automatically.
- Values
trueorfalse- Default
true
Request Timeout
streams.providerTimeout
How long to wait for trailer requests and subtitle downloads, in seconds.
- Values
- A whole number from
5to30seconds, in steps of1. Settings offers5,10,15,20,25or30 - Default
20seconds
Prefer Your Library (Older Builds)
streams.preferMediaServersForAutoSelect · Not in Settings
Retired: Auto-Select always prefers your own library now. Kept so older files still read.
- Values
trueorfalse- On import
- Retired. Import reads it so older files still open, and changes nothing.
Remember Stream Selection
streams.rememberStreamSelections
Puts the version you picked by hand at the top of the stream picker the next time you play that title.
- Values
trueorfalse- Default
true
Remember For
streams.pinnedStreamExpiry
How long a version you picked by hand stays at the top of the stream picker.
- Values
- One of these
"1_day": 24 Hours"3_days": 3 Days"1_week": 1 Week"never": Never Expire
- Default
"1_week"(1 Week)
Stream Tags
streams.streamTagPacks
Tag packs added from a web address; importing adds packs and never removes one.
- Values
- A list; each entry is a tag pack: its address and name
- Default
- An empty list
- On import
- Adds the file's entries; entries already on the device stay.
Stream Tags
streams.streamTagActivePackID
The id of the added tag pack whose tags stream cards use; empty uses Vesper's built-in tags.
- Values
- Text: a tag pack id, or empty for the built-in tags
- Default
- Empty
Hide Filtered Streams
streams.streamHideFilteredStreams
Hides versions that don't meet your requirements from the stream picker instead of listing them last.
- Values
trueorfalse- Default
false
Prefer 3D Versions
streams.preferStereoStreams · Stays on this device
Ranks 3D versions first on Apple Vision Pro.
- Values
trueorfalse- Default
false- Devices
- Apple Vision Pro
Content Restrictions
contentRestrictions · Rating limits and genre exclusions
Movie Rating
contentRestrictions.maxMovieCertification
The highest movie age rating shown, written as this device's region writes it; empty means no limit. In the US the ratings are G, PG, PG-13, R, NC-17; other regions use their own. A rating the region doesn't have counts as its strictest one until a limit is chosen again in Parental Controls.
- Values
- Text: an age rating, or empty for no limit
- Default
- Empty
TV Rating
contentRestrictions.maxTVCertification
The highest TV age rating shown, written as this device's region writes it; empty means no limit. In the US the ratings are TV-Y, TV-Y7, TV-G, TV-PG, TV-14, TV-MA; other regions use their own. A rating the region doesn't have counts as its strictest one until a limit is chosen again in Parental Controls.
- Values
- Text: an age rating, or empty for no limit
- Default
- Empty
Hide Unrated/Unknown
contentRestrictions.hideUnratedRestrictedContent
With a rating limit set, also hides titles that have no age rating.
- Values
trueorfalse- Default
true
Excluded Genres
contentRestrictions.excludedGenres
Titles in these genres are hidden everywhere in Vesper.
- Values
- A list of text; each entry is a genre name, such as Horror
- Default
- An empty list
Hide Server Titles with Unknown Genres
contentRestrictions.hideMediaServerTitlesWithUnknownGenres
With genres excluded, also hides titles from your media servers whose genre isn't known.
- Values
trueorfalse- Default
false
Hide Anime
contentRestrictions.hideAnime
Hides anime everywhere in Vesper.
- Values
trueorfalse- Default
false
Allowed Categories
contentRestrictions.liveTVAllowedCategories
With restrictions on, the Live TV categories that stay visible; an empty list hides Live TV while any restriction is set.
- Values
- A list of text; each entry is a Live TV category name, as your playlist names it
- Default
- An empty list
Unlock Restrictions
contentRestrictions.requireDeviceAuthenticationToEdit
Asks for Face ID, Touch ID, the device passcode or the Parental Controls passcode before these settings can change.
- Values
trueorfalse- Default
false
Parents Guide
contentRestrictions.showParentsGuide
Shows a summary of a title's content, such as violence or language, on its page.
- Values
trueorfalse- Default
true
Reviews
contentRestrictions.showReviews
Shows reviews on movie and show pages.
- Values
trueorfalse- Default
true
Translate Reviews
contentRestrictions.translateReviews
Translates reviews written in another language into yours.
- Values
trueorfalse- Default
true
Review Source
contentRestrictions.reviewSourcePreference
Where reviews come from: TMDB, Trakt, or whichever has them.
- Values
- One of these
"auto": Auto"tmdb": TMDB"trakt": Trakt
- Default
"auto"(Auto)
TV Shows
tvShows · Smart Resume, Stay Current, intro skipping, contributions
Smart Resume
tvShows.smartResumeEnabled
Opens a show at your next unwatched episode, based on your library history.
- Values
trueorfalse- Default
true
Stay Current
tvShows.stayCurrentEnabled
Opens talk and news shows at their latest episode instead of the next unwatched one.
- Values
trueorfalse- Default
true
Hide Unreleased Episodes
tvShows.hideUnreleasedEpisodes
Hides episodes and seasons that haven't aired yet.
- Values
trueorfalse- Default
true
Hide Spoilers
tvShows.hideSpoilers
Blurs the pictures of episodes you haven't watched in a show's episode list, the player's Episodes panel and the Apple Vision Pro Screening Room. Episode names and descriptions still show.
- Values
trueorfalse- Default
false
Required Submissions
tvShows.introSkipMinimumSubmissionCount
How many community timestamps must agree before an intro or recap is skipped automatically.
- Values
1,2,3or5- Default
2
Mark Intros in Player
tvShows.introDBSubmissionsEnabled
Shows a button in the player for marking where an intro starts and ends, which shares the timestamps with IntroDB.
- Values
trueorfalse- Default
true- Devices
- iPhone, iPad and Mac
IntroDB API Key
tvShows.introDBCredential · Secret
Your IntroDB API key, used to share timestamps you mark.
- Values
- Text
- On import
- A value in the file replaces the device's; an empty one never clears it.
Lists & Catalogs
externalLists · Trakt, MDBList, Letterboxd, and SIMKL lists
Lists & Catalogs
externalLists.externalLists
The lists and catalogs you added, such as Trakt or Letterboxd lists, that rows and Showcases draw from.
- Values
- A list; each entry is a list or catalog
- Default
- An empty list
Artwork Packs
externalLists.showcaseArtworkPacks
Artwork packs added from a web address that give Showcase folders their pictures.
- Values
- A list; each entry is an artwork pack: its address and name
- Default
- An empty list
Show Custom Lists
externalLists.customListsEnabled
Shows your own lists from your library sync service in Vesper.
- Values
trueorfalse- Default
false
Custom Lists
externalLists.selectedCustomLists
Which of your own lists show, by each list's short name.
- Values
- A list of text; each entry is a list's short name
- Default
- An empty list
Continue Watching
continueWatching · Item limit preferences
Continue Watching Limit
continueWatching.continueWatchingLimit
How many titles the Continue Watching row holds.
- Values
- A whole number. Settings offers
5,10,20,25or50 - Default
20
Downloads
downloads · Auto-download, quality, and size limits
Auto-Select Download
downloads.autoDownload · Stays on this device
Downloads the best version that meets your requirements without showing the stream picker.
- Values
trueorfalse- Default
false
Preferred Quality
downloads.downloadPreferredQuality · Stays on this device
The resolution an automatic download aims for; Auto picks the best that fits your size limit.
- Values
- One of these
"Auto""4K""1080p""720p"
- Default
"Auto"
Size Limit (Older Builds)
downloads.downloadMaxSizeGB · Not in Settings
The single download size limit older builds used, in GB; it sets the movie and episode limits when a file has neither, and is ignored next to either of them.
- Values
- A number from
0to1000GB - Default
20GB
Movie Size Limit
downloads.downloadMovieMaxSizeGB · Stays on this device
The largest movie file downloaded automatically, in GB; 0 means no limit.
- Values
- A number from
0to1000GB. Settings offers0,5,10,15,20,25,30,40,50,60,80or100 - Default
20GB
TV Episode Size Limit
downloads.downloadTVShowMaxSizeGB · Stays on this device
The largest episode file downloaded automatically, in GB; 0 means no limit.
- Values
- A number from
0to1000GB. Settings offers0,1,2,3,5,8,10,15or20 - Default
5GB
Simultaneous Downloads
downloads.downloadMaxConcurrentDownloads · Stays on this device
How many downloads run at the same time.
- Values
- A whole number from
1to3, in steps of1. Settings offers1,2or3 - Default
2
Download Using
downloads.downloadNetworkPolicy · Stays on this device
Whether downloads run only on Wi-Fi or Ethernet, or on any network including cellular.
- Values
- One of these
"wifiAndEthernet": Wi-Fi or Ethernet"anyNetwork": Any Network
- Default
"wifiAndEthernet"(Wi-Fi or Ethernet)
Delete After Watching
downloads.downloadAutoDeletePolicy · Stays on this device
Which finished downloads are deleted on their own once you've watched them.
- Values
- One of these
"off": Off"moviesAndEpisodes": Movies and Episodes"movies": Movies"episodes": Episodes
- Default
"off"(Off)
Convert To
downloads.downloadConversionQuality · Stays on this device
The quality a Jellyfin, Emby, Plex or Silo server converts a download to; Original downloads the file as it is.
- Values
- One of these
"original": Original"1080p""720p""480p"
- Default
"original"(Original)
Smart Downloads
downloads.smartDownloadsEnabled · Stays on this device
Downloads the next episodes of a show you're watching and removes the ones you've finished.
- Values
trueorfalse- Default
false
Episodes Ahead
downloads.smartDownloadsEpisodesAhead · Stays on this device
How many upcoming episodes Smart Downloads keeps ready.
- Values
1,2,3or5- Default
2
Trakt Sync
traktSync · Scrobbling and sync frequency
Scrobbling
traktSync.scrobblingEnabled · Not in Settings
Not used by this version of Vesper; kept so older builds and files still read.
- Values
trueorfalse- Default
true- On import
- Retired. Import reads it so older files still open, and changes nothing.
Sync Frequency
traktSync.traktSyncFrequency
How often Vesper syncs with Trakt while it's open and signed in to Trakt. With Trakt as Where Your Library Lives, this is the interval that applies, not Library Sync Frequency.
- Values
- One of these
"on_launch": On Launch"every_minute": Every Minute"hourly": Hourly"every_6_hours": Every 6 Hours"daily": Daily
- Default
"on_launch"(On Launch)
Sync After Another Player
traktSync.syncAfterExternalPlayback · Not in Settings
Not used by this version of Vesper; kept so older builds and files still read.
- Values
trueorfalse- Default
true- On import
- Retired. Import reads it so older files still open, and changes nothing.
AI Search
aiSearch · AI search toggle and API credential
Enhanced Search
aiSearch.aiSearchEnabled
Lets search understand descriptions like a funny heist movie, not just titles.
- Values
trueorfalse- Default
true
Ask Vesper
aiSearch.aiAssistantEnabled
Shows Ask Vesper, which answers questions about what to watch.
- Values
trueorfalse- Default
true
Provider
aiSearch.aiProviderMode
The AI provider used for web lookups and for anything this device can't do on its own.
- Values
- One of these
"gemini": Google Gemini"openAI": OpenAI"perplexity": Perplexity"grok": xAI Grok"claude": Anthropic Claude
- Default
"gemini"(Google Gemini)
Gemini API Key
aiSearch.geminiCredential · Secret
Your Google Gemini API key.
- Values
- Text
- Default
- Empty
- On import
- A value in the file replaces the device's; an empty one never clears it.
OpenAI API Key
aiSearch.openAICredential · Secret
Your OpenAI API key.
- Values
- Text
- Default
- Empty
- On import
- A value in the file replaces the device's; an empty one never clears it.
Perplexity API Key
aiSearch.perplexityCredential · Secret
Your Perplexity API key.
- Values
- Text
- Default
- Empty
- On import
- A value in the file replaces the device's; an empty one never clears it.
xAI API Key
aiSearch.grokCredential · Secret
Your xAI API key, for Grok.
- Values
- Text
- Default
- Empty
- On import
- A value in the file replaces the device's; an empty one never clears it.
Anthropic API Key
aiSearch.claudeCredential · Secret
Your Anthropic API key, for Claude.
- Values
- Text
- Default
- Empty
- On import
- A value in the file replaces the device's; an empty one never clears it.
Hide Results Without Posters
aiSearch.hideSearchResultsWithoutPosters
Leaves search results that have no poster out of the list.
- Values
trueorfalse- Default
true
Metadata Sources
metadataSources · Rating source, AniList, and TVDB preferences
Rating Source
metadataSources.preferredRatingSource
The rating shown first on posters and pages; MDBList sources need an MDBList account.
- Values
- One of these
"tmdb": TMDB"imdb": IMDb"tomatoes": Rotten Tomatoes"popcorn": RT Audience"metacritic": Metacritic"letterboxd": Letterboxd"trakt": Trakt"simkl": SIMKL"anilist": AniList
- Default
"tmdb"(TMDB)
Show Ratings
metadataSources.showRatings
Shows ratings on posters and title pages.
- Values
trueorfalse- Default
true
Show All Rating Sources
metadataSources.showAllRatingSources
Shows every rating Vesper has for a title on its page, not only the preferred one.
- Values
trueorfalse- Default
true
Enhanced Anime
metadataSources.useAniListForAnime
Uses AniList for anime episode lists and details.
- Values
trueorfalse- Default
true
Enhanced Episodes
metadataSources.useTVDBForEpisodes
Uses TVDB for episode lists and numbering where it's more complete.
- Values
trueorfalse- Default
true
Show Rating Icons
metadataSources.ratingSourceIconsEnabled
Shows each rating source's icon next to its rating.
- Values
trueorfalse- Default
false
Color-Code Ratings
metadataSources.ratingSourceColorsEnabled
Colors ratings from red to green by how high they are.
- Values
trueorfalse- Default
true
Rating Posters
metadataSources.posterEnhancementProvider
Whether posters are replaced with versions that have ratings drawn on them.
- Values
- One of these
"off": Off"ratingPosterDatabase": Rating Posters
- Default
"off"(Off)
BetterPosters Labels (Older Builds)
metadataSources.betterPostersConfiguration · Not in Settings
Retired: the labels of the old BetterPosters option; a file that still chooses it turns them into poster badges.
- Values
- A group: which labels the old option drew
- Default
{ "language": "en", "ratingSource": "avg", "showsAgeRating": false, "showsGenre": true, "showsQualityTags": false, "showsRating": true, "showsTrendTags": false }
Rating Posters On
metadataSources.rpdbRatingsEnabled · Not in Settings
The on or off form of Rating Posters; on picks the rating poster service, off turns rating posters off.
- Values
trueorfalse- Default
false
API Key
metadataSources.rpdbCredential · Secret
Your Rating Poster Database API key.
- Values
- Text
- Default
- Empty
- On import
- A value in the file replaces the device's; an empty one never clears it.
API Key
metadataSources.openPosterDBCredential · Secret
Your OpenPosterDB API key.
- Values
- Text
- Default
- Empty
- On import
- A value in the file replaces the device's; an empty one never clears it.
API Key
metadataSources.ratingPosterCustomCredential · Secret
The API key for your custom poster endpoint.
- Values
- Text
- Default
- Empty
- On import
- A value in the file replaces the device's; an empty one never clears it.
Service
metadataSources.ratingPosterService
Which service draws the rating posters.
- Values
- One of these
"ratingPosterDatabase": Rating Poster Database"openPosterDB": OpenPosterDB"custom": Custom Endpoint
- Default
"ratingPosterDatabase"(Rating Poster Database)
Custom Endpoint
metadataSources.ratingPosterCustomBaseURL
The web address of your own rating poster service, used when Service is Custom Endpoint.
- Values
- Text: a web address
- Default
- Empty
Rating Icons
metadataSources.ratingSourceIcons
Custom rating icons added on this device, as image data by rating source.
- Values
- A group: image data for each rating source
Rating Icons
metadataSources.ratingSourceIconProvenance
Where each custom rating icon came from, so another device can fetch it again.
- Values
- A group: an icon address for each rating source
Media Servers
mediaServers · Plex, Jellyfin, Emby, and Silo server connections
Connected Servers
mediaServers.connections · Secret
Your Jellyfin, Emby, Plex and Silo servers; importing adds servers you don't have yet, and each one asks you to sign in again.
- Values
- A list; each entry is a media server: its type, address, name and user
- Default
- An empty list
- On import
- Adds the file's entries; entries already on the device stay.
Show Server Badge
mediaServers.showMediaServerBadge
Marks posters of titles you have on your own servers or network shares.
- Values
trueorfalse- Default
true
Show Library Shortcuts
mediaServers.showMediaServerLibraryShortcuts
Shows shortcuts to your server and share libraries on the Library page.
- Values
trueorfalse- Default
true
Library Refresh
mediaServers.mediaServerRefreshInterval
How often each server's library refreshes, in minutes; 0 means only when you choose Refresh Library.
- Values
- A whole number, in minutes. Settings offers
0,15,30,60,120,360,720or1440 - Default
60minutes
Poster Artwork
mediaServers.mediaServerArtworkSource
Whether your server libraries show your server's own posters or Vesper's.
- Values
- One of these
"server": From My Server"vesper": From Vesper
- Default
"server"(From My Server)
Server Sign-Ins
mediaServers.directLogins · Secret · Not in Settings
Sign-ins Web Setup collected for Jellyfin, Emby and Silo servers; Vesper signs in with each once and keeps no password.
- Values
- A list; each entry is a server sign-in: type, address, user name and password
- On import
- Adds the file's entries; entries already on the device stay.
Live TV
liveTV · IPTV playlists and Xtream accounts
Sources
liveTV.sources · Secret
Your Live TV playlists and accounts; importing adds sources you don't have yet.
- Values
- A list; each entry is a Live TV source: its kind, addresses and guide settings
- Default
- An empty list
- On import
- Adds the file's entries; entries already on the device stay.
Show Favorites on Home
liveTV.showFavoritesOnHome
Shows a row of your favorite channels on the Home screen.
- Values
trueorfalse- Default
true
Show Channels in Search
liveTV.showChannelsInSearch
Includes Live TV channels in search results.
- Values
trueorfalse- Default
true
Live Preview
liveTV.channelPreview
Plays a small live preview of the channel you're on while browsing.
- Values
trueorfalse- Default
true
Open Live TV To
liveTV.defaultView
Whether Live TV opens to what's on now or to the guide.
- Values
- One of these
"onNow": Now"guide": Guide
- Default
"onNow"(Now)
Color Cells by Channel (Older Builds)
liveTV.guideColoredCells · Not in Settings
Retired: the guide has one look now. Kept so older files still read.
- Values
trueorfalse- On import
- Retired. Import reads it so older files still open, and changes nothing.
Default Sort
liveTV.guideSortOrder
The order channels appear in the guide.
- Values
- One of these
"playlist": Playlist Order"name": Name A–Z"nameDescending": Name Z–A"channelNumber": Channel Number"favoritesFirst": Favorites First
- Default
"favoritesFirst"(Favorites First)
Combine Duplicate Channels
liveTV.mergeChannelVariants
Shows a channel your sources list more than once, such as in HD and SD, as one channel.
- Values
trueorfalse- Default
true
Playlist Refresh
liveTV.playlistRefresh
How often your channel lists are fetched again.
- Values
- One of these
"everyLaunch": Every Launch"sixHours": Every 6 Hours"twelveHours": Every 12 Hours"twentyFourHours": Every 24 Hours"manual": Manual Only
- Default
"twelveHours"(Every 12 Hours)
Guide Refresh
liveTV.guideRefresh
How often the program guide is fetched again.
- Values
- One of these
"everyLaunch": Every Launch"sixHours": Every 6 Hours"twelveHours": Every 12 Hours"twentyFourHours": Every 24 Hours"manual": Manual Only
- Default
"twelveHours"(Every 12 Hours)
Content Requests
contentRequests · Your request server and where requests are offered
Your Server
contentRequests.connection · Secret
The request server you connect to and how Vesper signs in to it.
- Values
- A group: the server's kind, address and sign-in
kind: Which request app the server runs. One of these."seerr": Seerr"overseerr": Overseerr"jellyseerr": Jellyseerr
baseURL: The server's web address. Text: a web address.usesAPIKey: On signs in with an API key, off with an account.trueorfalse.email: The account's email, when signing in with one. Text.secret: The API key or the account's password; only in a file that includes secrets. Text.
Show in Context Menus
contentRequests.showInContextMenus
Offers Request in the menu you get by touching and holding a poster.
- Values
trueorfalse- Default
true
Offer When No Streams Found
contentRequests.offerInStreamPicker
Offers to request a title when no version of it is found.
- Values
trueorfalse- Default
true
Automatically Request New Seasons
contentRequests.automaticSeasonRequestsEnabled
Requests a new season of a show you watch on its own.
- Values
trueorfalse- Default
false
Request Timing
contentRequests.automaticSeasonRequestTiming
Whether a new season is requested as soon as it's scheduled or after its finale airs.
- Values
- One of these
"whenScheduled": When It Appears in Coming Soon"afterFinale": After the Season Finale
- Default
"whenScheduled"(When It Appears in Coming Soon)
Include Watchlist Shows
contentRequests.automaticSeasonRequestsIncludeWatchlist
Also requests new seasons of shows on your watchlist that you haven't started.
- Values
trueorfalse- Default
false
Manage Shows
contentRequests.automaticSeasonRequestExcludedShowIDs
Shows that never get automatic season requests, by TMDB show number.
- Values
- A list; each entry is a TMDB show number
- Default
- An empty list
Library
library · Calendar and library display preferences
Calendar View
library.libraryCalendarEnabled
Shows a calendar of upcoming episodes and releases on the Library page.
- Values
trueorfalse- Default
false
Where Your Library Lives
library.personalLibrarySourceMode
Which service keeps your watchlist, history and progress.
- Values
- One of these
"trakt": Trakt"simkl": SIMKL"mdblist": MDBList"wetrakr": WeTrakr"icloud": iCloud
- Default
"icloud"(iCloud)
Library Sync Frequency
library.personalLibrarySyncFrequency
How often your library syncs with that service while Vesper is open, for every library service except Trakt, which follows Trakt Sync Frequency instead.
- Values
- One of these
"on_launch": On Launch"hourly": Hourly"every_6_hours": Every 6 Hours"daily": Daily
- Default
"on_launch"(On Launch)
Appearance
appearance · Background and visual appearance preferences
Watched
appearance.showWatchedMovieBadges
Marks posters of movies you've watched.
- Values
trueorfalse- Default
false
OLED Mode (Older Builds)
appearance.preferTrueBlackBackgrounds · Not in Settings
The on or off switch older builds had for a pure black background; used only when the file has no theme.
- Values
trueorfalse- Default
false
Theme
appearance.theme
How dark Vesper's background is: Pure Black, Midnight or the lighter Twilight.
- Values
- One of these
"pure_black": Pure Black"midnight": Midnight"twilight": Twilight
- Default
"midnight"(Midnight)
Accent
appearance.accent
The color of controls, selections and progress throughout Vesper.
- Values
- One of these
"champagne": Champagne"apricot": Apricot"rose": Rose"lavender": Lavender"mist_blue": Mist Blue"teal": Teal"sage": Sage
- Default
"champagne"(Champagne)
Home Layout
appearance.tvHomeLayout
Whether Apple TV Home shows every row in its own style or one row under a full-screen backdrop.
- Values
- One of these
"shelves": Shelves"spotlight": Spotlight
- Default
"shelves"(Shelves)- Devices
- Apple TV
Top Shelf
appearance.tvTopShelfSource
What Vesper shows in the Apple TV Top Shelf.
- Values
- One of these
"continueWatching": Continue Watching"heroCarousel": Hero Carousel
- Default
"continueWatching"(Continue Watching)- Devices
- Apple TV
Text Size
appearance.tvTextSize
The size of Vesper's text on Apple TV.
- Values
- One of these
"smaller": Smaller"standard": Default"larger": Larger
- Default
"standard"(Default)- Devices
- Apple TV
Opening Sound
appearance.openingSoundEnabled
Plays Vesper's short sound when it opens.
- Values
trueorfalse- Default
false- Devices
- Apple TV
Swipe Between Titles
appearance.tvSwipeBetweenTitles
Lets you swipe left or right on a title's page to move to the next title in its row.
- Values
trueorfalse- Default
true- Devices
- Apple TV
Widget Tap Opens
appearance.widgetTapAction
Whether tapping a title in a Vesper widget opens its details or starts playing it.
- Values
- One of these
"details": Details"play": Play
- Default
"details"(Details)- Devices
- iPhone, iPad and Mac
Poster Style
appearance.posterStyle
Whether posters show the title's key art or a scene from it with its logo.
- Values
- One of these
"standard": Standard"backdrop": Backdrop
- Default
"standard"(Standard)
Badges
appearance.posterBadges
Which details posters show as small badges: the rating, the age rating and the genre.
- Values
- A group: on or off for the rating, age rating and genre badges
showsRating: The rating badge.trueorfalse.showsAgeRating: The age rating badge.trueorfalse.showsGenre: The genre badge.trueorfalse.
- Default
{ "showsAgeRating": false, "showsGenre": false, "showsRating": false }
Notifications
notifications · Release alert timing and delivery preferences
Release Notifications
notifications.releaseNotificationsEnabled
Notifies you when an episode or movie you follow comes out. It needs this device's permission for notifications, which importing a file that turns it on asks for.
- Values
trueorfalse- Default
false
Notification Time
notifications.releaseNotificationHour
The hour of the day release notifications arrive, from 0 for midnight to 23, in this device's own time zone.
- Values
- A whole number from
0to23, in steps of1 - Default
9
Timing
notifications.releaseNotificationTimingMode
Whether episodes notify on their release day at Notification Time or a set time before they air.
- Values
- One of these
"releaseDayAtTime": On release day"minutesBeforeAiring": Before airing
- Default
"releaseDayAtTime"(On release day)
Lead Time
notifications.releaseNotificationLeadMinutes
How many minutes before an episode airs its notification arrives, when Timing is Before airing.
- Values
- A whole number from
0to180minutes, in steps of1. Settings offers0,5,10,15,30,60or120 - Default
15minutes