[HowTo] Guide to the Kodi whitelist function and related settings

Applies to OSMC v18.x.
Platforms: Vero 4K and 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 references 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.

Pi users may also want to de-whitelist 1080p/25: see section 19.

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, 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.)

  • 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, 11 and 19).

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) 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. 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; 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:

Under Settings>System>Display:

  • 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. But higher refresh rates make the system look and feel more responsive, so I wouldn’t recommend setting the refresh rate lower than 50.)

Under Settings>Player>Videos:

  • 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:


  • Make sure Settings level is set to “Expert” or you won’t be able to access all the settings you need.

Under Settings>Player>Videos:

  • Set “Display 4:3 videos as” to “Use HDMI AVI signalling”. (Right for most users, but see section 6).

Under Settings>System>Display:

  • 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.

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 you should set “Display 4:3 videos as” to “Normal” (or possibly to “Stretch 16:9” - see section 6 to understand the trade-offs here); you may also want to de-whitelist 1080p/25 - see section 19 for the reasons why.
19) Why might I not want to whitelist 1080p/25 on a Raspberry Pi?

This is related to a bug in the Pi’s 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), the Pi may select 1080p/25 as its output mode rather than 1080p/50. This would be optimal if the deinterlacing were done correctly; but unfortunately if the deinterlace mode is set to “Auto-select” (the default) the Pi will deinterlace it wrongly (using video-mode rather than film-mode); and converting the result to 1080p/25 can give jerky playback.

If you de-whitelist 1080p/25, this forces 1080p/50 output, which fixes the jerkiness. However, the Pi will still be deinterlacing in video-mode which causes visible resolution loss, especially when the camera is panning. So, in my opinion, the better option is to go into the video menu during playback and set the deinterlacing mode to “Off” - this forces film-mode deinterlacing and gives the best possible output regardless of whether the refresh rate is 50Hz or 25Hz. Leaving 1080p/25 whitelisted can act as a useful reminder to turn deinterlacing off. (Of course, you can de-whitelist 1080p/25 and turn off deinterlacing if you want to).

Most 1080i material requires film-mode deinterlacing, but if the 1080i source is actually video-mode (e.g. a hi-def news broadcast) then setting deinterlacing to Off will give you combing; so if you set deinterlacing to Off for all videos that will work correctly most of the time, but not always.

The Pi has the same problem deinterlacing 1080i/60; so, while you probably won’t experience jerkiness issues (because it won’t try to output 1080p/30) you may still want to set deinterlacing to Off to get the best picture quality.

The Vero 4K also deinterlaces 1080i/50 incorrectly, and in some ways the situation is worse, because there is no work-around to force film-mode. But since the Vero defaults to 1080p/50 output (even if 1080p/25 is whitelisted) the effect is less obvious - you will get the resolution loss, but no jerkiness.


This is great work, thanks! Just a couple of remarks.

Yes there is: VIC 60. Probably rarely supported though.

Note under question 12, I think you have it right but OSMC uses a different scheme than standard Kodi, and Kodi v19 will be different again, allowing more fine-grained selection.

Wording changed.

You mean my four steps are correct, but I should change it to “How does OSMC decide…” rather than “How does Kodi decide…”?

It’s just bullet points 3 and 4. You might like to put at the end of bullet 4 ‘(this search for higher resolutions is unique to OSMC)’

Of course bullet 4 is not final - the final step is it gives up if it fails all the above and reverts to the desktop (GUI) resolution.

Also (picky) ‘exact multiple’ actually includes 2.5x the source framerate so 24fps can play at 60.

Very nice work indeed! :+1:t2:

As an idea: May be worth thinking about splitting this into single posts with a first post acting as a table of contents like I did with the audio wiki article: Connecting up your audio setup & audio settings The main advantage of this: We can always link to certain parts of the wiki article with said post structure. Might be useful to follow this structure with this article as well - not all users may want to read everything or it’s sufficient to just point them to one piece of information. :thinking:

That is currently beyond my editing abilities, but if you mods want to do it for me, knock yourselves out. :grin:

And I may add here: There can be severe disadvantages of doing this although using whitelisting.
A good example for this is my setup. Two reasons why:

  • The first being that my AVR doesn’t listen to the AVI signalling at all - all SD resolutions are handled as 4:3 and if the scaler is set to 16:9 (it can only either be set to 16:9 or 4:3 - don’t ask me why and how that makes any sense) it will then take the 4:3 content and stretch it to 16:9. I’ve even asked the Denon support and their reply was: all SD content is 4:3. Yeah, no. They only seem to look at resolution, nothing else. :rofl:
  • The second reason being how my TV handles 4:3 content. It listens to the AVI signalling properly, but it doesn’t offer any way of disabling overscan with its 4:3 mode, unfortunately.

As my AVR is a fairly recent Denon and my TV is a Panasonic plasma not that uncommon even today (not sure how newer Panas handle 4:3), it might be good to include warnings as to what the issues might be with properly signalled 4:3 SD output. With my setup it’s a better compromise IMHO to output 4:3 SD content pillarboxed (yes, it’s a loss of horizontal resolution) as neither my TV nor my AVR’s scaler can properly handle it the way you’d want them to.

That I could do once there’s time. Only issue: If I’d do this, I’d have to create a new thread with new posts thus loosing your authorship - but I’d surely mention that the original write-up was yours! :slightly_smiling_face:

I’ve redrafted that section a bit - see what you think.

1 Like

I’m not quite sure how to incorporate that. I mean, I can add a note to the effect that “if the equipment you’re connecting to is completely f*cked then this might not work properly” but that’s true of almost anything - it kind of goes without saying.

I suppose I could say a little more than I do about what the setting does, and what effect the other options have.

I agree. Just wanted to bring this up as it could lead to confusion when advocating this setting without more context. From what my equipment does with the signalling, I guess, lots of user equipment will handle this in funny ways. So, further explanation for the other settings might be just what’s needed here - that could include a remark about none of these settings being perfect in every scenario, depending on your setup (goes without saying, but some things can’t be said often enough) :slightly_smiling_face:

Explain how to test and if it fails then point them to the RPi recommend. Add a link to chillbo’s post alternatively?

So basically you want me to take the blame for everything in it but not have the power to edit it? :rofl:

No, if you want to do that, I’m fine with it. :slightly_smiling_face: I put this together as a result of a conversation with @darwindesign in which I was wondering why you guys don’t mention the whitelist and the “Use HDMI AVI Signalling” setting as standard. He said it was partly because there wasn’t actually much documentation about whitelisting, but that if someone were to write some it could maybe be linked to from the bottom of the standard info drop. So I thought I’d have a go at it.

But the purpose of this is to make people more aware of some features that may improve their viewing experience. If the best way for the information to be more widely disseminated is for me to relinquish authorial control, that’s not a problem.

1 Like

I promise I will give that some thought.

I don’t know if you are aware of what Kodi has been doing (slowly) with whitelists. IMHO they never wrote a specification for what they wanted to acheive either back when it started or when they decided it needed improving. I think they have a tendency to just think of kodi running on a PC with lots of grunt to handle a high-res display and a display with very few modes compared to a TV. I suspect whatever they do with v19 we will end up modding it.

Any chance you could mod the existing version a little more? :smiling_imp:

It has never made any sense to me that 720p/23.98 should default to 720p/59.94 instead of 1080p/23.98. And a case could be made for 480p/23.98 defaulting to 1080p/23.98 too, although that’s not quite so clearcut.

Either matching refresh-rate should take precedence over matching resolution (rather than vice versa) or 3:2 pulldown multiples of frame rates shouldn’t be regarded as matching the base frame rate at all.

Well maybe you should get stuck into the conversation at github if what they are proposing doesn’t do what you are after. I think they’ve got some kind of control over the ‘pull-up’ modes.

Then the wider Kodi community might benefit.

What consequences are there (if any) of setting this to 50 Hz? Most European/UK users would probably expect 50 Hz to be the correct setting …

None at all in my experience.

The GUI framerate should be a thing of user preference - while the resolution should typically be 1080p. :+1:t2:

I always avoid 50fps as most Panasonic plasma TVs are not perfect at playing 50fps content (50Hz bug). Whether you set 59.94fps or 60fps is really up to you, I’d say. Have switched to 59.94fps for a while now and it’s quite handy when playing US YT videos a lot - it avoids a framerate switch from GUI to video in these cases. I don’t watch 25fps or 50fps content a lot and setting the GUI to a 24p framerate is quite laggy, so a framerate switch for 24p is more or less unavoidable.

1 Like

The faster the GUI refresh rate is, the more responsive OSMC looks and feels. Slower refresh rates extend the time between when you push a button on the remote and when you actually see the screen update as a result.

The difference between 60Hz and 50Hz isn’t huge, of course, but it’s detectable.

EDIT: Added a note to section 17 saying this is a matter of personal preference.

1 Like