Applies to OSMC v18.x.
Platforms: Vero 4K, Raspberry Pi 2 and 3.
The following 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 guide is aimed primarily at Vero 4K and Vero 4K+ users, but there is also some discussion about how the Raspberry Pi differs from the Vero 4K. I am not familiar with older Vero devices or the original Apple TV, so I can’t comment on them. I also have no knowledge of the Raspberry Pi 4 - all mentions to “Pi” in here refer to older models.
This guide 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.
Questions and Answers
1) What is a whitelist?
The whitelist is the list of video modes (i.e. 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?
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 some disadvantages. The Kodi GUI isn’t optimised for 4K resolution; 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 “Adjust display refresh rate” to “On start/stop”. This allows Kodi to change its output refresh rate to match the frame rate of the video.
If the GUI is running at 1080p, the same setting allows Kodi to change resolution to 4K (2160p) when playing a 4K video. (Obviously this doesn’t apply to a Raspberry Pi which is not capable of 4K playback).
Now: the standard recommendation is that all users should use this setting, and set the GUI to run at 1080p. If you aren’t using a whitelist, this is recommended; if you are using a whitelist, this setting is essential - without it, the whitelist won’t work correctly.
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.
Secondly, if you have set up a whitelist you get an extra menu in the On Screen Display 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 rare 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.
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 many 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 is preferable.
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 three other settings you may need to change. All are in the Settings>Player>Videos section.
Set “Adjust display refresh rate” to “On start/stop”.
Make sure “Sync playback to display” is NOT selected
You also need to set “Display 4:3 videos as” correctly. Vero 4K users should usually set this to “Use HDMI AVI signalling”, but there are exceptions; for Pi users, it’s more complicated. Either way, see the next section (section 6) for more information.
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: “Stretch 16:9”
The name of this option is misleading: what it does 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 Vero or Pi 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 not a great 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 controls.
Summary: you need to set aspect ratio manually, and use a different approach for SD and HD videos; but if you’re willing to do that, image quality is always optimal.
Option 2: “Normal”
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 image quality.
Summary: good for HD 4:3 videos; 16:9 SD videos are fine; 4:3 SD videos upscaled to HD are okay; SD 4:3 output at native resolution has the correct aspect ratio, but looks significantly worse because of downscaling.
Option 3: “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 by far the best option; every type of video is played with the correct aspect ratio automatically, and nothing suffers from resolution loss.
But some TVs and AVRs 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.
The Best Choice
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; and this option doesn’t exist on the Pi.
“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.
“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, except that it’s often better not to whitelist 1280x720p/59.94 or 1280x720p/60 (see section 10 for more info).
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 may want to de-whitelist 480p and 576p - see section 6.
10) Why shouldn't I 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 widely supported. (Even if the TV could support it, the Vero 4K and Pi can’t output that mode).
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.
Annoyingly, 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 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.
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 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 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.)
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.
Finally it will look for a higher resolution mode whose refresh rate is a multiple of the video frame rate. (Again, 2.5x is acceptable).
If even that fails, it will fall back to using the the Kodi GUI resolution and refresh rate.
(Searching for a higher resolution is a feature that is specific to OSMC - generic Kodi Leia doesn’t do 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?
Yes: one where the resolution is Standard Definition or less, that has a pixel ratio of 1:1 (i.e. the pixels are square, not rectangular), and that has a frame rate of 50, 59.94 or 60fps.
If you try to play one of these 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 - 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.
(See also sections 10 and 11).
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 a bit odd in this mode, as they will still be upscaled to full screen even though the video itself is not.
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) 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).
17) 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; 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:
- 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 modevchanges, fit example - then go ahead. But higher refresh rates make the system look and feel more responsive.)
Set “Adjust display refresh rate” to “On start/stop”.
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:
- Make sure Settings level is set to “Expert” or you won’t be able to access all the settings you need.
- 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 for 1280x720p/59.94Hz and 1280x720p/60Hz. (See sections 10 and 11 for exceptions). Remember to select “OK” to save your changes.
Raspberry Pi users who want to use a whitelist:
- The same settings as for the Vero 4K except that you should set “Display 4:3 videos as” to “Normal”. (See section 6 to understand the trade-offs here).