# Vesper settings reference

> Every setting a Vesper settings file can carry, generated from the app.

Canonical page: https://watchvesper.app/settings-reference

The same reference as JSON: https://watchvesper.app/settings-reference.json

224 settings in 21 categories, from Vesper 1.0.2 (26).

## 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

```json
{
  "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

Category key: `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

Category key: `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:

```json
{
  "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

Category key: `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

Category key: `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:

```json
{
  "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

Category key: `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.
- On import: Replaces the device's value; a file that has this category but leaves this key out puts it back to the default.

Default:

```json
[
  {
    "enabled": true,
    "kind": "movieWatchlist"
  },
  {
    "enabled": true,
    "kind": "tvWatchlist"
  },
  {
    "enabled": true,
    "kind": "favorites"
  },
  {
    "enabled": true,
    "kind": "comingSoon"
  },
  {
    "enabled": true,
    "kind": "recentlyReleased"
  },
  {
    "enabled": true,
    "kind": "history"
  }
]
```

## Streams & Sorting

Category key: `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:

```json
[
  {
    "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:

```json
[
  "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

Category key: `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

Category key: `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

Category key: `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

Category key: `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

Category key: `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

Category key: `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

Category key: `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

Category key: `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:

```json
{
  "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

Category key: `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

Category key: `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

Category key: `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

Category key: `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

Category key: `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

Category key: `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:

```json
{
  "showsAgeRating": false,
  "showsGenre": false,
  "showsRating": false
}
```

## Notifications

Category key: `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
