21 Aug 2020 - The wiki is undergoing a major cleanup. If you arrived here from a search engine and cannot find the page, please use the wiki search instead (top right corner of page)
More info can be found on the forum

Add-on settings conversion

From Official Kodi Wiki
Jump to: navigation, search
Home icon grey.png   ▶ Development ▶ Add-on development ▶ Add-on settings conversion

1 Converting addon settings

1.1 Preface

As of Kodi 18 Leia it is possible to write your addon settings in the same setting format as Kodi uses. Due to many initial issues, it is not recommended to convert your settings if your addon is in the Leia addon repo.

In Kodi 19 Matrix, those bugs have been fixed, so we recommend to convert your addon settings if you plan to submit your addon to the Matrix addon repo (or higher).

1.2 Structure

The structure of your settings.xml file should look like this

<?xml version="1.0" ?>
<settings version="1">
	<section id="my.addon.id">
		<category id="general" label="" help="">
			<group id="1" label="">
				<setting id="" type="" label="" help="">
					<control type="" format=""/>
  • The <settings> tag must have a version="1" attribute (or the <section> tag will not be supported)
  • your addon settings file can only have one <section> tag. the id should be the id of your addon. (the use of multiple sections is reserved for kodi's main settings.xml file)
  • you can use multiple <category> tags, just like in the old addon settings format. the id of a category needs to be a string.
  • the <group> tag is a replacement for the old sep and lsep types, you can define multiple groups in order to group a number of settings.

1.3 Level

Similar to Kodi settings, addons can now define a setting level for every setting.
This will show or hide certain settings based on the settings level the user has selected (Basic, Standard, Advanced, Expert).

<setting id="" type="" label="" help="">

The various levels are defined as such:

  • 0 - Basic
  • 1 - Standard
  • 2 - Advanced
  • 3 - Expert
  • 4 - Internal (will never be shown in the GUI)

2 Setting types

2.1 type="text"

<setting type="text" id="test01" label="32001" default=""/>

<setting type="text" id="test02" label="32002" default="" option="hidden"/>

<setting type="text" id="test03" label="32003" default="" option="urlencoded"/>

2.2 type="ipaddress"

<setting type="ipaddress" id="test04" label="32004"/>

2.3 type="number"

<setting type="number" id="test05" label="32005"/>

2.4 type="date"

<setting type="date" id="test06" label="32006" default="2015-03-12"/>

2.5 type="time"

<setting type="time" id="test07" label="32007" default="13:13"/>

2.6 type="bool"

<setting type="bool" id="test08" label="32008" default="false"/>

2.7 type="select"

<setting type="select" id="test09" label="32009" lvalues="11|12|13|14"/>

<setting type="select" id="test10" label="32010" values="aa|bb|cc|dd"/>

2.8 type="addon"

<setting type="addon" id="test11" label="32011" default="" addontype="xbmc.metadata.scraper.movies"/>

<setting type="addon" id="test12" label="32012" default="" addontype="xbmc.metadata.scraper.movies" multiselect="true"/>

2.9 type="enum"

<setting type="enum" id="test13" label="32013" lvalues="11|12|13|14"/>

<setting type="enum" id="test14" label="32014" values="aa|bb|cc|dd"/>

2.10 type="labelenum"

in case you use lvalues in a labelenum control, the saved value will now be the string id, instead of the localized string. please adapt your python code for this.

<setting type="labelenum" id="test15" label="32015" lvalues="11|12|13|14"/>

<setting type="labelenum" id="test16" label="32016" values="bb|aa|dd|cc" sort="yes"/>

2.11 type="slider"

<setting type="slider" id="test17" label="32017" default="20" range="5,5,100" option="int"/>

<setting type="slider" id="test18" label="32018" default="0.5" range="0.0,0.1,1.0" option="float"/>

<setting type="slider" id="test19" label="32019" default="20" range="0,1,100" option="percent"/>

2.12 type="file"

<setting type="file" id="test20" label="32020" default=""/>

2.13 type="audio"

<setting type="audio" id="test21" label="32021" default=""/>

2.14 type="video"

<setting type="video" id="test22" label="32022" default=""/>

2.15 type="image"

<setting type="image" id="test23" label="32023" default=""/>

2.16 type="executable"

<setting type="executable" id="test24" label="32024" default=""/>

2.17 type="folder"

<setting type="folder" id="test25" label="32025" default=""/>

<setting type="folder" id="test26" label="32026" default="" option="writeable"/>

<setting type="folder" id="test27" label="32027" default="" source="videos"/>

<setting type="folder" id="test28" label="32028" default="" source="music"/>

<setting type="folder" id="test29" label="32029" default="" source="pictures"/>

<setting type="folder" id="test30" label="32030" default="" source="programs"/>

<setting type="folder" id="test31" label="32031" default="" source="files"/>

<setting type="folder" id="test32" label="32032" default="" source="local"/>

2.18 type="action"

<setting type="action" id="test33" label="32033" action="RunScript(script.globalsearch)" option="close"/>

<setting type="action" id="test34" label="32034" action="RunScript(weather.yahoo,Location1)" default=""/>

2.19 type="fileenum"

fileenum type settings (which was basically a spincontrol listing all items) are no longer supported. these settings can be converted into a file or folder browser.

<setting type="fileenum" id="test35" label="32035" values="resources"/>

<setting type="fileenum" id="test36" label="32036" values="resources" mask="/"/>

<setting type="fileenum" id="test37" label="32037" values="resources" mask="*.txt"/>

3 Subsetting

if you wish to define a subsetting, you can use the parent attribute with the id of the parent setting as the value.

<setting id="test37" type="path" label="32037" help="" parent="test36">

4 Conditions

4.1 visible

if a setting should always be hidden, you can add this to the setting


if a settings should be conditionallly visible, add a dependencies section to your setting

	<dependency type="visible" setting=""></dependency>

4.2 enable

if a setting should always be disabled, you can add this to the setting


if a settings should be conditionally enabled, add a dependencies section to your setting

	<dependency type="enable" setting=""></dependency>

4.3 eq / lt / gt


compare to a bool value of another setting

	<dependency type="enable" setting="test01">true</dependency>

compare to a int value of another setting

	<dependency type="enable" setting="test01">5</dependency>

compare to a string value of another setting

	<dependency type="enable" setting="test01">something</dependency>


	<dependency type="enable" operator="!is" setting="test01">true</dependency>
	<dependency type="enable" operator="!is" setting="test01">0</dependency>
	<dependency type="enable" operator="!is" setting="test01"></dependency>


	<dependency type="enable" operator="lt" setting="test01">5</dependency>


	<dependency type="enable" operator="gt" setting="test01">0</dependency>

4.4 and / or

multiple dependencies can be defined as such

	<dependency type="enable">
			<condition setting=""></condition>
			<condition setting=""></condition>
	<dependency type="enable">
			<condition setting=""></condition>
			<condition setting=""></condition>