Platforms: Vero 4K and 4K+, Raspberry Pi 2 and 3.
Applies to OSMC v18.x and 19.x
I would like to cover the Pi 4 as well, but I don’t possess one; if others would like to research it for me, feel free!
This is a guide to the Kodi whitelist feature and some related settings, and how to use them to get the best possible image quality.
Feel free to post comments and suggestions below.
This is in question-and-answer format; click/tap on a section to expand it.
This is for users with a Vero 4K or 4K+, or a Raspberry Pi 2 or 3. I am not familiar with older Vero devices or the original Apple TV, so I can’t comment on them. As noted above, I also have no direct knowledge of the Raspberry Pi 4 - all references to “Pi” in here refer to the Pi 2 and 3, unless otherwise specified.
Any time the text refers to “Vero 4K” it also applies to the Vero 4K+.
The text generally assumes that you are using the default OSMC skin. I imagine that the same settings are available in other skins, but the icons and the structure of the menus may be different.
1) What is a whitelist?
The whitelist is the list of video modes (combinations of output resolution and refresh rate) that Kodi is allowed to switch to automatically when playing a video.
2) What happens if I don't set up a whitelist?
Kodi v18 Defaults
With all settings at stock/default values, Kodi runs at a fixed resolution and refresh rate: everything is scaled and/or frame-rate-converted to that one mode.
This has several disadvantages. The Kodi GUI isn’t optimised for 4K resolution, so you shouldn’t set Kodi to run at 4K; but if you set the GUI to run at 1080p then 4K videos will be downscaled. And frame-rate-conversion can reduce viewing quality.
To improve on this, go into Settings>Player>Videos and set the (misleadingly named!) “Adjust display refresh rate” setting to “On start/stop”.
Kodi v19 Defaults
Under Kodi v19, “Settings>Player>Videos>Adjust display refresh rate” is generally set to “On start/stop” by default, but in some releases this option is removed, and instead the setting defaults to “Always”. Either of these options is good; but if it’s available I generally recommend choosing “On start/stop”.
Effect of “On start/stop” or “Always” settings
These settings allow Kodi to change its output refresh rate to match the frame rate of the video; it also allows Kodi to switch the resolution upwards (if there is a more that exactly matches the dimensions of the video). So, if the GUI is running at 1080p, the setting allows Kodi to change resolution up to 4K (2160p) when playing a 4K video. (Obviously this doesn’t apply to a Raspberry Pi which is not capable of 4K playback).
Note: the recommendation is that all users should set “Adjust display refresh rate” to “On start/stop” (if that option is available) or to “Always” (if it is not); and all users should also set the GUI to run at 1080p. Running the UI at 4K can lead to instabilities, so don’t do this. If you aren’t using a whitelist, the “On start/stop” or “Always” setting is recommended; if you are using a whitelist, it is essential - without it, the whitelist won’t work correctly.
- Tip: when Kodi switches output resolution or refresh rate, the screen will usually go black for a few seconds, which means you may miss a little bit of the video. You can prevent that by adding an automatic delay to playback when there’s a mode change. Under Settings / System / Display / General, there’s a setting called “Delay after change of refresh rate”. Set that to however long it takes for the picture to come back up, and you won’t miss anything.
3) How does using a whitelist help?
First, if you don’t use a whitelist, any video that has a resolution of less than 1080p (for example, DVD rips) will be upscaled to 1080p (assuming the Kodi GUI is running at that resolution). If you do use a whitelist then 720p, 576p/i and 480p/i videos can also be output at native resolution. (Section 4 explains why this is desirable).
Secondly, if you have set up a whitelist you get an extra menu in the OSD during playback. (In the default OSMC skin, this is launched from an icon on the far right hand side). This allows you to switch to any whitelisted mode on the fly (and thus override Kodi’s default choice if you don’t like it).
Thirdly, there are some situations where you might want to block Kodi from switching to a specific resolution or refresh rate while still allowing it to use others. The whitelist gives you fine-grained control over which modes Kodi can or can’t use.
Finally, without a whitelist, Kodi will only switch resolutions if the video dimensions exactly match an allowed output resolution. So, for example, if the video is 2560x1440, with no whitelist this will be downscaled to 1080p; with a whitelist active Kodi can upscale it to 4K instead.
4) Why might outputting a video at native resolution improve image quality?
It means it is the TV, not the Vero 4K or the Pi, that does the upscaling.
Almost all TVs can upscale as well as the Vero 4K or Pi can, and most TVs can do it at least a little better.
In addition, if the TV screen is 4K resolution, then without a whitelist a low resolution video is scaled twice: once by Kodi to 1080p and once by the TV from 1080p to 4K. Doing all of the scaling in one step gives better image quality.
5) How do I set up a whitelist?
Look under Settings>System>Display. (You will need to set “Settings level” to “Expert” for the setting to be visible).
When editing the list, Kodi gives you a list of all possible video modes, and you can choose to make each one active or not. Active modes are highlighted; click on one to select or deselect it. (In the standard OSMC skin, with the default colour scheme, active modes are coloured blue, inactive ones are grey).
When you’ve finished editing the list, remember to select “OK” at the bottom of the screen, otherwise the change won’t be saved.
Important: there are some other settings you may need to change, in the Settings>Player>Videos section.
Make sure “Adjust display refresh rate” is set to “On start/stop” if this option is available, or to “Always” if it is not.
Make sure “Sync playback to display” is NOT selected.
You also need to set “Display 4:3 videos as” correctly. Most Vero 4K users should set this to “Use HDMI AVI signalling”, but there are a few exceptions. Pi users running Kodi v19 should probably select “Stretch 16:9”. For Pi users running Kodi v18, it’s more complicated. See the next section (section 6) for more information.
If you are using Kodi v19, please also see section 20 of this guide - there are two new settings.
6) What do the different options for the 'Display 4:3 videos as' setting do?
There are three options for this setting that could make sense.
Option 1: “Normal”
Behaviour on the Pi in Kodi v19
I will freely admit that I don’t entirely understand what this option does on the Pi in Kodi v19, but whatever it’s doing, it definitely isn’t right! On a 4:3 SD video, outputting at native resolution, it seems to shrink the picture in both dimensions. (If the player is upscaling the video to 1080p it works okay).
Behaviour on the Vero 4K or on the Pi in Kodi v18
With this option, Kodi manages aspect ratio by scaling videos differently. 16:9 videos are scaled to fill the screen horizontally; 4:3 videos are scaled to fill three quarters of the screen horizontally, with the rest of the screen filled in black. Kodi always tells the TV that the aspect ratio is 16:9.
This approach works well if the output resolution is 720p or higher. If the output resolution is 576p or 480p, 16:9 videos still look good, but 4:3 videos are horizontally downscaled from 720 pixels wide to 540, and the rest of the screen filled in black. The aspect ratio that you see on the TV is correct, because the TV is still in 16:9 mode and stretches the video back to its correct size; but because the video is downscaled before it is sent to the TV, you lose horizontal resolution in the image, which significantly harms the image quality.
- Summary: a bad idea for Pi users under Kodi v19. On the Pi under v18 or on the Vero: good for HD videos; 16:9 SD videos are fine; 4:3 SD videos upscaled to HD are fine; SD 4:3 output at native resolution has the correct aspect ratio, but looks significantly worse because of downscaling. May still be the best option for Pi users running Kodi v18. (See under “The Best Option” below).
Option 2: “Use HDMI AVI Signalling”
This option is only available on the Vero 4K and not on the Pi.
For HD videos, it works the same way as the “Normal” setting - controlling aspect ratio by scaling. For SD output at native resolution, the video is always output without any downscaling, and the Vero signals the TV to switch aspect ratio between 16:9 and 4:3 as needed.
Assuming your TV (or other equipment) does what it is supposed to do, this is the best option; every type of video is played with the correct aspect ratio automatically, and nothing suffers from resolution loss.
But there are some TVs and AVRs which don’t behave the way they’re supposed to - they may not correctly respond to the signal to switch aspect ratio, or they may misbehave in other ways (e.g. by adding undefeatable overscan when the aspect ratio is 4:3). In this case you may need to use another option.
- Summary: the best option for most Vero 4K users, but some TVs don’t behave the way they should. Not available on the Pi.
Option 3: “Stretch 16:9”
Behaviour on the Pi in Kodi v19
Under Kodi v19, this option (on the Pi) has become more useful. For an SD video, output at SD resolution, it now mirrors the behaviour of the “Use HDMI AVI Signalling” option on the Vero 4K (see previous sub-section) and produces optimal behaviour. Unfortunately, it doesn’t work correctly for HD videos with a 4:3 aspect ratio – these will be stretched horizontally.
Behaviour on the Vero 4K or on the Pi in Kodi v18
The name of this option is misleading: what it does on the Vero 4K (and on the Pi in Kodi v18) is scale all videos horizontally to fit the full width of the screen. If the output mode is 720x576, or 720x480, the effect is the same - the video always fills the full width of the screen. This applies to HD and SD videos.
With this option, the player does not send any signal to the TV to switch aspect ratio, and also doesn’t scale videos to get the aspect ratio correct.
This is a bad choice for HD videos with a 4:3 aspect ratio (e.g. 960x720 or 1440x1080) because these will be horizontally stretched. (You can fix that on a case-by-case basis by going into the OSD during playback, going into the Video Settings menu, and setting the View Mode to Stretch 4:3 for that specific video).
This can be a good option for Standard Definition videos: you’ll always see all of the available picture detail. But for SD videos you will need to change the aspect ratio between 4:3 and 16:9 using the TV’s controls.
- Summary: may well the best option for Pi users under Kodi v19, but only if you don’t watch any HD videos with a 4:3 aspect ratio (or if you do, but you don’t mind manually changing the view mode for those!). Under v18 or on the Vero 4K you will need to set aspect ratio manually, and use different approaches for SD and HD videos; but if you’re willing to do that, image quality is always optimal.
The Best Choice
Vero 4K Users
On the Vero 4K, most users should choose “Use HDMI AVI Signalling”. So long as the equipment you’re connecting to responds the way it should, everything is optimised. But you may need a different option if the TV misbehaves.
Pi Users on Kodi v19
On the Pi under Kodi v19, “Stretch 16:9” is the best setting for SD videos, but it will mess up HD videos with a 4:3 aspect ratio. If you watch many of those then “Normal” might be a better choice.
Pi Users on Kodi v18
On the Pi under Kodi v18, “Stretch 16:9” will give you great picture quality for all videos, but only if you are willing to control the aspect ratio manually, and to do that in completely different ways for SD and HD videos. (Not “family friendly”!) Using “Normal” with 480p and 576p whitelisted works well for HD and for 16:9 SD, but 4:3 SD will look significantly worse because of downscaling. “Normal” with 480p and 576p not whitelisted may also be worth considering: this prevents Kodi from downscaling 4:3 SD, but it means all SD videos will be upscaled by Kodi instead of by the TV, which eliminates much of the benefit of using a whitelist.
7) When editing the whitelist, why are some of the modes listed twice?
This is a bug in Kodi. For now, just select both versions of each mode you want to whitelist.
8) Will Kodi let me whitelist resolutions that my TV doesn't actually support?
Normally Kodi pulls the list of supported modes from the TV or AVR, and only offers you those; so you shouldn’t be offered modes the TV can’t handle.
If you are being offered invalid modes, it could be that an AVR is not returning the correct EDID data from the TV; it could also be due to the presence of an incorrect .kodi/userdata/disp_cap file. On a Raspberry Pi, the presence of an incorrect override RPi config.txt with hdmi_edid_file=1 can also cause this.
9) Which resolutions should I whitelist?
You should usually whitelist every mode your TV supports, with the following exceptions:
Kodi v18 users will want to de-whitelist all 25Hz, 29.97Hz and 30Hz modes. See section 19 for an explanation.
Some users may not want to whitelist 1280x720p/59.94 or 1280x720p/60 (see section 10 for more info). N.B. 1280x720p/50 should be whitelisted if it’s available.
Most users will want to whitelist 720x480p/59.94, but a few might not - see section 11 for more info.
Some Pi users on Kodi v18 may want to de-whitelist 480p and 576p - see section 6, under the “The Best Choice”. (On Kodi v19 you should whitelist them).
10) Why might I not want to whitelist 720p/60 and 720p/59.94?
720p/24 or 720p/23.98 videos are quite common, but 720p/24 and 720p/23.98 are HDMI modes that are not supported. (Even if the TV could support them, the Vero 4K and Pi can’t output those modes).
So, if a video is 720p/23.98, you have to choose between preserving the original refresh rate (by playing at 1080p/23.98) and preserving the original resolution (by playing at 720p/59.94).
Converting from 23.98Hz to 59.94Hz introduces 3:2 pulldown judder, and the majority of users will prefer to avoid judder, even if it means Kodi doing the upscaling. If you whitelist 720p/59.94 and the video is 720p/23.98 then Kodi will play the video at 720p/59.94. So it’s usually better not to whitelist this.
Of course, if you actually watch a lot of 720p/59.94 videos - and PVR users in America may well do that - and especially if you also don’t watch 720p/23.98 (or even if you do but you are not sensitive to 3:2 judder), then by all means do whitelist 720p/59.94.
Similarly, it is usually best not to whitelist 720p/60 - otherwise Kodi will use that mode to play 720p/24 videos. But if you actually watch a lot of 720p/60, then go ahead and whitelist it.
If 720p/50 is available, that should be whitelisted.
Kodi v19 users: there is a new option which may sometimes help - but it’s not always as useful as you might think. Under Settings>System>Display, in the Whitelist section, there is a new checkbox called “Allow 3:2 pulldown refresh rates”. If you uncheck that then you can safely whitelist 720p/59.94 and 720p/60, and Kodi will still output 720p/24 as 1080p/24. However, unchecking this also means that 480p/24 will be upscaled to 1080p/24 instead of being output as 480p/60, which may not be desirable.
11) Why might I not want to whitelist 480p/59.94?
For the same reasons as with 720p (see section 10), if you watch a lot of 480p/23.98 videos, and you never watch 480p/59.94, or 720p/59.94, you may want to de-whitelist 720x480p/59.94 as well as 1280x720p/59.94.
However, 480p/59.94 video is much more common than 720p/59.94 or 720p/60, and you can always manually switch the output to 1080p/23.98 during playback if you want to; so my standard recommendation is to whitelist 480p/59.94 and switch manually if needed.
12) If the whitelist is active, how does OSMC choose which resolution to switch to?
It checks for the following things, in this order.
First it looks for a whitelisted mode whose resolution and refresh rate are an exact match to the video resolution and frame-rate.
If it can’t find one, then it looks for a mode where the resolution matches the video, and the refresh rate is a multiple of the video frame-rate. For example, if the video is 1080p/25 but 1080p/25 is not a whitelisted mode, it will check to see if 1080p/50 is available. (Note that, annoyingly, a “multiple” includes a refresh rate that is 2.5x the video frame rate, so a refresh rate of 60Hz is an acceptable match to a frame rate of 24fps.)
Kodi v19 users: there are two new options which allow extra control. Under Settings>System>Display, in the Whitelist section, there is a new checkbox called “Allow 3:2 pulldown refresh rates” and another called “Allow double refresh rates”. The first, if unchecked, prevents Kodi from converting 24Hz to 60Hz (or 23.98 to 59.94); the second, if unchecked, prevents Kodi from converting 25Hz to 50Hz, or 30Hz to 60Hz.
If it still hasn’t found a match, it then looks for a higher resolution with the correct refresh rate. So, if the video is 1080p/25 and neither 1080p/25 nor 1080p/50 is available, it will check to see if 2160p/25 is an option.
Then it will look for a higher resolution mode whose refresh rate is a multiple of the video frame rate. (Again, 2.5x is acceptable, unless blocked under Kodi v19).
If that fails, it will use the Kodi desktop resolution, matching the refresh rate to the video frame rate if possible, or just using the default refresh rate if not.
(In Kodi v18, searching for a higher resolution with an appropriate refresh rate is a feature that is specific to OSMC - generic Kodi Leia doesn’t do this. But in Kodi v19 standard Kodi also does this.)
13) What if I don't like the mode Kodi switches to?
Either change the resolution manually from the OSD during playback (in the default OSMC skin it’s the icon on the far right of the OSD) or, if Kodi is consistently doing something you don’t like, consider de-whitelisting the resolution it keeps switching to.
14) Is there any type of video where whitelisting can cause problems?
See sections 10, 11 and 19 for some possible examples.
In Kodi v18 there is another type of video that can cause problems (although happily this has been fixed in Kodi v19): if the video resolution is Standard Definition or less, and it has a pixel ratio of 1:1 (i.e. the pixels are square, not rectangular) - for example, a video that is 720x540/25Hz, or 640x480/59.94Hz. If you try to play one of these in Kodi v18 with the output mode set to 480p or 576p, Kodi will probably mess up the aspect ratio; so you’re better off switching to a higher resolution for those.
However, videos like this are quite rare - and even even when you do come across files with those dimensions, they tend to have 24 or 23.98Hz frame rates. So, if you ever watch 720x480 or 720x576 videos (e.g. DVD remuxes) then it’s probably worth whitelisting 576p and 480p anyway and switching resolution by manually if needed.
And, as noted above, this issue is fixed in Kodi v19, so you don’t need to worry about it there.
15) If the video dimensions don't match any whitelisted mode, can you still stop Kodi from scaling?
You can, but you may not want to.
Let’s say you’re playing a video that is 960x540/24Hz. Kodi will play that at 1080p/24. In the OSD, in the Video Settings menu, you can change the View Mode to “Original Size” - the video will then be displayed without any scaling. But of course this means the video doesn’t fill the screen - it is displayed in a 960x540 window with a huge black border round it.
Also, subtitles look odd in this mode, as they will still be upscaled to full screen even though the video itself is not. (IMO this is a bug in Kodi, but no one seems to want to fix it). You can partly work around it by temporarily setting the subtitle position to “bottom of video” and reducing the font size.
Note that you shouldn’t do this with 720x480 videos that have a 4:3 aspect ratio. For some reason Kodi horizontally downscales those to 640x480!
16) Is there anything that can cause Kodi still to do some scaling even when the video is being output at native resolution?
Yes: using Kodi to correct for overscan (in the Video Calibration settings) will cause it do some scaling. If at all possible you should correct overscan using the TV controls instead. (The setting will have different names on different TVs - “1:1” and “Just Scan” are possibilities, but there are others). Leave both overscan settings at the default value - i.e. (0,0) - and leave the Pixel ratio setting set to 1.000.
17) Are there any situations where you CAN output a video at native resolution, but you shouldn't?
See sections 10 and 11 for some examples - matching refresh rate to the video frame rate may be more important than matching resolution.
Additionally, if a video is a 480p/59.94Hz DVD rip, and the material was originally shot on film (as opposed to captured on a TV camera in a studio), then outputting 1080p/23.98 or 2160p/23.98 may look quite good. (But it also may not).
18) Can you summarise the list of recommended settings?
The following is what I would suggest for most users. But I strongly recommend that you read sections 6, 10 and 11 (and Kodi v19 users should also check section 20); these sections go into detail about why these settings might not always be the best choices.
All users, regardless of whether they use a whitelist or not:
- Make sure Settings level is set to “Expert” or you won’t be able to access all the settings you need.
- Set “Resolution” to 1920x1080.
- Set “Refresh Rate” to 60Hz. (This is a matter of personal preference, so if you want to set it to a different value - to avoid some mode changes, for example - then go ahead: either 59.94Hz or 50Hz will also work fine. But higher refresh rates make the system look and feel more responsive, so I definitely don’t recommend setting the refresh rate lower than 50.)
- When Kodi switches output resolution or refresh rate, the screen will usually go black for a few seconds. Set “Delay after change of refresh rate” to however long it takes for the picture to come back up again.
Set “Adjust display refresh rate” to “On start/stop” if the option is available; if not, choose “Always”.
Make sure “Sync playback to display” is NOT selected.
Vero 4K and 4K+ users who want to use a whitelist:
ALL OF THE STANDARD SETTINGS IN THE LIST ABOVE, plus:
- Set “Display 4:3 videos as” to “Use HDMI AVI signalling”. (Right for most users, but see section 6).
Edit the whitelist. Enable every mode that your TV supports, except that Kodi v18 users will probably want to de-whitelist all 25Hz, 29.97Hz, and 30Hz modes - see section 19 for the reasons why - and many users will also want to de-whitelist 1280x720p/59.94Hz and 1280x720p/60Hz (see sections 10 and 11 for discussion - Kodi v19 users also see section 20). Remember to select “OK” to save your changes!
Kodi v19 users should consider checking “Allow 3:2 pulldown refresh rates” (see section 20), and definitely check “Allow double refresh rates”. (These settings don’t exist in Kodi 18).
Under Settings>System>Display>Video calibration…
- The default values in here are fine. You can change Subtitle positioning if you want, but it’s important that you leave all the other settings set to the default (overscan settings to (0,0) and Pixel ratio adjustment to 1.000).
Raspberry Pi users who want to use a whitelist:
- The same settings as for the Vero 4K except that if you are running Kodi v19 you should probably set “Display 4:3 videos as” to “Stretch 16:9”. Pi users running Kodi v18 should set this either to “Normal” or to “Stretch 16:9”. For either Kodi version, see section 6 to understand the trade-offs.
19) Under Kodi v18, why might I not want to whitelist 25Hz, 29.97Hz and 30Hz modes?
This is related to some bugs in Kodi and the way it handles deinterlacing.
If a video is 1080i/50 and flagged as progressive, i.e. it should be deinterlaced in film-mode (weaving) rather than video-mode (motion-adaptive), Kodi may select 1080p/25 as its output mode rather than 1080p/50. This would be optimal if the deinterlacing were done correctly; but unfortunately Kodi will deinterlace it wrongly (using video-mode rather than film-mode); and converting the result of doing that to 1080p/25 gives jerky playback.
If you de-whitelist 1080p/25, this forces 1080p/50 output, which fixes the jerkiness.
You may experience the same issue with 1080i/59.94 material - if it’s output as 1080p/29.97, the result is jerky.
This behaviour should be fixed – or at least worked around – in Kodi v19.
20) What are the changes in Kodi v19?
Section 19 no longer relevant
The stuff discussed in section 19 ceases to be relevant.
Pulldown and Double settings
There are two additional settings under Settings>System>Display, in the Whitelist section. The first is “Allow 3:2 pulldown refresh rates”, and the second is “Allow double refresh rates”.
If you are using a whitelist, the second (“double”) setting will allow Kodi to output (say) 1080p/25 video as 1080p/50, or 1080p/29.97 as 1080p/59.94. The first (“pulldown”) setting allows 23.98fps video to be output as 59.94Hz, or 24fps as 60Hz.
Pretty much all users will want to check the “double” setting.
The “pulldown” setting is more complex. Leaving it unchecked allows you to whitelist 720p/59.94Hz and 720p/60Hz modes but still have 720p/24fps videos output as 1080p/24Hz. That’s probably a good thing. But it also means that 480p/24fps videos will be output as 1080p/24 instead of 480p/60, and that doesn’t look so good. Generally my recommendation is to check this box but de-whitelist 720p/59.94 and 720p/60 modes. However, if you watch a lot of native 720p/60 material (e.g. live TV in the U.S.) you’re better off whitelisting those modes; in that case you may want to uncheck the box, depending on whether you watch more 720p/24 or more 480p/24 material.
“Display 4:3 videos as” Setting For Pi Users
For Pi users, the “Stretch 16:9” option for “Settings / Player / Videos / Display 4:3 videos as” has become more useful than it was in v18 - see section 6 for details. Also, the “Normal” option for that setting has changed its function - what it now does is a little unclear, but it’s definitely not helpful!
And finally, 2D and 3D modes are now listed separately – see the next section.
21) In Kodi v19, what's up with all those TAB and SBS modes?
If you have a 3D TV, under Kodi v19, 2D and 3D modes are listed separately. SBS stands for Side By Side; TAB is Top And Bottom; FP is Frame-Packed. So, for example, 1920x1080@24Hz 2D, 1920x1080@24Hz SBS, 1920x1080@24Hz TAB, and 1920x1080@24Hz FP are all listed as separate modes in the whitelist.
With the exceptions noted in previous sections (e.g. sections 10, 11 and 19) you probably want to whitelist all the modes that are available, 2D and 3D. (If your TV is not 3D-enabled, you won’t see any 3D modes in the menus).