Official Kodi Wiki - User contributions [en]

List of boolean conditions

2021-01-11T23:23:08Z

Lunatixz: /* ListItem */

{{see also|Conditional Visibility}}
<section begin="main content" />
Skins can use boolean conditions with the <visible> tag or with condition attributes. Scripts can read boolean conditions with <code>xbmc.getCondVisibility(condition)</code>.

=== Container ===
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>Container.HasThumb</code>
| Returns true if the current container you are in has a thumb assigned to it
|
|-
| <code>Container.Content(parameter)</code>
| Returns true if the current container you are in contains the following: '''files, songs, artists, albums, movies, tvshows, seasons, episodes, musicvideos, genres, years, actors, playlists, plugins, studios, directors, sets, tags, countries, roles, images''' (Note: these currently only work in the Video and Music Library or unless a Plugin has set the value) also available are '''Addons''' true when a list of add-ons is shown '''LiveTV''' true when a htsp (tvheadend) directory is shown
|
|-
| <code>Container(id).OnNext</code>
| Returns true if the container with id (or current container if id is omitted) is moving to the next item. Allows views to be custom-designed (such as 3D coverviews etc.)
|
|-
| <code>Container(id).OnScrollNext</code>
| Returns true if the container with id (or current container if id is omitted) is scrolling to the next item. Differs from OnNext in that OnNext triggers on movement even if there is no scroll involved.
|
|-
| <code>Container(id).OnPrevious</code>
| Returns true if the container with id (or current container if id is omitted) is moving to the previous item. Allows views to be custom-designed (such as 3D coverviews etc.)
|
|-
| <code>Container(id).OnScrollPrevious</code>
| Returns true if the container with id (or current container if id is omitted) is scrolling to the previous item. Differs from OnPrevious in that OnPrevious triggers on movement even if there is no scroll involved.
|
|-
| <code>Container(id).HasFocus(item_number)</code>
| Returns true if the container with id (or current container if id is omitted) has static content and is focused on the item with id item_number.
|
|-
| <code>Container.HasFiles</code>
| Returns true if the container contains files.
|
|-
| <code>Container.HasFolders</code>
| Returns true if the container contains folders.
|
|-
| <code>Container(id).HasNext</code>
| Returns true if the container or textbox with id (id) has a next page.
|
|-
| <code>Container(id).HasPrevious</code>
| Returns true if the container or textbox with id (id) has a previous page.
|
|-
| <code>Container(id).IsUpdating</code>
| Returns true if the container with [[Dynamic List Content|dynamic list content]] is currently updating.
|
|-
| <code>Container.IsStacked</code>
| Returns true if the container is currently in stacked mode.
|
|-
| <code>Container.CanFilter</code>
| Returns true when the current container can be filtered.
|
|-
| <code>Container.CanFilterAdvanced</code>
| Returns true when advanced filtering can be applied to the current container.
|
|-
| <code>Container.Filtered</code>
| Returns true when a mediafilter is applied to the current container.
|
|-
| <code>Container(id).HasParent</code>
| Return true when the container with id (or current container if id is omitted) contains a parent ('..') item.
|
|-
| <code>Container.SortDirection(ascending)</code>
| Returns true the sort direction of a container is ascending.
|
|-
| <code>Container.SortDirection(descending)</code>
| Returns true the sort direction of a container is descending.
|
|-
| <code>Container(id).Row(row)</code>
| Returns true if the container with id (or current container if id is omitted) is focused on the row given.
|
|-
| <code>Container(id).Column(col)</code>
| Returns true if the container with id (or current container if id is omitted) is focused on the column given.
|
|-
| <code>Container(id).Position(pos)</code>
| Returns true if the container with id (or current container if id is omitted) is focused on the position given.
|
|-
| <code>Container(id).Scrolling</code>
| Returns true if the user is currently scrolling through the container with id (or current container if id is omitted). Note that this is slightly delayed from the actual scroll start. Use Container(id).OnScrollNext/OnScrollPrevious to trigger animations immediately on scroll.
|
|-
| Container(id).SubItem
| Returns true if the container with id (or current container if id is omitted) is focused on the specified subitem.
|
|-
| Container.Sortmethod(id)
| Returns true if the current sort method matches the specified SortID [[https://kodi.wiki/view/List_of_built-in_functions#List_of_sort_methods see list of sort methods]].
|
|}

=== Control ===
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>Control.IsEnabled(id)</code>
| Returns true if the control with id "id" is enabled.
|
|-
| <code>Control.IsVisible(id)</code>
| Returns true if the control with id "id" is visible.
|
|-
| <code>Control.HasFocus(id)</code>
| Returns true if the currently focused control has id "id".
|
|-
| <code>ControlGroup(group).HasFocus(id)</code>
| Returns true if the control group with id “group” has control id “id” as it's focused item. If “id” is not present, or is 0, then it will return true if the currently focused control is in the control group with id “group”. Note that if the control group with id “group” does not have focus, then this will still return true if the last focused item in the group had control id “id”.
|
|}

=== Integer ===
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>Integer.IsEqual([[InfoLabels|info]],number)</code>
| Returns true if the value of the [[InfoLabels|infolabel]] is equal to the supplied number. Example: Integer.IsEqual(ListItem.Year,2000)
| {{nowrap|v17 Addition}}
|-
| <code>Integer.IsEven([[InfoLabels|info]])</code>
| Returns true if the value of the [[InfoLabels|infolabel]] is even. Example: Integer.IsEven(ListItem.CurrentItem)
| {{nowrap|v19 Addition}}
|-
| <code>Integer.IsGreater([[InfoLabels|info]],number)</code>
| Returns true if the value of the [[InfoLabels|infolabel]] is greater than to the supplied number. Example: Integer.IsGreater(ListItem.Year,2000)
| {{nowrap|v17 Addition}}
|-
| <code>Integer.IsGreaterOrEqual([[InfoLabels|info]],number)</code>
| Returns true if the value of the [[InfoLabels|infolabel]] is greater or equal to the supplied number. Example: Integer.IsGreaterOrEqual(ListItem.Year,2000)
| {{nowrap|v17 Addition}}
|-
| <code>Integer.IsLess([[InfoLabels|info]],number)</code>
| Returns true if the value of the [[InfoLabels|infolabel]] is less than the supplied number. Example: Integer.IsLess(ListItem.Year,2000)
| {{nowrap|v17 Addition}}
|-
| <code>Integer.IsLessOrEqual([[InfoLabels|info]],number)</code>
| Returns true if the value of the [[InfoLabels|infolabel]] is less or equal to the supplied number. Example: Integer.IsLessOrEqual(ListItem.Year,2000)
| {{nowrap|v17 Addition}}
|-
| <code>Integer.IsOdd([[InfoLabels|info]])</code>
| Returns true if the value of the [[InfoLabels|infolabel]] is odd. Example: Integer.IsOdd(ListItem.CurrentItem)
| {{nowrap|v19 Addition}}
|}

=== Library ===
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>Library.HasContent(string)</code>
| Returns true if the Kodi libraries have the content from string. Valid Strings are (Video, Music, Movies, TVShows, MusicVideos, MovieSets, BoxSets)
|
|-
| <code>Library.IsScanningMusic</code>
| Returns true if the music library is being updated
|
|-
| <code>Library.IsScanningVideo</code>
| Returns true if the video library is being updated
|
|-
| <code>Library.HasContent(Role, Composer)</code>
| Tag can be Composer, Conductor, Orchestra, Lyricist, Remixer, Arranger, Engineer, Producer, DJMixer or Mixer. Returns true if there are any artists with that role in the library
| v17 addition
|-
| <code>Library.HasNode(path)</code>
| Returns True if the specified node is available (example: Library.HasNode(library://video/movies/titles.xml))
| v19 addition
|}

=== ListItem ===
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>ListItem.IsFolder</code>
| Returns whether the current ListItem is a folder
|
|-
| <code>ListItem.IsPlaying</code>
| Returns whether the current ListItem.* [[InfoLabels|info labels]] and images are currently Playing media
|
|-
| <code>ListItem.IsResumable</code>
| Returns true when the current ListItem has been partially played
|
|-
| <code>ListItem.IsCollection</code>
| Returns true when the current ListItem is a movie set
|
|-
| <code>ListItem.IsSelected</code>
| Returns whether the current ListItem is selected (f.e. currently playing in playlist window)
|
|-
| <code>ListItem.HasArchive</code>
| returns True when the selected channel has a server-side back buffer (PVR)
| v19 addition
|-
| <code>ListItem.HasEpg</code>
| Returns true when the selected programme has epg info (PVR)
|
|-
| <code>ListItem.HasReminder</code>
| returns True if the item has a reminder set (PVR)
| v19 addition
|-
| <code>ListItem.HasReminderRule</code>
| returns True if the item was scheduled by a reminder timer rule (PVR)
| v19 addition
|-
| <code>ListItem.HasTimer</code>
| Returns true when a recording timer has been set for the selected programme (PVR)
|
|-
| <code>ListItem.IsRecording</code>
| Returns true when the selected programme is being recorded (PVR)
|
|-
| <code>ListItem.IsEncrypted</code>
| Returns true when the selected programme is encrypted (PVR)
|
|-
| <code>ListItem.IsStereoscopic</code>
| Returns true when the selected video is a 3D (stereoscopic) video
|
|-
| <code>ListItem.Property(IsSpecial)</code>
| Returns whether the current Season/Episode is a Special
|
|-
| <code>ListItem.Property(DateLabel)</code>
| Can be used in the rulerlayout of the epggrid control. Will return true if the item is a date label, returns false if the item is a time label.
|
|-
| <code>ListItem.Property(Addon.IsEnabled)</code>
| Returns true when the selected addon is enabled (for use in the addon info dialog only).
|
|-
| <code>ListItem.Property(Addon.IsInstalled)</code>
| Returns true when the selected addon is installed (for use in the addon info dialog only).
|
|-
| <code>ListItem.Property(Addon.HasUpdate)</code>
| Returns true when there's an update available for the selected addon.
|
|-
| <code>ListItem.HasTimerSchedule</code>
| Whether the item is part of a repeating timer schedule (PVR).
| v16 addition
|-
| <code>ListItem.TimerHasError</code>
| Whether the item has a timer and it won't be recorded because of an error (PVR).
| v17 addition
|-
| <code>ListItem.TimerHasConflict</code>
| Whether the item has a timer and it won't be recorded because of a conflict (PVR).
| v17 addition
|-
| <code>ListItem.TimerIsActive</code>
| Whether the item has a timer that will be recorded, i.e. the timer is enabled (PVR).
| v17 addition
|-
| <code>ListItem.Property(Addon.Orphaned)</code>
| Returns true if the slected addon is orphaned (not needed anymore by any other addon)
| v17 addition
|-
| <code>ListItem.IsParentFolder</code>
| Returns true is the slected item is the 'up' item
| v17 addition
|-
| <code>ListItem.IsNew</code>
| [PVR] will return true if the item is a premiere (for example, a Live TV show that will be first aired).
| v19 addition
|-
| <code>ListItem.IsPlayable</code>
| Returns True when the selected programme can be played (PVR)
| v19 addition
|-
| <code>ListItem.IsBoxset</code>
| Returns True if the item is part of a boxset album
| v19 addition
|-
| <code>ListItem.IsPremiere</code>
| Returns true if the item is a premiere (for example, a Movie first showing or season first on Live TV)
| v19 addition
|-
| <code>ListItem.IsFinale</code>
| Returns true if the item is a finale (for example, a season finale showing on Live TV)
| v19 addition
|-
| <code>ListItem.IsLive</code>
| Returns true if the item is live (for example, a Live TV sports event)
| v19 addition
|-
| <code>ListItem.Property(Addon.IsFromOfficialRepo)</code>
| Returns true if the addon is from an official repository
| v19 addition
|-
| <code>ListItem.Property(Addon.IsBinary)</code>
| Returns true for binary addons
| v19 addition
|-
| <code>ListItem.Property(Addon.IsUpdate)</code>
| Returns True if this add-on is a valid update of an installed outdated add-on
| v19 addition
|-
| <code>ListItem.IsAutoUpdateable</code>
| Returns True if this add-on can be updated automatically
| v19 addition
|}

=== Player ===
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>Player.HasMedia</code>
| Returns true if the player has an audio or video file.
|
|-
| <code>Player.HasAudio</code>
| Returns true if the player has an audio file.
|
|-
| <code>Player.HasDuration</code>
| Returns true if Media isn't a true stream
|
|-
| <code>Player.HasVideo</code>
| Returns true if the player has a video file.
|
|-
| <code>Player.Passthrough</code>
| Returns true if the player is using audio passthrough.
|
|-
| <code>Player.Playing</code>
| Returns true if the player is currently playing (ie not ffwding, rewinding or paused.)
|
|-
| <code>Player.Paused</code>
| Returns true if the player is paused.
|
|-
| <code>Player.Forwarding</code>
| Returns true if the player is fast forwarding.
|
|-
| <code>Player.Forwarding2x</code>
| Returns true if the player is fast forwarding at 2x.
|
|-
| <code>Player.Forwarding4x</code>
| Returns true if the player is fast forwarding at 4x.
|
|-
| <code>Player.Forwarding8x</code>
| Returns true if the player is fast forwarding at 8x.
|
|-
| <code>Player.Forwarding16x</code>
| Returns true if the player is fast forwarding at 16x.
|
|-
| <code>Player.Forwarding32x</code>
| Returns true if the player is fast forwarding at 32x.
|
|-
| <code>Player.Rewinding</code>
| Returns true if the player is rewinding.
|
|-
| <code>Player.Rewinding2x</code>
| Returns true if the player is rewinding at 2x.
|
|-
| <code>Player.Rewinding4x</code>
| Returns true if the player is rewinding at 4x.
|
|-
| <code>Player.Rewinding8x</code>
| Returns true if the player is rewinding at 8x.
|
|-
| <code>Player.Rewinding16x</code>
| Returns true if the player is rewinding at 16x.
|
|-
| <code>Player.Rewinding32x</code>
| Returns true if the player is rewinding at 32x.
|
|-
| <code>Player.PauseEnabled</code>
| Returns true if the currently playing stream can be paused.
|
|-
| <code>Player.Caching</code>
| Returns true if the player is current re-caching data (internet based video playback).
|
|-
| <code>Player.DisplayAfterSeek</code>
| Returns true for the first 2.5 seconds after a seek.
|
|-
| <code>Player.Seeking</code>
| Returns true if a seek is in progress
|
|-
| <code>Player.SeekEnabled</code>
| Returns true if player can seek
|
|-
| <code>Player.ShowTime</code>
| Returns true if the user has requested the time to show (occurs in video fullscreen)
|
|-
| <code>Player.ShowInfo</code>
| Returns true if the user has requested the song info to show (occurs in visualisation fullscreen and slideshow)
|
|-
| <code>Player.IsInternetStream</code>
| Returns true if the player is playing an internet stream.
|
|-
| <code>Player.Muted</code>
| Returns true if the volume is muted.
|
|-
| <code>Player.Process(videohwdecoder)</code>
| Returns true if the currently playing video is decoded in hardware
| v17 addition
|-
| <code>Player.TempoEnabled</code>
| Returns true if the current player supports changing the playback speed
| v17 addition
|-
| <code>Player.IsTempo</code>
| Returns true if the current playbackspeed is not equal to 1
| v17 addition
|-
| <code>Player.HasGame</code>
| Returns true if the player is playing a game
| v18
|-
| <code>Player.HasResolutions</code>
| Returns true when multiple resolutions are available
| v18
|-
| <code>Player.FrameAdvance</code>
| Returns true if player is in frame advance mode
| v18
|-
| <code>Player.ChannelPreviewActive</code>
| Returns true if PVR channel preview is active (used channel tag different from played tag)
|
|}

==== MusicPlayer ====
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>MusicPlayer.HasNext</code>
| Returns true if the music player has a next song queued in the Playlist.
|
|-
| <code>MusicPlayer.HasPrevious</code>
| Returns true if the music player has a a Previous Song in the Playlist .
|
|-
| <code>MusicPlayer.Offset(number).Exists</code>
| Returns true if the music players playlist has a song queued in position (number).
|
|-
| <code>MusicPlayer.Content(parameter)</code>
| Returns true if the current audio you are playing matches the specified content. The following values are accepted: files, livetv
|
|-
| <code>MusicPartyMode.Enabled</code>
| Returns true if Party Mode is enabled
|
|-
|<code>MusicPlayer.IsMultiDisc</code>
| Returns true if the current album consists of two or more discs
| v19 addition
|}

==== VideoPlayer ====
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>VideoPlayer.UsingOverlays</code>
| Returns true if the video player is using the hardware overlays render method. Useful, as with hardware overlays you have no alpha blending to the video image, so shadows etc. need redoing, or disabling.
|
|-
| <code>VideoPlayer.IsFullscreen</code>
| Returns true if the video player is in fullscreen mode.
|
|-
| <code>VideoPlayer.HasMenu</code>
| Returns true if the video player has a menu (ie is playing a DVD)
|
|-
| <code>VideoPlayer.HasInfo</code>
| Returns true if the current playing video has information from the library or from a plugin (eg director/plot etc.)
|
|-
| <code>VideoPlayer.Content(parameter)</code>
| Returns true if the current Video you are playing is contained in corresponding Video Library sections. The following values are accepted : files, movies, episodes, musicvideos, livetv
|
|-
| <code>VideoPlayer.HasSubtitles</code>
| Returns true if there are subtitles available for video. (available for version 11.0 and above)
|
|-
| <code>VideoPlayer.IsStereoscopic</code>
| Returns true when the currently playing video is a 3D (stereoscopic) video
|
|-
| <code>VideoPlayer.SubtitlesEnabled</code>
| Returns true if subtitles are turned on for video. (available for version 11.0 and above)
|
|-
| <code>VideoPlayer.HasEpg</code>
| Returns true when epg information is available for the currently playing programme (PVR).
|
|-
| <code>VideoPlayer.HasTeletext</code>
| Returns true when teletext is available.
|
|}

=== PlayList ===
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>Playlist.IsRandom</code>
| Returns true if the player is in random mode.
|
|-
| <code>Playlist.IsRepeat</code>
| Returns true if the player is in repeat all mode.
|
|-
| <code>Playlist.IsRepeatOne</code>
| Returns true if the player is in repeat one mode.
|
|}

=== PVR ===
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>Pvr.HasTimer</code>
| Returns true when a recording timer is active.
|
|-
| <code>Pvr.HasNonRecordingTimer</code>
| Returns true when a non recording timer is active.
|
|-
| <code>Pvr.HasTVChannels</code>
| Returns true if there are tv channels available
|
|-
| <code>Pvr.HasRadioChannels</code>
| Returns true if there are radio channels available
|
|-
| <code>Pvr.IsPlayingTv</code>
| Returns true when live tv is being watched.
|
|-
| <code>Pvr.IsPlayingRadio</code>
| Returns true when live radio is being listened to.
|
|-
| <code>Pvr.IsPlayingRecording</code>
| Returns true when a recording is being watched.
|
|-
| <code>Pvr.IsRecording</code>
| Returns true when the system is recording a tv programme.
|
|-
| <code>Pvr.IsTimeShift</code>
| Returns true when the playback is timeshifted.
|
|-
| <code>Pvr.ActStreamIsEncrypted</code>
| Returns true if the stream is encrypted
|
|-
| <code>Pvr.RadioNextRecordingChannelIcon</code>
| Icon of the next recording radio channel
| {{nowrap|v17 Addition}}
|-
| <code>Pvr.IsRecordingTV</code>
| Returns true when the system is recording a tv programme.
| {{nowrap|v17 Addition}}
|-
| <code>Pvr.HasTVTimer</code>
| Returns true if at least one tv timer is active.
| {{nowrap|v17 Addition}}
|-
| <code>Pvr.HasNonRecordingTVTimer</code>
| Returns true if there are tv timers present who currently not do recording
| {{nowrap|v17 Addition}}
|-
| <code>Pvr.IsRecordingRadio</code>
| Returns true when the system is recording a radio programme.
| {{nowrap|v17 Addition}}
|-
| <code>Pvr.HasRadioTimer</code>
| Returns true if at least one radio timer is active.
| {{nowrap|v17 Addition}}
|-
| <code>Pvr.HasNonRecordingRadioTimer</code>
| Returns true if there are radio timers present who currently not do recording
| {{nowrap|v17 Addition}}
|
|-
| <code>Pvr.CanRecordPlayingChannel</code>
| Returns true if the player can record the current internet stream.
| {{nowrap|v18 Addition}}
|-
| <code>Pvr.IsRecordingPlayingChannel</code>
| Returns true if the player is recording the current internet stream.
| {{nowrap|v18 Addition}}
|-
| <code>Pvr.IsPlayingActiveRecording</code>
| Returns true when Kodi is currently playing a recording that is in progress.
| {{nowrap|v19 Addition}}
|}

=== RDS ===
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>RDS.HasRds</code>
| Returns true if RDS is present
|
|-
| <code>RDS.HasRadioText</code>
| Returns true if RDS contains also Radiotext
|
|-
| <code>RDS.HasRadioTextPlus</code>
| Returns true if RDS with Radiotext contains also the plus information
|
|-
| <code>RDS.HasHotline</code>
| Returns true if a hotline phone number is present (Only be available on RadiotextPlus)
|
|-
| <code>RDS.HasStudio</code>
| Returns true if a studio name is present (Only be available on RadiotextPlus)
|
|}

=== Skin ===
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>Skin.HasTheme(theme)</code>
| Returns true if the user has selected the theme with name ?theme?.
|
|-
| <code>Skin.HasSetting(setting)</code>
| Returns the state of the skin-specified setting ?setting?. You can toggle a setting from a button by using <onclick>Skin.ToggleSetting(setting)</onclick>.
|
|-
| <code>Skin.String(string)</code>
| Returns whether the skin string (set via Skin.SetString, Skin.SetPath, or Skin.SetImage) is non-empty.
|
|-
| <code>Skin.String(string1,string2)</code>
| Same as String.IsEqual(Skin.String(string1),string2). Returns true if Skin.String(string1) equals string2.
|
|}

=== SlideShow ===
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>Slideshow.IsActive</code>
| Returns true if the picture slideshow is running
|
|-
| <code>Slideshow.IsPaused</code>
| Returns true if the picture slideshow is paused
|
|-
| <code>Slideshow.IsRandom</code>
| Returns true if the picture slideshow is in random mode
|
|-
| <code>Slideshow.IsVideo</code>
| Returns true if the picture slideshow is playing a video
|
|}

=== String ===
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>String.IsEmpty([[InfoLabels|info]])</code>
| Returns true if the [[InfoLabels|info]] is empty. Example of info: ListItem.Title, ListItem.Genre. Please note that string can also be a $LOCALIZE[]. Also note that in a panelview or similar this only works on the focused item.
| {{nowrap|v17 Addition}}
|-
| <code>String.IsEqual([[InfoLabels|info]],string)</code>
| Returns true if the [[InfoLabels|info]] is equal to the given string. Example of info: ListItem.Title, ListItem.Genre. Please note that string can also be a $LOCALIZE[] or [[InfoLabels|info label]] (without $INFO prefix). Also note that in a panelview or similar this only works on the focused item.
| {{nowrap|v17 Addition}}
|-
| <code>String.StartsWith([[InfoLabels|info]],substring)</code>
| Returns true if the [[InfoLabels|info]] starts with the given substring. Example of info: ListItem.Title, ListItem.Genre. Please note that string can also be a $LOCALIZE[] or [[InfoLabels|info label]] (without $INFO prefix). Also note that in a panelview or similar this only works on the focused item.
| {{nowrap|v17 Addition}}
|-
| <code>String.EndsWith([[InfoLabels|info]],substring)</code>
| Returns true if the [[InfoLabels|info]] ends with the given substring. Example of info: ListItem.Title, ListItem.Genre. Please note that string can also be a $LOCALIZE[] or [[InfoLabels|info label]] (without $INFO prefix). Also note that in a panelview or similar this only works on the focused item.
| {{nowrap|v17 Addition}}
|-
| <code>String.Contains([[InfoLabels|info]],substring)</code>
| Returns true if the [[InfoLabels|info]] contains the given substring. Example of info: ListItem.Title, ListItem.Genre. Please note that string can also be a $LOCALIZE[] or [[InfoLabels|info label]] (without $INFO prefix). Also note that in a panelview or similar this only works on the focused item.
| {{nowrap|v17 Addition}}
|}

=== System ===
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>System.AddonIsEnabled(id)</code>
| Returns true if the specified addon is enabled on the system
| v19 addition
|-
| <code>System.HasAddon(id)</code>
| Returns true if the specified addon is installed on the system.
|
|-
| <code>System.HasPVRAddon</code>
| Returns true if at least one PVR addon is installed on the system.
|
|-
| <code>System.HasAlarm(alarm)</code>
| Returns true if the system has the ?alarm? alarm set.
|
|-
| <code>System.AlarmLessOrEqual(alarmname,seconds)</code>
| Returns true if the alarm with ?alarmname? has less or equal to ?seconds? left. Standard use would be system.alarmlessorequal(shutdowntimer,119), which would return true when the shutdowntimer has less then 2 minutes left.
|
|-
| <code>System.HasNetwork</code>
| Returns true if the ethernet cable is plugged in.
|
|-
| <code>System.HasMediadvd</code>
| Returns true if there is a CD or DVD in the DVD-ROM drive.
|
|-
| <code>System.HasMediaAudioCD</code>
| Returns true if there is an audio CD in the optical drive. False if no drive available, empty drive or other medium.
| v18 Addition
|-
| <code>System.IdleTime(time)</code>
| Returns true if Kodi has had no input for ?time? amount of seconds.
|
|-
| <code>System.IsStandalone</code>
| Returns true if Kodi is running in standalone mode.
|
|-
| <code>System.IsFullscreen</code>
| Returns true if Kodi is running fullscreen.
|
|-
| <code>System.IsLoggedOn</code>
| Returns true if a user is currently logged on under a [[Profiles|profile]]
|
|-
| <code>System.HasLoginScreen</code>
| Returns true if the [[Profiles|profile]] login screen is enabled
|
|-
| <code>System.HasActiveModalDialog</code>
| Returns true true when a modal dialog is active, disregarding any animations (Leia (v18) and newer versions)
| v18
|-
| <code>System.HasVisibleModalDialog</code>
| Returns true if a modal dialog is visible, eg when the animations are finished (Leia (v18) and newer versions)
| v18
|-
| <code>System.Time(startTime,endTime)</code>
| Returns true if the current system time is >= startTime and < endTime. endTime is optional. Time must be specified in the format HH:mm, using a 24 hour clock.
|
|-
| <code>System.Date(startDate,endDate)</code>
| Returns true if the current system date is >= startDate and < endDate. endDate is optional. Date must be specified in the format MM-DD.
|
|-
| <code>System.Platform.Linux</code>
| Returns true if Kodi is running on a linux/unix based computer.
|
|-
| <code>System.Platform.Windows</code>
| Returns true if Kodi is running on a windows based computer.
|
|-
| <code>System.Platform.OSX</code>
| Returns true if Kodi is running on an OSX based computer.
|
|-
| <code>System.Platform.IOS</code>
| Returns true if Kodi is running on an IOS device.
|
|-
| <code>System.Platform.Darwin</code>
| Returns true if Kodi is running on an OSX or IOS system.
|
|-
| <code>System.Platform.Android</code>
| Returns true if Kodi is running on an android device.
|
|-
| <code>System.Platform.UWP</code>
| Returns true if Kodi is running on Universal Windows Platform (UWP).
| {{nowrap|v18 Addition}}
|-
| <code>System.CanPowerDown</code>
| Returns true if Kodi can powerdown the system.
|
|-
| <code>System.CanSuspend</code>
| Returns true if Kodi can suspend the system.
|
|-
| <code>System.CanHibernate</code>
| Returns true if Kodi can hibernate the system.
|
|-
| <code>System.HasHiddenInput</code>
| Return true when to osd keyboard/numeric dialog requests a password/pincode.
|
|-
| <code>System.CanReboot</code>
| Returns true if Kodi can reboot the system.
|
|-
| <code>System.ScreenSaverActive</code>
| Returns true if ScreenSaver is active.
|
|-
| <code>System.Setting(hidewatched)</code>
| Returns true if 'hide watched items' is selected.
|
|-
| <code>System.IsInhibit</code>
| Returns true when shutdown on idle is disabled.
|
|-
| <code>System.HasShutdown</code>
| Returns true when shutdown on idle is enabled.
|
|-
| <code>System.HasCMS</code>
| Returns true if colour management is supported in Kodi.
| {{nowrap|v17 Addition}}
|-
| <code>System.GetBool(boolean)</code>
| Returns the value of any standard system boolean setting. Will not work with settings in advancedsettings.xml
|
|-
| <code>System.HasLocks</code>
| Returns true if the profile has lock preferences configured
|
|-
| <code>System.IsMaster</code>
| Returns true if the profile has entered the master mode
|
|-
| <code>System.SupportsCPUUsage</code>
| Return True if the system provides CPU info
| {{nowrap|v19 Addition}}
|}

=== Visualisation ===
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>Visualisation.Enabled</code>
| Returns true if any visualisation has been set in settings (so not None).
|
|-
| <code>Visualisation.HasPresets</code>
| Returns true if the visualisation has built in presets.
|
|-
| <code>Visualisation.Locked</code>
| Returns true if the current visualisation preset is locked (eg in Milkdrop.)
|
|}

=== Weather ===
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>Weather.IsFetched</code>
| Returns true if the weather data has been downloaded.
|
|}

=== Window ===
{| class="prettytable" width="100%"
! InfoLabels
! style="80%" | Definition
! Version
|-
| <code>Window.IsVisible(window)</code>
| Returns true if the window is visible (includes fade out time on dialogs)
|
|-
| <code>Window.IsActive(window)</code>
| Returns true if the window with id or title ?window? is active (excludes fade out time on dialogs) [[Window IDs|See here for a list of windows]]
|
|-
| <code>Window.IsTopMost(window)</code>
| Returns true if the window with id or title ?window? is on top of the window stack (excludes fade out time on dialogs) [[Window IDs|See here for a list of windows]]
|
|-
| <code>Window.IsMedia</code>
| Returns true if this window is a media window (programs, music, video, scripts, pictures)
|
|-
| <code>Window.Next(window)</code>
| Returns true if the window with id or title ?window? is being moved to. [[Window IDs|See here for a list of windows]]. Only valid while windows are changing.
|
|-
| <code>Window.Previous(window)</code>
| Returns true if the window with id or title ?window? is being moved from. [[Window IDs|See here for a list of windows]]. Only valid while windows are changing.
|
|-
| <code>Window.Property(IsRadio)</code>
| Returns true if the window is a radio window (for use in the PVR windows)
|-
| <code>Window.Is(name)</code>
| Useful in xml files that are shared between multiple windows/dialogs. Will return true if the window with the given name is visible
| v17 addition
|}
<section end="main content" />

== See also ==
'''Development:'''
* [[Add-on development]]
* [[Skinning]]

[[Category:Skin development]]
[[Category:Add-on development]]

Addon.xml

2018-02-27T21:16:09Z

Lunatixz:

{{mininav|[[Development]]|[[Add-on development]]}}
 

Every skin, script, or plugin in Kodi contains an <code>addon.xml</code> file which describes the add-on, providing credits, version information and dependencies. Below, we will explain how this file is structured and which elements must be used to create an add-on for Kodi. You can also consult the examples at the end to see how this file is laid out depending on if you are developing a skin or script.

Every <code>addon.xml</code> file has the same basic structure, this example is for a video plugin:

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_GB">Your add-on's summary</summary>
<description lang="en_GB">Your add-on's description</description>
<disclaimer lang="en_GB"></disclaimer>
<language></language>
<platform>all</platform>
<license></license>
<forum></forum>
<website></website>
<email></email>
<source></source>
<news></news>
<assets>
<icon></icon>
<fanart></fanart>
<banner></banner>
<clearlogo></clearlogo>
<screenshot></screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

There are a few important things to note in the above sample:

* The <code><addon></code> element must be present, and be the root node. It presents data about the add-on package as a whole.
* Inside the <code><addon></code> element is a <code><requires></code> element, listing all the dependencies that this add-on needs in order to function.
* Then there are one or more <code><extension></code> elements, each of which describes a part of Kodi that the add-on extends.
* Finally, there is a specific <code><extension></code> element that extends <code>"xbmc.addon.metadata"</code>. This describes the add-on to the user.
* Banners and clearlogos assets exclusive to Kodi v.18+
= Elements =

== <addon> ==

The <code><addon></code> element has 4 attributes, all required: <code>id</code>, <code>version</code>, <code>name</code>, and <code>provider-name</code>. For example:

<source lang="xml">
<addon id="script.hello.world" name="Hello World" version="0.0.1" provider-name="Dev1, Dev2">
</source>

=== id attribute ===

The id attribute is the unique identifier used for this add-on. It must be unique, and must use only lowercase characters, periods, underscores, dashes and numbers. This identifier is also used as the name of the folder that contains the add-on, so for ease of searching, we suggest you use something like <type>.<uniquename>.

=== version attribute ===

The version attribute is used by Kodi to determine whether updates are available. This should be use a version scheme like <code>x.y.z</code> (major.minor.patch). For example: <code>version="0.0.1"</code>. Generally, you'll start with a version of <code>0.y.z</code> for test releases and once you feel it is ready for a full release, you'd bump the version to <code>1.0.0</code>.

==== How versioning works ====

* <code>2.2.9</code> is newer than <code>2.2.1</code>
* <code>2.2.10</code> is newer than <code>2.2.1</code>
* <code>2.3.0</code> is newer than <code>2.2.9</code>
* <code>2.2.1</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1</code> is newer than <code>2.2.1~beta</code>
* <code>2.2.1~beta</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1~beta3</code> is newer than <code>2.2.1~beta2</code>
* <code>2.2.1~beta10</code> is newer than <code>2.2.1~beta1</code>

{{tip|Text should only be added for a beta version. In other cases version number should only contain numbers.}}

=== name attribute ===

The name attribute is the name of the add-on as it appears in the UI. This should be in English where it makes sense for it to be so, and is not translatable.

=== provider-name attribute ===

The provider-name attribute is used as the author field. This could be a team of authors or a single author. If the add-on is maintained by multiple people please separate them with a comma (<code>,</code>).

== <requires> ==

The <code><requires></code> element contains one or more <code><import></code> elements which specify which other add-ons this particular add-on requires, and which version of those add-ons it requires. These add-ons may be part of Kodi itself, or may be parts of other third-party add-ons.

Kodi will only allow the add-on to be run if suitable versions of the (non-optional) add-ons on which this add-on depends are installed. When a user installs your add-on from an online repository via Kodi's add-on manager, Kodi attempts to resolve these dependencies, and install anything that your add-on relies on first. The dependency must be provided with the minimum version number your script/skin requires.

=== Examples ===

Here is a sample <code><requires></code> block that imports two required modules:

<source lang="xml">
<requires>
<import addon="xbmc.python" version="2.14.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10"/>
</requires>
</source>

Here's another example, which will only install on OpenELEC:

<source lang="xml">
<requires>
<import addon="os.openelec.tv" version="2.0"/>
</requires>
</source>

== <import> ==

Each <code><import></code> element describes one dependency for an add-on, with two required attributes: <code>addon</code> and <code>version</code>. There is also an optional attribute called, fittingly, <code>optional</code>.

If your add-on relies on other third-party add-ons, Kodi will automatically install them as well, provided they are available on an existing add-on repository. If they aren't available on any existing repository, the user must install the other add-ons themselves. Note that you need to include any Python libraries you need directly in your add-on; these can't be loaded with an <code><import></code> element, since Kodi wouldn't know what to do with them.

=== addon attribute ===

The <code>addon</code> attribute specifies the id of the required add-on, e.g. <code>script.module.elementtree</code>.

=== version attribute ===

The <code>version</code> attribute specifies the minimum version of the required add-on to be installed.

==== Dependency versions ====

Each different Kodi version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of Kodi the add-on can be installed.

{| class="prettytable" border="1"
|+ Current versions
! Kodi version !! xbmc.python !! xbmc.gui !! xbmc.json !! xbmc.metadata !! xbmc.addon
|-
| Dharma 10.1 Deprecated|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 Deprecated || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x Deprecated|| 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
| Gotham 13.x || 2.14.0 (ABI 2.1.0) || 5.0.1 || 6.6.0 (ABI 6.0.0) || 2.1.0 || 13.0.0 (ABI 12.0.0)
|-
| Helix 14.x || 2.19.0 (ABI 2.1.0) || 5.3.0 || 6.20.0 (ABI 6.0.0) || 2.1.0 || 14.0.0 (ABI 12.0.0)
|-
| Isengard 15.x || 2.20.0 (ABI 2.1.0) || 5.9.0 (ABI 5.3.0) || 6.25.1 (ABI 6.0.0) || 2.1.0 || 15.0.0 (ABI 12.0.0)
|-
| Jarvis 16.x || 2.24.0 (ABI 2.1.0) || 5.10.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 || 16.0.0 (ABI 12.0.0)
|-
| Krypton 17.x || 2.25.0 (ABI 2.1.0) || 5.12.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 || 17.0.0 (ABI 12.0.0)
|-
| Leia 18.x || 2.25.0 (ABI 2.1.0) || 5.13.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 || 17.9.701 (ABI 12.0.0)
|}

Each Kodi version contain a certain backwards compatibility. For example add-ons made for Gotham 13.x can still work ion Jarvis 16.x. Do note that this might change in the future. The '''ABI''' version you see in the table above is the backwards compatibility version for which add-ons are still marked "working".

=== optional attribute ===

The dependency may be made optional by setting the <code>optional</code> attribute to <code>true</code>. This will only install the dependency when the add-on actually needs it. Even if this dependency is missing, the add-on can still be installed.

== <extension> ==

The <code><extension></code> element describes the technical aspects of this add-on. It will have at least a point attribute which will give the part of Kodi that the add-on extends. For instance, the <code>addon.xml</code> file for the Confluence skin extends the <code>xbmc.gui.skin</code> part of xbmc. All available extension points are given below.

The various extension points that Kodi provides are given in the list below.
{| class="prettytable"
!Extension point
!Add-on Category
|-
|<code>[[Skinning|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.webinterface</code>
|Web interface
|-
|<code>[[Add-on repositories|xbmc.addon.repository]]</code>
|''None''
|-
|<code>[[HOW-TO:_Automatically_start_addons_using_services|xbmc.service]]</code>
|Services
|-
|<code>xbmc.metadata.scraper.albums</code>
|Album information
|-
|<code>xbmc.metadata.scraper.artists</code>
|Artist information
|-
|<code>xbmc.metadata.scraper.movies</code>
|Movie information
|-
|<code>xbmc.metadata.scraper.musicvideos</code>
|Music video information
|-
|<code>xbmc.metadata.scraper.tvshows</code>
|TV information
|-
|<code>xbmc.metadata.scraper.library</code>
|''None''
|-
|<code>xbmc.ui.screensaver</code>
|Screensaver
|-
|<code>xbmc.player.musicviz</code>
|Visualization
|-
|<code>[[Plugin sources#What Kodi requires for your add-on|xbmc.python.pluginsource]]</code>
|Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
|-
|<code>[[Script sources#What Kodi requires for your add-on|xbmc.python.script]]</code>
|Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
|-
|<code>xbmc.python.weather</code>
|Weather
|-
|<code>xbmc.subtitle.module</code>
|Subtitle service module
|-
|<code>[[Script lyrics#What Kodi requires for your add-on|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>[[Script library#What Kodi requires for your add-on|xbmc.python.library]]</code>
|''None''
|-
|<code>xbmc.python.module</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.addon.video</code>
|Video Add-ons (video)
|-
|<code>xbmc.addon.audio</code>
|Music Add-ons (audio)
|-
|<code>xbmc.addon.image</code>
|Picture Add-ons (image)
|-
|<code>kodi.resource.images</code>
|Additional image files
|-
|<code>kodi.resource.language</code>
|Additional language files
|}

Add-ons that don't correspond to a specific add-on category can not be installed by users. These are usually supporting or shared add-ons that are installed automatically by the add-ons that require them.

=== xbmc.python.pluginsource ===
{{See also|Plugin sources}}

The most common extension point that will be used by plugin addon developers is <code>xbmc.python.pluginsource</code>.

==== library attribute ====

The <code><extension point="xbmc.python.pluginsource"></code> element has an extra attribute: <code>library</code>. This is the name of the Python script (startup script) that will be run when the add-on is activated. This file must exist in the root of your add-on directory.

==== <provides> element ====

The extension has an additional child element named <code><provides></code>, which contains a whitespace separated list of <code>image</code>, <code>video</code>, <code>audio</code>, and/or <code>executable</code>. This determines in what area (or context) of the Kodi system your addon will make itself visible in (please note that this applies only to plugin extension points):

{| class="prettytable"
!Provides
!Appears in
|-
|<code>image</code>
|Pictures
|-
|<code>audio</code>
|Music
|-
|<code>video</code>
|Video
|-
|<code>executable</code>
|Programs
|-
|''(blank)''
|Not visible
|}

==== Example ====

<source lang="xml">
<extension point="xbmc.python.pluginsource" library="gpodderxbmc.py">
<provides>audio video</provides>
</extension>
</source>

=== xbmc.addon.metadata ===

This special extension point ''must'' be provided by all add-ons, and is the way that your add-on is described to users of the Kodi add-on manager.

==== Required elements ====

There are several elements that this should contain and all are compulsory (except the broken tag). Each of the elements below must always be present in English as a minimum.

Many of these elements can be translated into multiple languages and should be added once for each supported language. The <code>lang</code> attribute should contain a [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifier]. If omitted, it defaults to en_GB. (Note: Kodi v14 and older uses ISO-639 code. See [[List of language codes (ISO-639:1988)]]).

===== <summary> =====

One or more <code><summary></code> elements provide a short summary of what the add-on does. This should be a single sentence. It may be translated into multiple languages.

<source lang="xml">
<summary lang="en_GB">Hello World script provides some basic examples on how to create your first script.</summary>
</source>

===== <description> =====

One or more <code><description></code> elements provide a more detailed summary of what the add-on does. It may be translated into multiple languages.

<source lang="xml">
<description lang="en_GB">Hello World script provides some basic examples on how to create your first script
and hopefully will increase the number of Kodi users to start creating their own addons.</description>
</source>

===== <disclaimer> =====

One or more <code><disclaimer></code> elements that indicate what (if any) things the user should know about the add-on. There is no need to have a disclaimer if you don't want one, though if something requires settings, or only works in a particular country then you may want to state this here. It may be translated into multiple languages.

<source lang="xml">
<disclaimer lang="en_GB">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <news> =====

{{note|Used in Kodi v17 Krypton and later only. Older versions are forward compatible.}}

The <code><news></code> element should contains a simple description of the major changes made to the add-on (new functionality, big fixes, etc). This is displayed in the Kodi addon installation/update system. (In the author's opinion, too many add-ons skip this piece of information, making it difficult for users to determine whether a particular problem that they may have been having has been fixed or not.)
Please keep it short, you might want to only include the changes for the last version here.

Here is an example:

<source lang="xml">
<news>v0.1.2 (2014-1-15)
- Added notification for Ubuntu users checking through apt command</news>
</source>

===== <platform> =====

The <code><platform></code> tag specifies which platforms (operating systems, hardware) this add-on runs on. Many add-ons will run on all platforms, so <code>all</code> is an option. If the platform tag is missing, we assume the add-on runs on all platforms. A combination of these is also possible. Currently available options are:

* <code>all</code>
* <code>linux</code>
* <code>osx</code>
* <code>osx64</code>
* <code>osx32</code>
* <code>ios</code>
* <code>windx</code>
* <code>android</code>

<source lang="xml">
<platform>all</platform>
</source>

===== <language> =====

The <code><language></code> elements indicate the language(s) of the ''content'' provided by your add-on. It applies to plugins, scripts, scrapers etc. This allows browsing the add-on list by language. When there is no specific language provided in your content, leave it blank.

<source lang="xml">
<language>en de fr</language>
or
<language></language>
</source>

===== <license> =====

The <code><license></code> element indicates what license is used for this add-on.

<source lang="xml">
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
</source>

===== <forum> =====

The <code><forum></code> element provides the forum thread URL for this specific add-on. Leave this blank if there is no forum thread.
<source lang="xml">
<forum>http://www.myaddonwebsite.com/forum.php?thread=12345</forum>
</source>

===== <website> =====

The <code><website></code> element provides the website URL for this specific add-on.

<source lang="xml">
<website>http://www.myaddonwebsite.com/</website>
</source>

===== <nowiki><source></nowiki> =====

The <code><nowiki><source></nowiki></code> element provides the URL for the source code for this specific add-on.
<syntaxhighlight lang="xml" enclose="div">
<source>http://github.com/someone/myaddon</source>
</syntaxhighlight>

===== <email> =====

The <code><email></code> element provides the email address of the author if he wishes to do so for this specific add-on. Here are two examples of how you can make it look (the second one it harder for spambots to use). This can be left blank if you do not want to make your email address public.
<source lang="xml">
<email>foo@bar.com</email>
or
<email>foo at bar dot com</email>
</source>

===== <broken> =====

The <code><broken></code> tag will mark the add-on as broken in the Kodi repo and provide the reason why. You don't need to do a version bump for this to work. However a bump is recommended as you could also add this to the changelog.

<source lang="xml">
<broken>deprecated</broken>
</source>

===== <assets> =====

{{note|Kodi v17 Krypton and later.}}

The <code><assets></code> element is a manifest that describes the various assets the add-on provides and where they are located. Supported sub-elements are:

* <code><icon></code> See [[Add-on_structure#icon.png]]
* <code><fanart></code> See [[Add-on_structure#fanart.jpg]]
* <code><screenshot></code>

If some elements are empty or not specified, it will be treated as non-existing/not provided.

Example:
<source lang="xml">
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
</assets>
</source>

With the above example definition, the files must be placed in the <code>resources</code> folder.

== Skin specific elements ==
=== Overview ===
{| class="prettytable"
| '''effectslowdown'''
| A multiplier that is applied to all <animation> effect lengths in the skin. Useful to slow down all animations globally so that you can better configure timings and see interactions between animating controls.
|-
| '''debugging'''
| When set to true, it'll display onscreen debug information (xml filename, mouse position and focused control type and name) in the skin.
|-
| '''res'''
| Support for arbitrary skin resolutions.
|}

=== How window xml files are found ===

Kodi can run in many differing resolutions, and a skin should try and cater to all these resolutions. The easiest way is to develop for one specific resolution and make sure that all controls contain <width> and <height> tags. That way, Kodi can scale the controls to the new screen resolution.

However, you may choose to develop alternative window xml files for differing resolutions (such as for HDTV resolutions, or for widescreen versus 4x3 resolutions).

The order that Kodi looks for it's skin files are as follows:

# It first looks in the current screenmode folder (one of 1080i, 720p, NTSC16x9, NTSC, PAL16x9 or PAL)
# If the current screenmode is 1080i and there's no 1080i folder, it then looks in the 720p folder.
# Finally, it looks in the '''res''' folder.

This allows you to just put any window files that do not require special treatment for 16x9 resolutions etc. in the <defaultresolution> folder, preventing needless repetition.

= Examples =

== addon.xml for skins ==

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addon
id="skin.confluence"
version="2.1.3"
name="Confluence"
provider-name="Jezz_X, Team Kodi">
<requires>
<import addon="xbmc.gui" version="5.13.0"/>
</requires>
<extension
point="xbmc.gui.skin"
debugging="false"
effectslowdown="0.75">
<res width="1280" height="720" aspect="16:9" default="true" folder="720p" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en">Confluence skin by Jezz_X. (Kodi's default skin)</summary>
<description lang="en">Confluence is the default skin for Kodi 9.11 and above. It is a combination of concepts from many popular skins, and attempts to embrace and integrate their good ideas into a skin that should be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en">Confluence is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
<news></news>
<assets>
<icon></icon>
<fanart></fanart>
<screenshot></screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that all tag names are lower case. XML tag names are case sensitive!

== addon.xml for scripts ==

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon
id="script.artwork.downloader"
name="Artwork Downloader"
version="12.0.12"
provider-name="Martijn">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
<import addon="xbmc.json" version="6.0.0"/>
<import addon="xbmc.addon" version="12.0.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10" optional="true"/>
<import addon="script.common.plugin.cache" version="1.3.0"/>
</requires>
<extension point="xbmc.python.script" library="default.py">
<provides>executable</provides>
</extension>
<extension point="xbmc.service" library="service.py" start="login"/>
<extension point="xbmc.addon.metadata">
<summary lang="en">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en">Downloads all available artwork for TV shows, Movies and Musicvideos in your library. Check the options for supported artwork[CR]Artwork sources:[CR]www.fanart.tv[CR]www.thetvdb.com[CR]www.themoviedb.org[CR]Remark:[CR]Check your skin to see what type of artwork is supported![CR]Each TV Show/Movie must have its own folder![CR]Skin integration:[CR]See readme file</description>
<disclaimer lang="en">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<language></language>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
<news></news>
<assets>
<icon></icon>
<fanart></fanart>
<screenshot></screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

= Schema Definition =

The XML schema definition for <code>addon.xml</code> is located [https://github.com/xbmc/xbmc/blob/master/addons/xbmc.addon/metadata.xsd here].

{{frodo updated}}

[[Category:Add-on development]]
[[Category:Skin development]]

Addon.xml

2018-02-27T21:04:04Z

Lunatixz:

{{mininav|[[Development]]|[[Add-on development]]}}
 

Every skin, script, or plugin in Kodi contains an <code>addon.xml</code> file which describes the add-on, providing credits, version information and dependencies. Below, we will explain how this file is structured and which elements must be used to create an add-on for Kodi. You can also consult the examples at the end to see how this file is laid out depending on if you are developing a skin or script.

Every <code>addon.xml</code> file has the same basic structure, this example is for a video plugin:

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_gb">Your add-on's summary</summary>
<description lang="en_gb">Your add-on's description</description>
<disclaimer lang="en_gb"></disclaimer>
<language></language>
<platform>all</platform>
<license></license>
<forum></forum>
<website></website>
<email></email>
<source></source>
<news></news>
<assets>
<icon></icon>
<fanart></fanart>
<banner></banner>
<clearlogo></clearlogo>
<screenshot></screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

There are a few important things to note in the above sample:

* The <code><addon></code> element must be present, and be the root node. It presents data about the add-on package as a whole.
* Inside the <code><addon></code> element is a <code><requires></code> element, listing all the dependencies that this add-on needs in order to function.
* Then there are one or more <code><extension></code> elements, each of which describes a part of Kodi that the add-on extends.
* Finally, there is a specific <code><extension></code> element that extends <code>"xbmc.addon.metadata"</code>. This describes the add-on to the user.
* Banners and clearlogos assets exclusive to Kodi v.18+
= Elements =

== <addon> ==

The <code><addon></code> element has 4 attributes, all required: <code>id</code>, <code>version</code>, <code>name</code>, and <code>provider-name</code>. For example:

<source lang="xml">
<addon id="script.hello.world" name="Hello World" version="0.0.1" provider-name="Dev1, Dev2">
</source>

=== id attribute ===

The id attribute is the unique identifier used for this add-on. It must be unique, and must use only lowercase characters, periods, underscores, dashes and numbers. This identifier is also used as the name of the folder that contains the add-on, so for ease of searching, we suggest you use something like <type>.<uniquename>.

=== version attribute ===

The version attribute is used by Kodi to determine whether updates are available. This should be use a version scheme like <code>x.y.z</code> (major.minor.patch). For example: <code>version="0.0.1"</code>. Generally, you'll start with a version of <code>0.y.z</code> for test releases and once you feel it is ready for a full release, you'd bump the version to <code>1.0.0</code>.

==== How versioning works ====

* <code>2.2.9</code> is newer than <code>2.2.1</code>
* <code>2.2.10</code> is newer than <code>2.2.1</code>
* <code>2.3.0</code> is newer than <code>2.2.9</code>
* <code>2.2.1</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1</code> is newer than <code>2.2.1~beta</code>
* <code>2.2.1~beta</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1~beta3</code> is newer than <code>2.2.1~beta2</code>
* <code>2.2.1~beta10</code> is newer than <code>2.2.1~beta1</code>

{{tip|Text should only be added for a beta version. In other cases version number should only contain numbers.}}

=== name attribute ===

The name attribute is the name of the add-on as it appears in the UI. This should be in English where it makes sense for it to be so, and is not translatable.

=== provider-name attribute ===

The provider-name attribute is used as the author field. This could be a team of authors or a single author. If the add-on is maintained by multiple people please separate them with a comma (<code>,</code>).

== <requires> ==

The <code><requires></code> element contains one or more <code><import></code> elements which specify which other add-ons this particular add-on requires, and which version of those add-ons it requires. These add-ons may be part of Kodi itself, or may be parts of other third-party add-ons.

Kodi will only allow the add-on to be run if suitable versions of the (non-optional) add-ons on which this add-on depends are installed. When a user installs your add-on from an online repository via Kodi's add-on manager, Kodi attempts to resolve these dependencies, and install anything that your add-on relies on first. The dependency must be provided with the minimum version number your script/skin requires.

=== Examples ===

Here is a sample <code><requires></code> block that imports two required modules:

<source lang="xml">
<requires>
<import addon="xbmc.python" version="2.14.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10"/>
</requires>
</source>

Here's another example, which will only install on OpenELEC:

<source lang="xml">
<requires>
<import addon="os.openelec.tv" version="2.0"/>
</requires>
</source>

== <import> ==

Each <code><import></code> element describes one dependency for an add-on, with two required attributes: <code>addon</code> and <code>version</code>. There is also an optional attribute called, fittingly, <code>optional</code>.

If your add-on relies on other third-party add-ons, Kodi will automatically install them as well, provided they are available on an existing add-on repository. If they aren't available on any existing repository, the user must install the other add-ons themselves. Note that you need to include any Python libraries you need directly in your add-on; these can't be loaded with an <code><import></code> element, since Kodi wouldn't know what to do with them.

=== addon attribute ===

The <code>addon</code> attribute specifies the id of the required add-on, e.g. <code>script.module.elementtree</code>.

=== version attribute ===

The <code>version</code> attribute specifies the minimum version of the required add-on to be installed.

==== Dependency versions ====

Each different Kodi version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of Kodi the add-on can be installed.

{| class="prettytable" border="1"
|+ Current versions
! Kodi version !! xbmc.python !! xbmc.gui !! xbmc.json !! xbmc.metadata !! xbmc.addon
|-
| Dharma 10.1 Deprecated|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 Deprecated || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x Deprecated|| 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
| Gotham 13.x || 2.14.0 (ABI 2.1.0) || 5.0.1 || 6.6.0 (ABI 6.0.0) || 2.1.0 || 13.0.0 (ABI 12.0.0)
|-
| Helix 14.x || 2.19.0 (ABI 2.1.0) || 5.3.0 || 6.20.0 (ABI 6.0.0) || 2.1.0 || 14.0.0 (ABI 12.0.0)
|-
| Isengard 15.x || 2.20.0 (ABI 2.1.0) || 5.9.0 (ABI 5.3.0) || 6.25.1 (ABI 6.0.0) || 2.1.0 || 15.0.0 (ABI 12.0.0)
|-
| Jarvis 16.x || 2.24.0 (ABI 2.1.0) || 5.10.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 || 16.0.0 (ABI 12.0.0)
|-
| Krypton 17.x || 2.25.0 (ABI 2.1.0) || 5.12.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 || 17.0.0 (ABI 12.0.0)
|-
| Leia 18.x || 2.25.0 (ABI 2.1.0) || 5.13.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 || 17.9.701 (ABI 12.0.0)
|}

Each Kodi version contain a certain backwards compatibility. For example add-ons made for Gotham 13.x can still work ion Jarvis 16.x. Do note that this might change in the future. The '''ABI''' version you see in the table above is the backwards compatibility version for which add-ons are still marked "working".

=== optional attribute ===

The dependency may be made optional by setting the <code>optional</code> attribute to <code>true</code>. This will only install the dependency when the add-on actually needs it. Even if this dependency is missing, the add-on can still be installed.

== <extension> ==

The <code><extension></code> element describes the technical aspects of this add-on. It will have at least a point attribute which will give the part of Kodi that the add-on extends. For instance, the <code>addon.xml</code> file for the Confluence skin extends the <code>xbmc.gui.skin</code> part of xbmc. All available extension points are given below.

The various extension points that Kodi provides are given in the list below.
{| class="prettytable"
!Extension point
!Add-on Category
|-
|<code>[[Skinning|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.webinterface</code>
|Web interface
|-
|<code>[[Add-on repositories|xbmc.addon.repository]]</code>
|''None''
|-
|<code>[[HOW-TO:_Automatically_start_addons_using_services|xbmc.service]]</code>
|Services
|-
|<code>xbmc.metadata.scraper.albums</code>
|Album information
|-
|<code>xbmc.metadata.scraper.artists</code>
|Artist information
|-
|<code>xbmc.metadata.scraper.movies</code>
|Movie information
|-
|<code>xbmc.metadata.scraper.musicvideos</code>
|Music video information
|-
|<code>xbmc.metadata.scraper.tvshows</code>
|TV information
|-
|<code>xbmc.metadata.scraper.library</code>
|''None''
|-
|<code>xbmc.ui.screensaver</code>
|Screensaver
|-
|<code>xbmc.player.musicviz</code>
|Visualization
|-
|<code>[[Plugin sources#What Kodi requires for your add-on|xbmc.python.pluginsource]]</code>
|Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
|-
|<code>[[Script sources#What Kodi requires for your add-on|xbmc.python.script]]</code>
|Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
|-
|<code>xbmc.python.weather</code>
|Weather
|-
|<code>xbmc.subtitle.module</code>
|Subtitle service module
|-
|<code>[[Script lyrics#What Kodi requires for your add-on|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>[[Script library#What Kodi requires for your add-on|xbmc.python.library]]</code>
|''None''
|-
|<code>xbmc.python.module</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.addon.video</code>
|Video Add-ons (video)
|-
|<code>xbmc.addon.audio</code>
|Music Add-ons (audio)
|-
|<code>xbmc.addon.image</code>
|Picture Add-ons (image)
|-
|<code>kodi.resource.images</code>
|Additional image files
|-
|<code>kodi.resource.language</code>
|Additional language files
|}

Add-ons that don't correspond to a specific add-on category can not be installed by users. These are usually supporting or shared add-ons that are installed automatically by the add-ons that require them.

=== xbmc.python.pluginsource ===
{{See also|Plugin sources}}

The most common extension point that will be used by plugin addon developers is <code>xbmc.python.pluginsource</code>.

==== library attribute ====

The <code><extension point="xbmc.python.pluginsource"></code> element has an extra attribute: <code>library</code>. This is the name of the Python script (startup script) that will be run when the add-on is activated. This file must exist in the root of your add-on directory.

==== <provides> element ====

The extension has an additional child element named <code><provides></code>, which contains a whitespace separated list of <code>image</code>, <code>video</code>, <code>audio</code>, and/or <code>executable</code>. This determines in what area (or context) of the Kodi system your addon will make itself visible in (please note that this applies only to plugin extension points):

{| class="prettytable"
!Provides
!Appears in
|-
|<code>image</code>
|Pictures
|-
|<code>audio</code>
|Music
|-
|<code>video</code>
|Video
|-
|<code>executable</code>
|Programs
|-
|''(blank)''
|Not visible
|}

==== Example ====

<source lang="xml">
<extension point="xbmc.python.pluginsource" library="gpodderxbmc.py">
<provides>audio video</provides>
</extension>
</source>

=== xbmc.addon.metadata ===

This special extension point ''must'' be provided by all add-ons, and is the way that your add-on is described to users of the Kodi add-on manager.

==== Required elements ====

There are several elements that this should contain and all are compulsory (except the broken tag). Each of the elements below must always be present in English as a minimum.

Many of these elements can be translated into multiple languages and should be added once for each supported language. The <code>lang</code> attribute should contain a [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifier]. If omitted, it defaults to en_GB. (Note: Kodi v14 and older uses ISO-639 code. See [[List of language codes (ISO-639:1988)]]).

===== <summary> =====

One or more <code><summary></code> elements provide a short summary of what the add-on does. This should be a single sentence. It may be translated into multiple languages.

<source lang="xml">
<summary lang="en_GB">Hello World script provides some basic examples on how to create your first script.</summary>
</source>

===== <description> =====

One or more <code><description></code> elements provide a more detailed summary of what the add-on does. It may be translated into multiple languages.

<source lang="xml">
<description lang="en_GB">Hello World script provides some basic examples on how to create your first script
and hopefully will increase the number of Kodi users to start creating their own addons.</description>
</source>

===== <disclaimer> =====

One or more <code><disclaimer></code> elements that indicate what (if any) things the user should know about the add-on. There is no need to have a disclaimer if you don't want one, though if something requires settings, or only works in a particular country then you may want to state this here. It may be translated into multiple languages.

<source lang="xml">
<disclaimer lang="en_GB">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <news> =====

{{note|Used in Kodi v17 Krypton and later only. Older versions are forward compatible.}}

The <code><news></code> element should contains a simple description of the major changes made to the add-on (new functionality, big fixes, etc). This is displayed in the Kodi addon installation/update system. (In the author's opinion, too many add-ons skip this piece of information, making it difficult for users to determine whether a particular problem that they may have been having has been fixed or not.)
Please keep it short, you might want to only include the changes for the last version here.

Here is an example:

<source lang="xml">
<news>v0.1.2 (2014-1-15)
- Added notification for Ubuntu users checking through apt command</news>
</source>

===== <platform> =====

The <code><platform></code> tag specifies which platforms (operating systems, hardware) this add-on runs on. Many add-ons will run on all platforms, so <code>all</code> is an option. If the platform tag is missing, we assume the add-on runs on all platforms. A combination of these is also possible. Currently available options are:

* <code>all</code>
* <code>linux</code>
* <code>osx</code>
* <code>osx64</code>
* <code>osx32</code>
* <code>ios</code>
* <code>windx</code>
* <code>android</code>

<source lang="xml">
<platform>all</platform>
</source>

===== <language> =====

The <code><language></code> elements indicate the language(s) of the ''content'' provided by your add-on. It applies to plugins, scripts, scrapers etc. This allows browsing the add-on list by language. When there is no specific language provided in your content, leave it blank.

<source lang="xml">
<language>en de fr</language>
or
<language></language>
</source>

===== <license> =====

The <code><license></code> element indicates what license is used for this add-on.

<source lang="xml">
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
</source>

===== <forum> =====

The <code><forum></code> element provides the forum thread URL for this specific add-on. Leave this blank if there is no forum thread.
<source lang="xml">
<forum>http://www.myaddonwebsite.com/forum.php?thread=12345</forum>
</source>

===== <website> =====

The <code><website></code> element provides the website URL for this specific add-on.

<source lang="xml">
<website>http://www.myaddonwebsite.com/</website>
</source>

===== <nowiki><source></nowiki> =====

The <code><nowiki><source></nowiki></code> element provides the URL for the source code for this specific add-on.
<syntaxhighlight lang="xml" enclose="div">
<source>http://github.com/someone/myaddon</source>
</syntaxhighlight>

===== <email> =====

The <code><email></code> element provides the email address of the author if he wishes to do so for this specific add-on. Here are two examples of how you can make it look (the second one it harder for spambots to use). This can be left blank if you do not want to make your email address public.
<source lang="xml">
<email>foo@bar.com</email>
or
<email>foo at bar dot com</email>
</source>

===== <broken> =====

The <code><broken></code> tag will mark the add-on as broken in the Kodi repo and provide the reason why. You don't need to do a version bump for this to work. However a bump is recommended as you could also add this to the changelog.

<source lang="xml">
<broken>deprecated</broken>
</source>

===== <assets> =====

{{note|Kodi v17 Krypton and later.}}

The <code><assets></code> element is a manifest that describes the various assets the add-on provides and where they are located. Supported sub-elements are:

* <code><icon></code> See [[Add-on_structure#icon.png]]
* <code><fanart></code> See [[Add-on_structure#fanart.jpg]]
* <code><screenshot></code>

If some elements are empty or not specified, it will be treated as non-existing/not provided.

Example:
<source lang="xml">
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
</assets>
</source>

With the above example definition, the files must be placed in the <code>resources</code> folder.

== Skin specific elements ==
=== Overview ===
{| class="prettytable"
| '''effectslowdown'''
| A multiplier that is applied to all <animation> effect lengths in the skin. Useful to slow down all animations globally so that you can better configure timings and see interactions between animating controls.
|-
| '''debugging'''
| When set to true, it'll display onscreen debug information (xml filename, mouse position and focused control type and name) in the skin.
|-
| '''res'''
| Support for arbitrary skin resolutions.
|}

=== How window xml files are found ===

Kodi can run in many differing resolutions, and a skin should try and cater to all these resolutions. The easiest way is to develop for one specific resolution and make sure that all controls contain <width> and <height> tags. That way, Kodi can scale the controls to the new screen resolution.

However, you may choose to develop alternative window xml files for differing resolutions (such as for HDTV resolutions, or for widescreen versus 4x3 resolutions).

The order that Kodi looks for it's skin files are as follows:

# It first looks in the current screenmode folder (one of 1080i, 720p, NTSC16x9, NTSC, PAL16x9 or PAL)
# If the current screenmode is 1080i and there's no 1080i folder, it then looks in the 720p folder.
# Finally, it looks in the '''res''' folder.

This allows you to just put any window files that do not require special treatment for 16x9 resolutions etc. in the <defaultresolution> folder, preventing needless repetition.

= Examples =

== addon.xml for skins ==

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addon
id="skin.confluence"
version="2.1.3"
name="Confluence"
provider-name="Jezz_X, Team Kodi">
<requires>
<import addon="xbmc.gui" version="5.13.0"/>
</requires>
<extension
point="xbmc.gui.skin"
debugging="false"
effectslowdown="0.75">
<res width="1280" height="720" aspect="16:9" default="true" folder="720p" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en">Confluence skin by Jezz_X. (Kodi's default skin)</summary>
<description lang="en">Confluence is the default skin for Kodi 9.11 and above. It is a combination of concepts from many popular skins, and attempts to embrace and integrate their good ideas into a skin that should be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en">Confluence is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
<news></news>
<assets>
<icon></icon>
<fanart></fanart>
<screenshot></screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that all tag names are lower case. XML tag names are case sensitive!

== addon.xml for scripts ==

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon
id="script.artwork.downloader"
name="Artwork Downloader"
version="12.0.12"
provider-name="Martijn">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
<import addon="xbmc.json" version="6.0.0"/>
<import addon="xbmc.addon" version="12.0.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10" optional="true"/>
<import addon="script.common.plugin.cache" version="1.3.0"/>
</requires>
<extension point="xbmc.python.script" library="default.py">
<provides>executable</provides>
</extension>
<extension point="xbmc.service" library="service.py" start="login"/>
<extension point="xbmc.addon.metadata">
<summary lang="en">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en">Downloads all available artwork for TV shows, Movies and Musicvideos in your library. Check the options for supported artwork[CR]Artwork sources:[CR]www.fanart.tv[CR]www.thetvdb.com[CR]www.themoviedb.org[CR]Remark:[CR]Check your skin to see what type of artwork is supported![CR]Each TV Show/Movie must have its own folder![CR]Skin integration:[CR]See readme file</description>
<disclaimer lang="en">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<language></language>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
<news></news>
<assets>
<icon></icon>
<fanart></fanart>
<screenshot></screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

= Schema Definition =

The XML schema definition for <code>addon.xml</code> is located [https://github.com/xbmc/xbmc/blob/master/addons/xbmc.addon/metadata.xsd here].

{{frodo updated}}

[[Category:Add-on development]]
[[Category:Skin development]]

Addon.xml

2018-02-27T21:03:41Z

Lunatixz:

{{mininav|[[Development]]|[[Add-on development]]}}
 

Every skin, script, or plugin in Kodi contains an <code>addon.xml</code> file which describes the add-on, providing credits, version information and dependencies. Below, we will explain how this file is structured and which elements must be used to create an add-on for Kodi. You can also consult the examples at the end to see how this file is laid out depending on if you are developing a skin or script.

Every <code>addon.xml</code> file has the same basic structure, this example is for a video plugin:

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_gb">Your add-on's summary</summary>
<description lang="en_gb">Your add-on's description</description>
<disclaimer lang="en_gb"></disclaimer>
<language></language>
<platform>all</platform>
<license></license>
<forum></forum>
<website></website>
<email></email>
<source></source>
<news></news>
<assets>
<icon></icon>
<fanart></fanart>
<banner></banner>
<clearlogo></clearlogo>
<screenshot></screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

There are a few important things to note in the above sample:

* The <code><addon></code> element must be present, and be the root node. It presents data about the add-on package as a whole.
* Inside the <code><addon></code> element is a <code><requires></code> element, listing all the dependencies that this add-on needs in order to function.
* Then there are one or more <code><extension></code> elements, each of which describes a part of Kodi that the add-on extends.
* Finally, there is a specific <code><extension></code> element that extends <code>"xbmc.addon.metadata"</code>. This describes the add-on to the user.
* Banners and Clearlogos exclusive to Kodi v.18+
= Elements =

== <addon> ==

The <code><addon></code> element has 4 attributes, all required: <code>id</code>, <code>version</code>, <code>name</code>, and <code>provider-name</code>. For example:

<source lang="xml">
<addon id="script.hello.world" name="Hello World" version="0.0.1" provider-name="Dev1, Dev2">
</source>

=== id attribute ===

The id attribute is the unique identifier used for this add-on. It must be unique, and must use only lowercase characters, periods, underscores, dashes and numbers. This identifier is also used as the name of the folder that contains the add-on, so for ease of searching, we suggest you use something like <type>.<uniquename>.

=== version attribute ===

The version attribute is used by Kodi to determine whether updates are available. This should be use a version scheme like <code>x.y.z</code> (major.minor.patch). For example: <code>version="0.0.1"</code>. Generally, you'll start with a version of <code>0.y.z</code> for test releases and once you feel it is ready for a full release, you'd bump the version to <code>1.0.0</code>.

==== How versioning works ====

* <code>2.2.9</code> is newer than <code>2.2.1</code>
* <code>2.2.10</code> is newer than <code>2.2.1</code>
* <code>2.3.0</code> is newer than <code>2.2.9</code>
* <code>2.2.1</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1</code> is newer than <code>2.2.1~beta</code>
* <code>2.2.1~beta</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1~beta3</code> is newer than <code>2.2.1~beta2</code>
* <code>2.2.1~beta10</code> is newer than <code>2.2.1~beta1</code>

{{tip|Text should only be added for a beta version. In other cases version number should only contain numbers.}}

=== name attribute ===

The name attribute is the name of the add-on as it appears in the UI. This should be in English where it makes sense for it to be so, and is not translatable.

=== provider-name attribute ===

The provider-name attribute is used as the author field. This could be a team of authors or a single author. If the add-on is maintained by multiple people please separate them with a comma (<code>,</code>).

== <requires> ==

The <code><requires></code> element contains one or more <code><import></code> elements which specify which other add-ons this particular add-on requires, and which version of those add-ons it requires. These add-ons may be part of Kodi itself, or may be parts of other third-party add-ons.

Kodi will only allow the add-on to be run if suitable versions of the (non-optional) add-ons on which this add-on depends are installed. When a user installs your add-on from an online repository via Kodi's add-on manager, Kodi attempts to resolve these dependencies, and install anything that your add-on relies on first. The dependency must be provided with the minimum version number your script/skin requires.

=== Examples ===

Here is a sample <code><requires></code> block that imports two required modules:

<source lang="xml">
<requires>
<import addon="xbmc.python" version="2.14.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10"/>
</requires>
</source>

Here's another example, which will only install on OpenELEC:

<source lang="xml">
<requires>
<import addon="os.openelec.tv" version="2.0"/>
</requires>
</source>

== <import> ==

Each <code><import></code> element describes one dependency for an add-on, with two required attributes: <code>addon</code> and <code>version</code>. There is also an optional attribute called, fittingly, <code>optional</code>.

If your add-on relies on other third-party add-ons, Kodi will automatically install them as well, provided they are available on an existing add-on repository. If they aren't available on any existing repository, the user must install the other add-ons themselves. Note that you need to include any Python libraries you need directly in your add-on; these can't be loaded with an <code><import></code> element, since Kodi wouldn't know what to do with them.

=== addon attribute ===

The <code>addon</code> attribute specifies the id of the required add-on, e.g. <code>script.module.elementtree</code>.

=== version attribute ===

The <code>version</code> attribute specifies the minimum version of the required add-on to be installed.

==== Dependency versions ====

Each different Kodi version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of Kodi the add-on can be installed.

{| class="prettytable" border="1"
|+ Current versions
! Kodi version !! xbmc.python !! xbmc.gui !! xbmc.json !! xbmc.metadata !! xbmc.addon
|-
| Dharma 10.1 Deprecated|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 Deprecated || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x Deprecated|| 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
| Gotham 13.x || 2.14.0 (ABI 2.1.0) || 5.0.1 || 6.6.0 (ABI 6.0.0) || 2.1.0 || 13.0.0 (ABI 12.0.0)
|-
| Helix 14.x || 2.19.0 (ABI 2.1.0) || 5.3.0 || 6.20.0 (ABI 6.0.0) || 2.1.0 || 14.0.0 (ABI 12.0.0)
|-
| Isengard 15.x || 2.20.0 (ABI 2.1.0) || 5.9.0 (ABI 5.3.0) || 6.25.1 (ABI 6.0.0) || 2.1.0 || 15.0.0 (ABI 12.0.0)
|-
| Jarvis 16.x || 2.24.0 (ABI 2.1.0) || 5.10.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 || 16.0.0 (ABI 12.0.0)
|-
| Krypton 17.x || 2.25.0 (ABI 2.1.0) || 5.12.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 || 17.0.0 (ABI 12.0.0)
|-
| Leia 18.x || 2.25.0 (ABI 2.1.0) || 5.13.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 || 17.9.701 (ABI 12.0.0)
|}

Each Kodi version contain a certain backwards compatibility. For example add-ons made for Gotham 13.x can still work ion Jarvis 16.x. Do note that this might change in the future. The '''ABI''' version you see in the table above is the backwards compatibility version for which add-ons are still marked "working".

=== optional attribute ===

The dependency may be made optional by setting the <code>optional</code> attribute to <code>true</code>. This will only install the dependency when the add-on actually needs it. Even if this dependency is missing, the add-on can still be installed.

== <extension> ==

The <code><extension></code> element describes the technical aspects of this add-on. It will have at least a point attribute which will give the part of Kodi that the add-on extends. For instance, the <code>addon.xml</code> file for the Confluence skin extends the <code>xbmc.gui.skin</code> part of xbmc. All available extension points are given below.

The various extension points that Kodi provides are given in the list below.
{| class="prettytable"
!Extension point
!Add-on Category
|-
|<code>[[Skinning|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.webinterface</code>
|Web interface
|-
|<code>[[Add-on repositories|xbmc.addon.repository]]</code>
|''None''
|-
|<code>[[HOW-TO:_Automatically_start_addons_using_services|xbmc.service]]</code>
|Services
|-
|<code>xbmc.metadata.scraper.albums</code>
|Album information
|-
|<code>xbmc.metadata.scraper.artists</code>
|Artist information
|-
|<code>xbmc.metadata.scraper.movies</code>
|Movie information
|-
|<code>xbmc.metadata.scraper.musicvideos</code>
|Music video information
|-
|<code>xbmc.metadata.scraper.tvshows</code>
|TV information
|-
|<code>xbmc.metadata.scraper.library</code>
|''None''
|-
|<code>xbmc.ui.screensaver</code>
|Screensaver
|-
|<code>xbmc.player.musicviz</code>
|Visualization
|-
|<code>[[Plugin sources#What Kodi requires for your add-on|xbmc.python.pluginsource]]</code>
|Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
|-
|<code>[[Script sources#What Kodi requires for your add-on|xbmc.python.script]]</code>
|Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
|-
|<code>xbmc.python.weather</code>
|Weather
|-
|<code>xbmc.subtitle.module</code>
|Subtitle service module
|-
|<code>[[Script lyrics#What Kodi requires for your add-on|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>[[Script library#What Kodi requires for your add-on|xbmc.python.library]]</code>
|''None''
|-
|<code>xbmc.python.module</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.addon.video</code>
|Video Add-ons (video)
|-
|<code>xbmc.addon.audio</code>
|Music Add-ons (audio)
|-
|<code>xbmc.addon.image</code>
|Picture Add-ons (image)
|-
|<code>kodi.resource.images</code>
|Additional image files
|-
|<code>kodi.resource.language</code>
|Additional language files
|}

Add-ons that don't correspond to a specific add-on category can not be installed by users. These are usually supporting or shared add-ons that are installed automatically by the add-ons that require them.

=== xbmc.python.pluginsource ===
{{See also|Plugin sources}}

The most common extension point that will be used by plugin addon developers is <code>xbmc.python.pluginsource</code>.

==== library attribute ====

The <code><extension point="xbmc.python.pluginsource"></code> element has an extra attribute: <code>library</code>. This is the name of the Python script (startup script) that will be run when the add-on is activated. This file must exist in the root of your add-on directory.

==== <provides> element ====

The extension has an additional child element named <code><provides></code>, which contains a whitespace separated list of <code>image</code>, <code>video</code>, <code>audio</code>, and/or <code>executable</code>. This determines in what area (or context) of the Kodi system your addon will make itself visible in (please note that this applies only to plugin extension points):

{| class="prettytable"
!Provides
!Appears in
|-
|<code>image</code>
|Pictures
|-
|<code>audio</code>
|Music
|-
|<code>video</code>
|Video
|-
|<code>executable</code>
|Programs
|-
|''(blank)''
|Not visible
|}

==== Example ====

<source lang="xml">
<extension point="xbmc.python.pluginsource" library="gpodderxbmc.py">
<provides>audio video</provides>
</extension>
</source>

=== xbmc.addon.metadata ===

This special extension point ''must'' be provided by all add-ons, and is the way that your add-on is described to users of the Kodi add-on manager.

==== Required elements ====

There are several elements that this should contain and all are compulsory (except the broken tag). Each of the elements below must always be present in English as a minimum.

Many of these elements can be translated into multiple languages and should be added once for each supported language. The <code>lang</code> attribute should contain a [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifier]. If omitted, it defaults to en_GB. (Note: Kodi v14 and older uses ISO-639 code. See [[List of language codes (ISO-639:1988)]]).

===== <summary> =====

One or more <code><summary></code> elements provide a short summary of what the add-on does. This should be a single sentence. It may be translated into multiple languages.

<source lang="xml">
<summary lang="en_GB">Hello World script provides some basic examples on how to create your first script.</summary>
</source>

===== <description> =====

One or more <code><description></code> elements provide a more detailed summary of what the add-on does. It may be translated into multiple languages.

<source lang="xml">
<description lang="en_GB">Hello World script provides some basic examples on how to create your first script
and hopefully will increase the number of Kodi users to start creating their own addons.</description>
</source>

===== <disclaimer> =====

One or more <code><disclaimer></code> elements that indicate what (if any) things the user should know about the add-on. There is no need to have a disclaimer if you don't want one, though if something requires settings, or only works in a particular country then you may want to state this here. It may be translated into multiple languages.

<source lang="xml">
<disclaimer lang="en_GB">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <news> =====

{{note|Used in Kodi v17 Krypton and later only. Older versions are forward compatible.}}

The <code><news></code> element should contains a simple description of the major changes made to the add-on (new functionality, big fixes, etc). This is displayed in the Kodi addon installation/update system. (In the author's opinion, too many add-ons skip this piece of information, making it difficult for users to determine whether a particular problem that they may have been having has been fixed or not.)
Please keep it short, you might want to only include the changes for the last version here.

Here is an example:

<source lang="xml">
<news>v0.1.2 (2014-1-15)
- Added notification for Ubuntu users checking through apt command</news>
</source>

===== <platform> =====

The <code><platform></code> tag specifies which platforms (operating systems, hardware) this add-on runs on. Many add-ons will run on all platforms, so <code>all</code> is an option. If the platform tag is missing, we assume the add-on runs on all platforms. A combination of these is also possible. Currently available options are:

* <code>all</code>
* <code>linux</code>
* <code>osx</code>
* <code>osx64</code>
* <code>osx32</code>
* <code>ios</code>
* <code>windx</code>
* <code>android</code>

<source lang="xml">
<platform>all</platform>
</source>

===== <language> =====

The <code><language></code> elements indicate the language(s) of the ''content'' provided by your add-on. It applies to plugins, scripts, scrapers etc. This allows browsing the add-on list by language. When there is no specific language provided in your content, leave it blank.

<source lang="xml">
<language>en de fr</language>
or
<language></language>
</source>

===== <license> =====

The <code><license></code> element indicates what license is used for this add-on.

<source lang="xml">
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
</source>

===== <forum> =====

The <code><forum></code> element provides the forum thread URL for this specific add-on. Leave this blank if there is no forum thread.
<source lang="xml">
<forum>http://www.myaddonwebsite.com/forum.php?thread=12345</forum>
</source>

===== <website> =====

The <code><website></code> element provides the website URL for this specific add-on.

<source lang="xml">
<website>http://www.myaddonwebsite.com/</website>
</source>

===== <nowiki><source></nowiki> =====

The <code><nowiki><source></nowiki></code> element provides the URL for the source code for this specific add-on.
<syntaxhighlight lang="xml" enclose="div">
<source>http://github.com/someone/myaddon</source>
</syntaxhighlight>

===== <email> =====

The <code><email></code> element provides the email address of the author if he wishes to do so for this specific add-on. Here are two examples of how you can make it look (the second one it harder for spambots to use). This can be left blank if you do not want to make your email address public.
<source lang="xml">
<email>foo@bar.com</email>
or
<email>foo at bar dot com</email>
</source>

===== <broken> =====

The <code><broken></code> tag will mark the add-on as broken in the Kodi repo and provide the reason why. You don't need to do a version bump for this to work. However a bump is recommended as you could also add this to the changelog.

<source lang="xml">
<broken>deprecated</broken>
</source>

===== <assets> =====

{{note|Kodi v17 Krypton and later.}}

The <code><assets></code> element is a manifest that describes the various assets the add-on provides and where they are located. Supported sub-elements are:

* <code><icon></code> See [[Add-on_structure#icon.png]]
* <code><fanart></code> See [[Add-on_structure#fanart.jpg]]
* <code><screenshot></code>

If some elements are empty or not specified, it will be treated as non-existing/not provided.

Example:
<source lang="xml">
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
</assets>
</source>

With the above example definition, the files must be placed in the <code>resources</code> folder.

== Skin specific elements ==
=== Overview ===
{| class="prettytable"
| '''effectslowdown'''
| A multiplier that is applied to all <animation> effect lengths in the skin. Useful to slow down all animations globally so that you can better configure timings and see interactions between animating controls.
|-
| '''debugging'''
| When set to true, it'll display onscreen debug information (xml filename, mouse position and focused control type and name) in the skin.
|-
| '''res'''
| Support for arbitrary skin resolutions.
|}

=== How window xml files are found ===

Kodi can run in many differing resolutions, and a skin should try and cater to all these resolutions. The easiest way is to develop for one specific resolution and make sure that all controls contain <width> and <height> tags. That way, Kodi can scale the controls to the new screen resolution.

However, you may choose to develop alternative window xml files for differing resolutions (such as for HDTV resolutions, or for widescreen versus 4x3 resolutions).

The order that Kodi looks for it's skin files are as follows:

# It first looks in the current screenmode folder (one of 1080i, 720p, NTSC16x9, NTSC, PAL16x9 or PAL)
# If the current screenmode is 1080i and there's no 1080i folder, it then looks in the 720p folder.
# Finally, it looks in the '''res''' folder.

This allows you to just put any window files that do not require special treatment for 16x9 resolutions etc. in the <defaultresolution> folder, preventing needless repetition.

= Examples =

== addon.xml for skins ==

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addon
id="skin.confluence"
version="2.1.3"
name="Confluence"
provider-name="Jezz_X, Team Kodi">
<requires>
<import addon="xbmc.gui" version="5.13.0"/>
</requires>
<extension
point="xbmc.gui.skin"
debugging="false"
effectslowdown="0.75">
<res width="1280" height="720" aspect="16:9" default="true" folder="720p" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en">Confluence skin by Jezz_X. (Kodi's default skin)</summary>
<description lang="en">Confluence is the default skin for Kodi 9.11 and above. It is a combination of concepts from many popular skins, and attempts to embrace and integrate their good ideas into a skin that should be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en">Confluence is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
<news></news>
<assets>
<icon></icon>
<fanart></fanart>
<screenshot></screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that all tag names are lower case. XML tag names are case sensitive!

== addon.xml for scripts ==

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon
id="script.artwork.downloader"
name="Artwork Downloader"
version="12.0.12"
provider-name="Martijn">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
<import addon="xbmc.json" version="6.0.0"/>
<import addon="xbmc.addon" version="12.0.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10" optional="true"/>
<import addon="script.common.plugin.cache" version="1.3.0"/>
</requires>
<extension point="xbmc.python.script" library="default.py">
<provides>executable</provides>
</extension>
<extension point="xbmc.service" library="service.py" start="login"/>
<extension point="xbmc.addon.metadata">
<summary lang="en">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en">Downloads all available artwork for TV shows, Movies and Musicvideos in your library. Check the options for supported artwork[CR]Artwork sources:[CR]www.fanart.tv[CR]www.thetvdb.com[CR]www.themoviedb.org[CR]Remark:[CR]Check your skin to see what type of artwork is supported![CR]Each TV Show/Movie must have its own folder![CR]Skin integration:[CR]See readme file</description>
<disclaimer lang="en">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<language></language>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
<news></news>
<assets>
<icon></icon>
<fanart></fanart>
<screenshot></screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

= Schema Definition =

The XML schema definition for <code>addon.xml</code> is located [https://github.com/xbmc/xbmc/blob/master/addons/xbmc.addon/metadata.xsd here].

{{frodo updated}}

[[Category:Add-on development]]
[[Category:Skin development]]

Addon.xml

2018-02-27T20:54:15Z

Lunatixz:

{{mininav|[[Development]]|[[Add-on development]]}}
 

Every skin, script, or plugin in Kodi contains an <code>addon.xml</code> file which describes the add-on, providing credits, version information and dependencies. Below, we will explain how this file is structured and which elements must be used to create an add-on for Kodi. You can also consult the examples at the end to see how this file is laid out depending on if you are developing a skin or script.

Every <code>addon.xml</code> file has the same basic structure, this example is for a video plugin:

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon id="plugin.addon.id" name="Your Add-on" version="1.2.3" provider-name="You">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
</requires>
<extension point="xbmc.python.pluginsource" library="addon.py">
<provides>video</provides>
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en_gb">Your add-on's summary</summary>
<description lang="en_gb">Your add-on's description</description>
<disclaimer lang="en_gb"></disclaimer>
<language></language>
<platform>all</platform>
<license></license>
<forum></forum>
<website></website>
<email></email>
<source></source>
<news></news>
<assets>
<icon></icon>
<fanart></fanart>
<banner></banner>
<clearlogo></clearlogo>
<screenshot></screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

There are a few important things to note in the above sample:

* The <code><addon></code> element must be present, and be the root node. It presents data about the add-on package as a whole.
* Inside the <code><addon></code> element is a <code><requires></code> element, listing all the dependencies that this add-on needs in order to function.
* Then there are one or more <code><extension></code> elements, each of which describes a part of Kodi that the add-on extends.
* Finally, there is a specific <code><extension></code> element that extends <code>"xbmc.addon.metadata"</code>. This describes the add-on to the user.

= Elements =

== <addon> ==

The <code><addon></code> element has 4 attributes, all required: <code>id</code>, <code>version</code>, <code>name</code>, and <code>provider-name</code>. For example:

<source lang="xml">
<addon id="script.hello.world" name="Hello World" version="0.0.1" provider-name="Dev1, Dev2">
</source>

=== id attribute ===

The id attribute is the unique identifier used for this add-on. It must be unique, and must use only lowercase characters, periods, underscores, dashes and numbers. This identifier is also used as the name of the folder that contains the add-on, so for ease of searching, we suggest you use something like <type>.<uniquename>.

=== version attribute ===

The version attribute is used by Kodi to determine whether updates are available. This should be use a version scheme like <code>x.y.z</code> (major.minor.patch). For example: <code>version="0.0.1"</code>. Generally, you'll start with a version of <code>0.y.z</code> for test releases and once you feel it is ready for a full release, you'd bump the version to <code>1.0.0</code>.

==== How versioning works ====

* <code>2.2.9</code> is newer than <code>2.2.1</code>
* <code>2.2.10</code> is newer than <code>2.2.1</code>
* <code>2.3.0</code> is newer than <code>2.2.9</code>
* <code>2.2.1</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1</code> is newer than <code>2.2.1~beta</code>
* <code>2.2.1~beta</code> is newer than <code>2.2.1~alpha</code>
* <code>2.2.1~beta3</code> is newer than <code>2.2.1~beta2</code>
* <code>2.2.1~beta10</code> is newer than <code>2.2.1~beta1</code>

{{tip|Text should only be added for a beta version. In other cases version number should only contain numbers.}}

=== name attribute ===

The name attribute is the name of the add-on as it appears in the UI. This should be in English where it makes sense for it to be so, and is not translatable.

=== provider-name attribute ===

The provider-name attribute is used as the author field. This could be a team of authors or a single author. If the add-on is maintained by multiple people please separate them with a comma (<code>,</code>).

== <requires> ==

The <code><requires></code> element contains one or more <code><import></code> elements which specify which other add-ons this particular add-on requires, and which version of those add-ons it requires. These add-ons may be part of Kodi itself, or may be parts of other third-party add-ons.

Kodi will only allow the add-on to be run if suitable versions of the (non-optional) add-ons on which this add-on depends are installed. When a user installs your add-on from an online repository via Kodi's add-on manager, Kodi attempts to resolve these dependencies, and install anything that your add-on relies on first. The dependency must be provided with the minimum version number your script/skin requires.

=== Examples ===

Here is a sample <code><requires></code> block that imports two required modules:

<source lang="xml">
<requires>
<import addon="xbmc.python" version="2.14.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10"/>
</requires>
</source>

Here's another example, which will only install on OpenELEC:

<source lang="xml">
<requires>
<import addon="os.openelec.tv" version="2.0"/>
</requires>
</source>

== <import> ==

Each <code><import></code> element describes one dependency for an add-on, with two required attributes: <code>addon</code> and <code>version</code>. There is also an optional attribute called, fittingly, <code>optional</code>.

If your add-on relies on other third-party add-ons, Kodi will automatically install them as well, provided they are available on an existing add-on repository. If they aren't available on any existing repository, the user must install the other add-ons themselves. Note that you need to include any Python libraries you need directly in your add-on; these can't be loaded with an <code><import></code> element, since Kodi wouldn't know what to do with them.

=== addon attribute ===

The <code>addon</code> attribute specifies the id of the required add-on, e.g. <code>script.module.elementtree</code>.

=== version attribute ===

The <code>version</code> attribute specifies the minimum version of the required add-on to be installed.

==== Dependency versions ====

Each different Kodi version might require you to use a higher version of the <code>xbmc.*</code> add-on dependencies to control on which version of Kodi the add-on can be installed.

{| class="prettytable" border="1"
|+ Current versions
! Kodi version !! xbmc.python !! xbmc.gui !! xbmc.json !! xbmc.metadata !! xbmc.addon
|-
| Dharma 10.1 Deprecated|| 1.0 || 2.11 || 2.0|| 1.0 || 0.1
|-
| Eden 11.0 Deprecated || 2.0 || 3.0 || 4.0 || 1.0 || 11.0
|-
| Frodo 12.x Deprecated|| 2.1.0 || 4.0.0 || 6.0.0 || 2.1.0 || 12.0.0
|-
| Gotham 13.x || 2.14.0 (ABI 2.1.0) || 5.0.1 || 6.6.0 (ABI 6.0.0) || 2.1.0 || 13.0.0 (ABI 12.0.0)
|-
| Helix 14.x || 2.19.0 (ABI 2.1.0) || 5.3.0 || 6.20.0 (ABI 6.0.0) || 2.1.0 || 14.0.0 (ABI 12.0.0)
|-
| Isengard 15.x || 2.20.0 (ABI 2.1.0) || 5.9.0 (ABI 5.3.0) || 6.25.1 (ABI 6.0.0) || 2.1.0 || 15.0.0 (ABI 12.0.0)
|-
| Jarvis 16.x || 2.24.0 (ABI 2.1.0) || 5.10.0 || 6.32.4 (ABI 6.0.0) || 2.1.0 || 16.0.0 (ABI 12.0.0)
|-
| Krypton 17.x || 2.25.0 (ABI 2.1.0) || 5.12.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 || 17.0.0 (ABI 12.0.0)
|-
| Leia 18.x || 2.25.0 (ABI 2.1.0) || 5.13.0 || 7.0.0 (ABI 6.0.0) || 2.1.0 || 17.9.701 (ABI 12.0.0)
|}

Each Kodi version contain a certain backwards compatibility. For example add-ons made for Gotham 13.x can still work ion Jarvis 16.x. Do note that this might change in the future. The '''ABI''' version you see in the table above is the backwards compatibility version for which add-ons are still marked "working".

=== optional attribute ===

The dependency may be made optional by setting the <code>optional</code> attribute to <code>true</code>. This will only install the dependency when the add-on actually needs it. Even if this dependency is missing, the add-on can still be installed.

== <extension> ==

The <code><extension></code> element describes the technical aspects of this add-on. It will have at least a point attribute which will give the part of Kodi that the add-on extends. For instance, the <code>addon.xml</code> file for the Confluence skin extends the <code>xbmc.gui.skin</code> part of xbmc. All available extension points are given below.

The various extension points that Kodi provides are given in the list below.
{| class="prettytable"
!Extension point
!Add-on Category
|-
|<code>[[Skinning|xbmc.gui.skin]]</code>
|Skin
|-
|<code>xbmc.webinterface</code>
|Web interface
|-
|<code>[[Add-on repositories|xbmc.addon.repository]]</code>
|''None''
|-
|<code>[[HOW-TO:_Automatically_start_addons_using_services|xbmc.service]]</code>
|Services
|-
|<code>xbmc.metadata.scraper.albums</code>
|Album information
|-
|<code>xbmc.metadata.scraper.artists</code>
|Artist information
|-
|<code>xbmc.metadata.scraper.movies</code>
|Movie information
|-
|<code>xbmc.metadata.scraper.musicvideos</code>
|Music video information
|-
|<code>xbmc.metadata.scraper.tvshows</code>
|TV information
|-
|<code>xbmc.metadata.scraper.library</code>
|''None''
|-
|<code>xbmc.ui.screensaver</code>
|Screensaver
|-
|<code>xbmc.player.musicviz</code>
|Visualization
|-
|<code>[[Plugin sources#What Kodi requires for your add-on|xbmc.python.pluginsource]]</code>
|Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
|-
|<code>[[Script sources#What Kodi requires for your add-on|xbmc.python.script]]</code>
|Music Add-ons (audio) / Picture Add-ons (image) / Program Add-ons (executable) / Video Add-ons (video)
|-
|<code>xbmc.python.weather</code>
|Weather
|-
|<code>xbmc.subtitle.module</code>
|Subtitle service module
|-
|<code>[[Script lyrics#What Kodi requires for your add-on|xbmc.python.lyrics]]</code>
|Lyrics
|-
|<code>[[Script library#What Kodi requires for your add-on|xbmc.python.library]]</code>
|''None''
|-
|<code>xbmc.python.module</code>
|These don't show up in the addon browser and are purely as support for other scripts.
|-
|<code>xbmc.addon.video</code>
|Video Add-ons (video)
|-
|<code>xbmc.addon.audio</code>
|Music Add-ons (audio)
|-
|<code>xbmc.addon.image</code>
|Picture Add-ons (image)
|-
|<code>kodi.resource.images</code>
|Additional image files
|-
|<code>kodi.resource.language</code>
|Additional language files
|}

Add-ons that don't correspond to a specific add-on category can not be installed by users. These are usually supporting or shared add-ons that are installed automatically by the add-ons that require them.

=== xbmc.python.pluginsource ===
{{See also|Plugin sources}}

The most common extension point that will be used by plugin addon developers is <code>xbmc.python.pluginsource</code>.

==== library attribute ====

The <code><extension point="xbmc.python.pluginsource"></code> element has an extra attribute: <code>library</code>. This is the name of the Python script (startup script) that will be run when the add-on is activated. This file must exist in the root of your add-on directory.

==== <provides> element ====

The extension has an additional child element named <code><provides></code>, which contains a whitespace separated list of <code>image</code>, <code>video</code>, <code>audio</code>, and/or <code>executable</code>. This determines in what area (or context) of the Kodi system your addon will make itself visible in (please note that this applies only to plugin extension points):

{| class="prettytable"
!Provides
!Appears in
|-
|<code>image</code>
|Pictures
|-
|<code>audio</code>
|Music
|-
|<code>video</code>
|Video
|-
|<code>executable</code>
|Programs
|-
|''(blank)''
|Not visible
|}

==== Example ====

<source lang="xml">
<extension point="xbmc.python.pluginsource" library="gpodderxbmc.py">
<provides>audio video</provides>
</extension>
</source>

=== xbmc.addon.metadata ===

This special extension point ''must'' be provided by all add-ons, and is the way that your add-on is described to users of the Kodi add-on manager.

==== Required elements ====

There are several elements that this should contain and all are compulsory (except the broken tag). Each of the elements below must always be present in English as a minimum.

Many of these elements can be translated into multiple languages and should be added once for each supported language. The <code>lang</code> attribute should contain a [https://en.wikipedia.org/wiki/Locale_(computer_software) locale identifier]. If omitted, it defaults to en_GB. (Note: Kodi v14 and older uses ISO-639 code. See [[List of language codes (ISO-639:1988)]]).

===== <summary> =====

One or more <code><summary></code> elements provide a short summary of what the add-on does. This should be a single sentence. It may be translated into multiple languages.

<source lang="xml">
<summary lang="en_GB">Hello World script provides some basic examples on how to create your first script.</summary>
</source>

===== <description> =====

One or more <code><description></code> elements provide a more detailed summary of what the add-on does. It may be translated into multiple languages.

<source lang="xml">
<description lang="en_GB">Hello World script provides some basic examples on how to create your first script
and hopefully will increase the number of Kodi users to start creating their own addons.</description>
</source>

===== <disclaimer> =====

One or more <code><disclaimer></code> elements that indicate what (if any) things the user should know about the add-on. There is no need to have a disclaimer if you don't want one, though if something requires settings, or only works in a particular country then you may want to state this here. It may be translated into multiple languages.

<source lang="xml">
<disclaimer lang="en_GB">Feel free to use this script. For information visit the wiki.</disclaimer>
</source>

===== <news> =====

{{note|Used in Kodi v17 Krypton and later only. Older versions are forward compatible.}}

The <code><news></code> element should contains a simple description of the major changes made to the add-on (new functionality, big fixes, etc). This is displayed in the Kodi addon installation/update system. (In the author's opinion, too many add-ons skip this piece of information, making it difficult for users to determine whether a particular problem that they may have been having has been fixed or not.)
Please keep it short, you might want to only include the changes for the last version here.

Here is an example:

<source lang="xml">
<news>v0.1.2 (2014-1-15)
- Added notification for Ubuntu users checking through apt command</news>
</source>

===== <platform> =====

The <code><platform></code> tag specifies which platforms (operating systems, hardware) this add-on runs on. Many add-ons will run on all platforms, so <code>all</code> is an option. If the platform tag is missing, we assume the add-on runs on all platforms. A combination of these is also possible. Currently available options are:

* <code>all</code>
* <code>linux</code>
* <code>osx</code>
* <code>osx64</code>
* <code>osx32</code>
* <code>ios</code>
* <code>windx</code>
* <code>android</code>

<source lang="xml">
<platform>all</platform>
</source>

===== <language> =====

The <code><language></code> elements indicate the language(s) of the ''content'' provided by your add-on. It applies to plugins, scripts, scrapers etc. This allows browsing the add-on list by language. When there is no specific language provided in your content, leave it blank.

<source lang="xml">
<language>en de fr</language>
or
<language></language>
</source>

===== <license> =====

The <code><license></code> element indicates what license is used for this add-on.

<source lang="xml">
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
</source>

===== <forum> =====

The <code><forum></code> element provides the forum thread URL for this specific add-on. Leave this blank if there is no forum thread.
<source lang="xml">
<forum>http://www.myaddonwebsite.com/forum.php?thread=12345</forum>
</source>

===== <website> =====

The <code><website></code> element provides the website URL for this specific add-on.

<source lang="xml">
<website>http://www.myaddonwebsite.com/</website>
</source>

===== <nowiki><source></nowiki> =====

The <code><nowiki><source></nowiki></code> element provides the URL for the source code for this specific add-on.
<syntaxhighlight lang="xml" enclose="div">
<source>http://github.com/someone/myaddon</source>
</syntaxhighlight>

===== <email> =====

The <code><email></code> element provides the email address of the author if he wishes to do so for this specific add-on. Here are two examples of how you can make it look (the second one it harder for spambots to use). This can be left blank if you do not want to make your email address public.
<source lang="xml">
<email>foo@bar.com</email>
or
<email>foo at bar dot com</email>
</source>

===== <broken> =====

The <code><broken></code> tag will mark the add-on as broken in the Kodi repo and provide the reason why. You don't need to do a version bump for this to work. However a bump is recommended as you could also add this to the changelog.

<source lang="xml">
<broken>deprecated</broken>
</source>

===== <assets> =====

{{note|Kodi v17 Krypton and later.}}

The <code><assets></code> element is a manifest that describes the various assets the add-on provides and where they are located. Supported sub-elements are:

* <code><icon></code> See [[Add-on_structure#icon.png]]
* <code><fanart></code> See [[Add-on_structure#fanart.jpg]]
* <code><screenshot></code>

If some elements are empty or not specified, it will be treated as non-existing/not provided.

Example:
<source lang="xml">
<assets>
<icon>resources/icon.png</icon>
<fanart>resources/fanart.jpg</fanart>
<screenshot>resources/screenshot-01.jpg</screenshot>
<screenshot>resources/screenshot-02.jpg</screenshot>
<screenshot>resources/screenshot-03.jpg</screenshot>
<screenshot>resources/screenshot-04.jpg</screenshot>
</assets>
</source>

With the above example definition, the files must be placed in the <code>resources</code> folder.

== Skin specific elements ==
=== Overview ===
{| class="prettytable"
| '''effectslowdown'''
| A multiplier that is applied to all <animation> effect lengths in the skin. Useful to slow down all animations globally so that you can better configure timings and see interactions between animating controls.
|-
| '''debugging'''
| When set to true, it'll display onscreen debug information (xml filename, mouse position and focused control type and name) in the skin.
|-
| '''res'''
| Support for arbitrary skin resolutions.
|}

=== How window xml files are found ===

Kodi can run in many differing resolutions, and a skin should try and cater to all these resolutions. The easiest way is to develop for one specific resolution and make sure that all controls contain <width> and <height> tags. That way, Kodi can scale the controls to the new screen resolution.

However, you may choose to develop alternative window xml files for differing resolutions (such as for HDTV resolutions, or for widescreen versus 4x3 resolutions).

The order that Kodi looks for it's skin files are as follows:

# It first looks in the current screenmode folder (one of 1080i, 720p, NTSC16x9, NTSC, PAL16x9 or PAL)
# If the current screenmode is 1080i and there's no 1080i folder, it then looks in the 720p folder.
# Finally, it looks in the '''res''' folder.

This allows you to just put any window files that do not require special treatment for 16x9 resolutions etc. in the <defaultresolution> folder, preventing needless repetition.

= Examples =

== addon.xml for skins ==

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8"?>
<addon
id="skin.confluence"
version="2.1.3"
name="Confluence"
provider-name="Jezz_X, Team Kodi">
<requires>
<import addon="xbmc.gui" version="5.13.0"/>
</requires>
<extension
point="xbmc.gui.skin"
debugging="false"
effectslowdown="0.75">
<res width="1280" height="720" aspect="16:9" default="true" folder="720p" />
</extension>
<extension point="xbmc.addon.metadata">
<summary lang="en">Confluence skin by Jezz_X. (Kodi's default skin)</summary>
<description lang="en">Confluence is the default skin for Kodi 9.11 and above. It is a combination of concepts from many popular skins, and attempts to embrace and integrate their good ideas into a skin that should be easy for first time Kodi users to understand and use.</description>
<disclaimer lang="en">Confluence is the default skin for Kodi, removing it may cause issues</disclaimer>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
<news></news>
<assets>
<icon></icon>
<fanart></fanart>
<screenshot></screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>
One thing to note is that all tag names are lower case. XML tag names are case sensitive!

== addon.xml for scripts ==

<syntaxhighlight lang="xml" enclose="div">
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<addon
id="script.artwork.downloader"
name="Artwork Downloader"
version="12.0.12"
provider-name="Martijn">
<requires>
<import addon="xbmc.python" version="2.1.0"/>
<import addon="xbmc.json" version="6.0.0"/>
<import addon="xbmc.addon" version="12.0.0"/>
<import addon="script.module.elementtree" version="1.2.7"/>
<import addon="script.module.simplejson" version="2.0.10" optional="true"/>
<import addon="script.common.plugin.cache" version="1.3.0"/>
</requires>
<extension point="xbmc.python.script" library="default.py">
<provides>executable</provides>
</extension>
<extension point="xbmc.service" library="service.py" start="login"/>
<extension point="xbmc.addon.metadata">
<summary lang="en">Downloads Artwork for TV shows, Movies and Musicvideos in your library</summary>
<description lang="en">Downloads all available artwork for TV shows, Movies and Musicvideos in your library. Check the options for supported artwork[CR]Artwork sources:[CR]www.fanart.tv[CR]www.thetvdb.com[CR]www.themoviedb.org[CR]Remark:[CR]Check your skin to see what type of artwork is supported![CR]Each TV Show/Movie must have its own folder![CR]Skin integration:[CR]See readme file</description>
<disclaimer lang="en">For bugs, requests or general questions visit the Artwork Downloader thread on the Kodi forum.</disclaimer>
<language></language>
<platform>all</platform>
<license>GNU GENERAL PUBLIC LICENSE. Version 2, June 1991</license>
<forum></forum>
<website></website>
<email></email>
<source></source>
<news></news>
<assets>
<icon></icon>
<fanart></fanart>
<screenshot></screenshot>
</assets>
</extension>
</addon>
</syntaxhighlight>

= Schema Definition =

The XML schema definition for <code>addon.xml</code> is located [https://github.com/xbmc/xbmc/blob/master/addons/xbmc.addon/metadata.xsd here].

{{frodo updated}}

[[Category:Add-on development]]
[[Category:Skin development]]