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 categories object; 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 libraryScreen category without libraryRows puts 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
true or false
Default
true

Auto-Play Next Episode

playback.autoPlayNextEpisode

Starts the next episode on its own when one ends.

Values
true or false
Default
true

Automatically Skip Intros

playback.skipTVIntros

Skips an episode's intro once enough community timestamps agree on where it is.

Values
true or false
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
true or false
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
true or false
Default
true

Skip Intro Button

playback.showSkipIntroButton

Shows a Skip button in the player during an intro or recap.

Values
true or false
Default
true

Next Episode Countdown

playback.showNextEpisodeCountdown

Shows a card near the end of an episode that counts down to the next one.

Values
true or false
Default
true

Countdown Starts

playback.nextEpisodeCountdownSeconds

How many seconds before the end of an episode the next-episode card appears.

Values
15, 30, 45, 60 or 90 seconds
Default
30 seconds

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
true or false
Default
true

Gesture Controls

playback.playerBrightnessGesturesEnabled

Swiping up or down on the left side of the player changes the screen brightness.

Values
true or false
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
true or false
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
true or false
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
true or false
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
true or false
Default
true

Show Remaining Time

playback.playerShowRemainingTime

Shows the time left in the video instead of its total length.

Values
true or false
Default
true

Show Intro & Recap Markers

playback.playerShowIntroRecapMarkers

Marks where intros and recaps are on the player's progress bar.

Values
true or false
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
true or false
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
true or false
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
true or false
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
true or false
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
true or false
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
true or false
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
true or false
Default
false

Quick Play

playback.quickPlayContinueWatching

Pressing a Continue Watching card starts playing right away instead of opening the details page.

Values
true or false
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
true or false
Default
true

Share What I'm Watching

playback.discordPresenceEnabled

Shows what this profile is watching on its linked Discord account.

Values
true or false
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
true or false
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
true or false
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
true or false
Default
true

Show Forced Subtitles

subtitles.automaticForcedSubtitles

Shows the forced subtitles a video marks for foreign-language lines while normal subtitles are off.

Values
true or false
Default
true

Show When Muted

subtitles.automaticSubtitlesWhenMuted

Shows subtitles in your preferred language while the built-in player is muted.

Values
true or false
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
true or false
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
true or false
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
true or false
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
true or false
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
true or false
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
true or false
Default
true

Subtitle Search Limit

subtitles.subtitleProviderMaxResults

How many online subtitle results to show for each video.

Values
5, 10, 15 or 25
Default
10

OpenSubtitles

subtitles.enableOpenSubtitles

Includes OpenSubtitles in online subtitle searches.

Values
true or false
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
true or false
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
true or false
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
true or false
Default
true

Dim Subtitles in HDR

subtitles.dimSubtitlesInHDR

Softens subtitle brightness while HDR or Dolby Vision video plays in the built-in player.

Values
true or false
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 from 0.5 to 2.5, in steps of 0.05.
  • bold: Bold text. true or false.
  • italic: Italic text. true or false.
  • 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 from 0 to 1.
    • green: How much green, from 0 to 1. A number from 0 to 1.
    • blue: How much blue, from 0 to 1. A number from 0 to 1.
    • alpha: How opaque, from 0 (see-through) to 1 (solid). A number from 0 to 1.
  • 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 from 0 to 1.
    • green: How much green, from 0 to 1. A number from 0 to 1.
    • blue: How much blue, from 0 to 1. A number from 0 to 1.
    • alpha: How opaque, from 0 (see-through) to 1 (solid). A number from 0 to 1.
  • outlineWidth: How thick the outline around the text is; 0 is none. A number from 0 to 8, in steps of 0.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 from 0 to 1.
    • green: How much green, from 0 to 1. A number from 0 to 1.
    • blue: How much blue, from 0 to 1. A number from 0 to 1.
    • alpha: How opaque, from 0 (see-through) to 1 (solid). A number from 0 to 1.
  • 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 from 0 to 200 points, in steps of 1.
  • leftMargin: Space kept clear on the left, in points. A number from 0 to 200 points, in steps of 1.
  • rightMargin: Space kept clear on the right, in points. A number from 0 to 200 points, in steps of 1.
  • stripEmbeddedStyle: On ignores the fonts and colors a subtitle track brings and uses these instead. true or false.
  • useSystemCaptionStyle: On uses the caption style from the device's Accessibility settings in place of these. true or false.
  • imageSubtitleScale: Size of picture-based subtitles, such as those on Blu-ray discs; 1 is their own size. A number from 0.1 to 2, in steps of 0.05.
  • imageSubtitleOffsetX: Moves picture-based subtitles left or right, in points. A number from -200 to 200 points, in steps of 1.
  • imageSubtitleOffsetY: Moves picture-based subtitles up or down, in points. A number from -200 to 200 points, in steps of 1.
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
true or false
Default
false

Play Trailers with Audio

trailers.trailerAudioEnabled

Starts trailers with sound instead of muted.

Values
true or false
Default
false

Skip for Shows I'm Watching

trailers.skipTrailersForWatchingShows

Doesn't play trailers on the pages of shows you're already watching.

Values
true or false
Default
true

Data Usage

trailers.disableTrailersOnCellular

On means trailers play only on Wi-Fi; off lets them play on cellular data too.

Values
true or false
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
true or false
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
true or false
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 from 4 to 20, in steps of 1.
  • shuffle: Shows the titles in a fresh order. true or false.
  • 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
true or false
Default
false

Coming Soon Row

homeScreen.homeComingSoonRowEnabled

Shows a Coming Soon row with upcoming episodes and releases next to Continue Watching.

Values
true or false
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
true or false
Default
false

Require Dolby Atmos

streams.streamRequireDolbyAtmos

Only versions with Dolby Atmos audio are picked automatically.

Values
true or false
Default
false

Require Dolby Vision

streams.streamRequireDolbyVision

Only versions in Dolby Vision are picked automatically.

Values
true or false
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 0 to 1000 GB
Default
0 GB

Movie Size Limit

streams.streamMovieMaxSizeGB

The largest movie file Auto-Select picks, in GB; 0 means no limit.

Values
A number from 0 to 1000 GB. Settings offers 0, 5, 10, 15, 20, 25, 30, 40, 50, 60, 80 or 100
Default
0 GB

TV Episode Size Limit

streams.streamEpisodeMaxSizeGB

The largest episode file Auto-Select picks, in GB; 0 means no limit.

Values
A number from 0 to 1000 GB. Settings offers 0, 1, 2, 3, 5, 8, 10, 15 or 20
Default
0 GB

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 0 to 1000 GB. Settings offers 0, 1, 2, 3, 5, 8, 10, 15 or 20
Default
0 GB
Devices
iPhone and iPad

Match Connection Speed

streams.streamMatchConnectionSpeed

Skips versions too large for your connection to play smoothly when picking automatically.

Values
true or false
Default
true

Request Timeout

streams.providerTimeout

How long to wait for trailer requests and subtitle downloads, in seconds.

Values
A whole number from 5 to 30 seconds, in steps of 1. Settings offers 5, 10, 15, 20, 25 or 30
Default
20 seconds

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
true or false
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
true or false
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
true or false
Default
false

Prefer 3D Versions

streams.preferStereoStreams · Stays on this device

Ranks 3D versions first on Apple Vision Pro.

Values
true or false
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
true or false
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
true or false
Default
false

Hide Anime

contentRestrictions.hideAnime

Hides anime everywhere in Vesper.

Values
true or false
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
true or false
Default
false

Parents Guide

contentRestrictions.showParentsGuide

Shows a summary of a title's content, such as violence or language, on its page.

Values
true or false
Default
true

Reviews

contentRestrictions.showReviews

Shows reviews on movie and show pages.

Values
true or false
Default
true

Translate Reviews

contentRestrictions.translateReviews

Translates reviews written in another language into yours.

Values
true or false
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
true or false
Default
true

Stay Current

tvShows.stayCurrentEnabled

Opens talk and news shows at their latest episode instead of the next unwatched one.

Values
true or false
Default
true

Hide Unreleased Episodes

tvShows.hideUnreleasedEpisodes

Hides episodes and seasons that haven't aired yet.

Values
true or false
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
true or false
Default
false

Required Submissions

tvShows.introSkipMinimumSubmissionCount

How many community timestamps must agree before an intro or recap is skipped automatically.

Values
1, 2, 3 or 5
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
true or false
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
true or false
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, 25 or 50
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
true or false
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 0 to 1000 GB
Default
20 GB

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 0 to 1000 GB. Settings offers 0, 5, 10, 15, 20, 25, 30, 40, 50, 60, 80 or 100
Default
20 GB

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 0 to 1000 GB. Settings offers 0, 1, 2, 3, 5, 8, 10, 15 or 20
Default
5 GB

Simultaneous Downloads

downloads.downloadMaxConcurrentDownloads · Stays on this device

How many downloads run at the same time.

Values
A whole number from 1 to 3, in steps of 1. Settings offers 1, 2 or 3
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
true or false
Default
false

Episodes Ahead

downloads.smartDownloadsEpisodesAhead · Stays on this device

How many upcoming episodes Smart Downloads keeps ready.

Values
1, 2, 3 or 5
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
true or false
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
true or false
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
true or false
Default
true

Ask Vesper

aiSearch.aiAssistantEnabled

Shows Ask Vesper, which answers questions about what to watch.

Values
true or false
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
true or false
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
true or false
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
true or false
Default
true

Enhanced Anime

metadataSources.useAniListForAnime

Uses AniList for anime episode lists and details.

Values
true or false
Default
true

Enhanced Episodes

metadataSources.useTVDBForEpisodes

Uses TVDB for episode lists and numbering where it's more complete.

Values
true or false
Default
true

Show Rating Icons

metadataSources.ratingSourceIconsEnabled

Shows each rating source's icon next to its rating.

Values
true or false
Default
false

Color-Code Ratings

metadataSources.ratingSourceColorsEnabled

Colors ratings from red to green by how high they are.

Values
true or false
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
true or false
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
true or false
Default
true

Show Library Shortcuts

mediaServers.showMediaServerLibraryShortcuts

Shows shortcuts to your server and share libraries on the Library page.

Values
true or false
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, 720 or 1440
Default
60 minutes

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.

Network Shares

networkShares · WebDAV share addresses and scan folders

Network Shares

networkShares.shares · Secret

Your network shares, such as WebDAV or SMB folders; importing adds shares you don't have yet, and each one asks for its password.

Values
A list; each entry is a network share: its kind, address, user name and folders
Default
An empty list
On import
Adds the file's entries; entries already on the device stay.

Automatic Daily Refresh

networkShares.automaticDailyRefresh

Scans your network shares for new files once a day.

Values
true or false
Default
true

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
true or false
Default
true

Show Channels in Search

liveTV.showChannelsInSearch

Includes Live TV channels in search results.

Values
true or false
Default
true

Live Preview

liveTV.channelPreview

Plays a small live preview of the channel you're on while browsing.

Values
true or false
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
true or false
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
true or false
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. true or false.
  • 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
true or false
Default
true

Offer When No Streams Found

contentRequests.offerInStreamPicker

Offers to request a title when no version of it is found.

Values
true or false
Default
true

Automatically Request New Seasons

contentRequests.automaticSeasonRequestsEnabled

Requests a new season of a show you watch on its own.

Values
true or false
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
true or false
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
true or false
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
true or false
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
true or false
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)

Top Navigation Bar

appearance.tvNavigationStyle

Whether Apple TV shows its sections in a top bar or a sidebar.

Values
One of these
  • "sidebar": Off
  • "top_bar": On
Default
"top_bar" (On)
Devices
Apple TV

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
true or false
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
true or false
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. true or false.
  • showsAgeRating: The age rating badge. true or false.
  • showsGenre: The genre badge. true or false.
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
true or false
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 0 to 23, in steps of 1
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 0 to 180 minutes, in steps of 1. Settings offers 0, 5, 10, 15, 30, 60 or 120
Default
15 minutes