Official Kodi Wiki - User contributions [en]

Advancedsettings.xml

2024-01-28T19:16:35Z

Fritsch: Document: superviseaudiodelay for Android

{{TOC right}}{{mininav|[[Settings]]|page=advancedsettings.xml}}
{{bigger|{{note|'''The advancedsettings.xml file does not exist by default. You have to create it first!'''}} }}

<section begin="intro" />The [[advancedsettings.xml]] file, which does not exist by default, can be created by a user in their '''[[Userdata|userdata folder]]'''.

This file is used for advanced settings and options that do not have GUI controls inside of {{kodi}}. Some settings are experimental or very rarely set, so they can only be used via the advancedsettings.xml file. The file is simply a plain text file and can be edited by various text editors, so long as the name is "advancedsettings.xml". These advanced settings can be used to tweak various things such as episode naming patterns, special network ports, special behaviors, and more.<section end="intro" />

The following page will describe the structure of the advancedsettings.xml file and the various individual settings.

{{note|
# All XML tags must be lowercase. The start and end of the advancedsettings.xml file must have the <advancedsettings> and </advancedsettings> tags.
# Kodi will only read the advancedsettings.xml file when it starts up. If you make changes while it is running then you must restart Kodi.
# For some Windows versions, Kodi has two <code>\userdata\</code> folders. The correct one to put the advancedsettings.xml file in is not the one in Program Files, but in <code>%appdata%\Kodi\userdata\.</code>}}

== Layout ==

The layout of <code>advancedsettings.xml</code> is as follows:

<syntaxhighlight lang=xml enclose="div">
<advancedsettings version="1.0">
<setting>value</setting>
...
<setting>value</setting>
</advancedsettings>
</syntaxhighlight>

where "setting" gives the name of the setting, and "value" gives its value.

A list of the available "setting" strings and their values is given below.

= List of available settings =
List of available settings that are recognised in the advancedsettings.xml file <ref>https://github.com/xbmc/xbmc/blob/master/xbmc/settings/AdvancedSettings.cpp</ref>

Recommended: Use the table of contents or the search function in your browser to locate items.

== Troubleshooting settings ==

=== loglevel ===
{{Anchor|.3Cloglevel.3E}}

<section begin="loglevel" />
Sets the logging level used to log errors and information. The "hide" attribute is optional.

<syntaxhighlight lang=xml>
<loglevel hide="attribute">options</loglevel>
</syntaxhighlight>

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Attribute
! style="width:500px;" | Action
|-
! '''true'''
| Hides the "enable debugging" setting in the Settings page. (default)
|-
! '''false'''
| Allows "enable debugging" setting to switch between '''0''' and '''2'''.
|}

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Option
! style="width:500px;" | Action
|-
! '''-1'''
| No logging, suppresses all log output
|-
! '''0'''
| Normal logging, only logging errors (default)
|-
! '''1'''
| Debug logging with freemem, fps and cpu usage (no on screen)
|-
! '''2'''
| Same as 1 (with on screen display)
|-
! '''3'''
| Same as 1 + full smb logging
|}

{| class="wikitable"
|-
! style="width:100px;" | Example
! style="width:500px;" |
|-
! Example 1:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings version="1.0">
<loglevel>2</loglevel>
</advancedsettings>
</syntaxhighlight>
|-
! Example 2:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings version="1.0">
<loglevel hide="true">2</loglevel>
</advancedsettings>
</syntaxhighlight>
|}

'''Note:''' The setting is persistent through shutdown and restarts.<br>
'''Note:''' If debugging is enabled in the GUI, loglevel will be set to '''2'''. This will over-ride the <code>advancedsettings.xml</code> setting. You must disable the GUI Setting before adding the entry to <code>advancedsettings.xml</code>.<br />
<section end="loglevel" />
:''{{see also|Log_file|label 1=Debug Log}}''

=== jsonrpc ===
{{Anchor|.3Cjsonrpc.3E}}
To make it easier for developers using the [[JSON-RPC_API]] API in their (third party) applications to debug during development the json output of Kodi can be prettified by setting '''compactoutput''' to '''false'''. Default json output mode is a compact print which does not contain any unnecessary whitespaces and therefore is difficult to read for humans.
Furthermore using the '''tcpport''' setting it is possible to change the default TCP port used by Kodi for JSON RPC (which is 9090) to any other valid port.

Example:
<syntaxhighlight lang=xml enclose="div">
<jsonrpc>
<compactoutput>false</compactoutput>
<tcpport>9999</tcpport>
</jsonrpc>
</syntaxhighlight>

== Audio/video playback settings ==

=== skiploopfilter ===
{{anchor|.3Cskiploopfilter.3E}}
The amount of the loop filter to skip on h.264 decoding. This can help the performance of slower machines when decoding h264 content. Values, in decreasing CPU usage (and decreasing quality)
* -16 None
* 0 Skip only empty frames (default)
* 8 Skip non-reference frames
* 16 Skip bi-dir frames
* 32 Skip all non-key frames
* 48 Skip all frames
Example:
<syntaxhighlight lang=xml enclose="div">
<skiploopfilter>8</skiploopfilter>
</syntaxhighlight>

=== video ===
{{anchor|.3Cvideo.3E}}

The <video> section also includes the following child-tags, which have their own sections:
*[[#cleandatetime]]
*[[#cleanstrings]]
*[[#excludefromscan]]
*[[#excludefromlisting]]
*[[#excludetvshowsfromscan]]

{{note|Some tags that have a "third-level" and are grouped together are highlighted in color.}}

{| class="prettytable"
! Tag !! Description
|-
|
<syntaxhighlight lang=xml>
<video>
</syntaxhighlight>
| Parent tag that all other child tags need to be placed inside of. Do not use more than one '''<code><video></code>''' tag, but instead place all other child-tags within a single '''<code><video></video></code>''' set.
|-
|
<syntaxhighlight lang=xml>
<subsdelayrange>10</subsdelayrange>
</syntaxhighlight>
| Delay range for subtitles, in seconds.
|-
|
<syntaxhighlight lang=xml>
<maxtempo>2.1</maxtempo>
</syntaxhighlight>
| Allow further increase of playback speed over the default of 1.5<br>
maxtempo must be in the range of 1.5 to 2.1 <br>
Be aware of the limitations of your platform / hardware as not all are capable of the increased maxtempo <ref>https://forum.kodi.tv/showthread.php?tid=10023&pid=2795069#pid2795069</ref>
|-
|
<syntaxhighlight lang=xml>
<audiodelayrange>10</audiodelayrange>
</syntaxhighlight>
| Delay range for audio/video sync, in seconds.
|-
|
<syntaxhighlight lang=xml>
<usetimeseeking>true</usetimeseeking>
</syntaxhighlight>
| Whether to use time based or percentage based seeking. {{small see also|Skip steps}}
|-
|
<syntaxhighlight lang=xml>
<timeseekforwardbig>600</timeseekforwardbig>
<timeseekbackwardbig>-600</timeseekbackwardbig>
</syntaxhighlight>
| Time to seek forward in seconds when doing a long seek. Defaults to 600 (10 minutes) and -600 (-10 minutes) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforward>2</percentseekforward>
<percentseekbackward>-2</percentseekbackward>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a short seek. Defaults to 2 (2%) and -2 (2%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforwardbig>10</percentseekforwardbig>
<percentseekbackwardbig>-10</percentseekbackwardbig>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a long seek. Defaults to 10 (10%) and -10 (10%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<fullscreenonmoviestart>true</fullscreenonmoviestart>
</syntaxhighlight>
| Whether to go to fullscreen or not when starting a movie. Defaults to true.
|-
|
<syntaxhighlight lang=xml>
<defaultplayer>VideoPlayer</defaultplayer>
</syntaxhighlight>
| Set the default video player: VideoPlayer or an external player. See '''[[External players]]''' for more info.
|-
|
<syntaxhighlight lang=xml>
<excludefromscan>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromscan>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be added to library. It is possible to add multiple <code><regexp></code> tags to match multiple patterns
|-
|
<syntaxhighlight lang=xml>
<excludefromlisting>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be displayed in files view.
|-
|
<syntaxhighlight lang=xml>
<playcountminimumpercent>90</playcountminimumpercent>
</syntaxhighlight>
| Minimum percentage that has to be played before it is marked as watched. Set to 101 to never auto-mark items as watched. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignoresecondsatstart>180</ignoresecondsatstart>
</syntaxhighlight>
| Number of seconds to ignore at video start after which a resume point is created. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignorepercentatend>8</ignorepercentatend>
</syntaxhighlight>
| Percentage of video to ignore at the end. If you stop watching the video here no resume point is created. Set to 101 to never save a resume point. The video is already marked as watched at 90%, see above. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<vdpauscaling>true</vdpauscaling>
</syntaxhighlight>
| Scales with vdpau instead of opengl and turns on its HQ scaler when available, enabling this might slow down rendering and cause framedrops especially on ION systems, this setting requires a vdpau feature set C GPU.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegdeinterlacing>linblenddeint</ppffmpegdeinterlacing>
</syntaxhighlight>
| Override the deinterlacing options passed to libpostproc.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegpostprocessing>ha:128:7,va,dr</ppffmpegpostprocessing>
</syntaxhighlight>
| Override the post processing options passed to libpostproc when 'Video post-processing' is activated in GUI Videos-Settings-Playback.
|-
|
<syntaxhighlight lang=xml>
<autoscalemaxfps>30</autoscalemaxfps>
</syntaxhighlight>
| When scaling method is set to auto, bilinear is chosen when the fps is higher than this limit, the default is 30.
|-
|
<syntaxhighlight lang=xml>
<adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" | Settings for when "Adjust refreshrate to match video fps" is enabled in the video playback GUI settings.
|-
|
<syntaxhighlight lang=xml>
<override>
<fps>23.976</fps>
<refresh>60.0</refresh>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' "Adjust refreshrate to match video fps" will try to select the best refreshrate for the video fps but it doesn't always get it right, for example it might switch to an unsupported refreshrate. You can add overrides here to switch to a certain refreshrate based on video fps. It's possible to add as many overrides as you need. Overrides are processed in order, if the first one doesn't match the fps or no refreshrates match that override, it will try the next one until no overrides are left.

* '''fps''' - if the fps is between 23.966 and 23.986
* '''refresh''' - switch to the first found refreshrate that is between 59.99 and 60.01
|-
|
<syntaxhighlight lang=xml>
<override>
<fpsmin>29.96</fpsmin>
<fpsmax>30.01</fpsmax>
<refreshmin>59.0</refreshmin>
<refreshmax>61.0</refreshmax>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -'''
* '''fpsmin''' / '''fpsmin''' - You can also specify the fps range yourself.
* '''refreshmin''' / '''refreshmax''' - Same for the refreshrate
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refresh>50.0</refresh>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' If none of the overrides match, or none of the refreshrates match any of the fps matching overrides, it will choose a fallback refreshrate. Fallbacks are process in order, if the first fallback doesn't match any refreshrate, it will try the next one until no fallbacks are left.

* '''refresh''' - Switch to the first found refreshrate that is between 49.99 and 50.01.
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refreshmin>49.0</refreshmin>
<refreshmax>51.0</refreshmax>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' You can also specify the range for the fallback yourself.

If none of the overrides match the video fps, or no refreshrates match any of the fps matching overrides, and no fallbacks are specified or no refreshrates match any fallbacks, it will automatically choose the best refreshrate (same as having no overrides and fallbacks).
|-
|
<syntaxhighlight lang=xml>
</adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" |
|-
|
<syntaxhighlight lang=xml>
<checkdxvacompatibility>value</checkdxvacompatibility>
</syntaxhighlight>
| Advanced setting not present: let Kodi autodetect cards that support H.264 profile > L4.1. Set value to false to enable DXVA no matter what. Set value to true if Kodi doesn't autodetect that the graphics card doesn't support > L4.1.
|-
|
<syntaxhighlight lang=xml>
<useocclusionquery>-1</useocclusionquery>
</syntaxhighlight>
| Use an occlusion query when capturing videoframes, -1 means auto detect, 0 means disabled, 1 means enabled, the default is -1.
|-
|
<syntaxhighlight lang=xml>
<fpsdetect>1</fpsdetect>
</syntaxhighlight>
| FPS detection for video playback
* 0 = trust codec fps
* 1 = recalculate from video timestamps with uniform spacing
* 2 = recalculate from video timestamps always
|-
|
<syntaxhighlight lang=xml>
<latency>
</syntaxhighlight>
| style="background:#F0E68C;"| Start of '''latency''' tags. Display latency (video lag). Latency is given in msecs.
|-
|
<syntaxhighlight lang=xml>
<delay>0</delay>
</syntaxhighlight>
| style="background:#F0E68C;" | Global default display latency.
|-
|
<syntaxhighlight lang=xml>
<refresh></refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | Override latency for given display (not video) refresh rates. When Kodi is in windowed mode, override is ignored. Multiple overrides are allowed.

Syntax of an override entry:
<syntaxhighlight lang=xml>
<refresh>
<min>, <max> refresh rate range, OR
<rate> exact refresh rate
<delay> display latency for the given refresh rate
</refresh>
</syntaxhighlight>
|-
|
<syntaxhighlight lang=xml>
<refresh>
<min>23</min>
<max>24</max>
<delay>125</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 125 msec latency at 23-24 Hz
|-
|
<syntaxhighlight lang=xml>
<refresh>
<rate>50</rate>
<delay>50</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 50 msec latency at 50 (+/-0.01) Hz
|-
|
<syntaxhighlight lang=xml>
</latency>
</syntaxhighlight>
| style="background:#F0E68C;" |
|-
|
<syntaxhighlight lang=xml>
<stereoscopicregex3d>[-. _]3d[-. _]</stereoscopicregex3d>
<stereoscopicregexsbs>[-. _]h?sbs[-. _]</stereoscopicregexsbs>
<stereoscopicregextab>[-. _]h?tab[-. _]</stereoscopicregextab>
</syntaxhighlight>
| Filename triggers for 3D (stereoscopic) mode.
|-
|
<syntaxhighlight lang=xml>
<assfixedworks>false</assfixedworks>
</syntaxhighlight>
| Position behavior of ass subtitiles when setting "subtitle position on screen" set to "fixed". True to show at the fixed position set in video calibration. False to show at the bottom of video (default). {{note|Removed in Kodi v20.}}
|-
|
<syntaxhighlight lang=xml>
<subtitleverticalmargin>120</subtitleverticalmargin>
</syntaxhighlight>
| Allows to customise the vertical margin of text based subtitles, which will be applied to each type of subtitle position in subtitle settings. {{note|Available in Kodi v20 and above.}}
|-
|
<syntaxhighlight lang=xml>
</video>
</syntaxhighlight>
|
|}

=== audio ===
{{anchor|.3Caudio.3E}}
<syntaxhighlight lang=xml enclose="div">
<audio>

<headroom>0</headroom>

<defaultplayer>paplayer</defaultplayer>

<excludefromscan>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromscan>

<excludefromlisting>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromlisting>

<ac3downmixgain>12.0</ac3downmixgain>

<usetimeseeking>true</usetimeseeking>

<timeseekforwardbig>600</timeseekfowardbig>

<timeseekbackwardbig>-600</timeseekbackward>

<playcountminimumpercent>99</playcountminimumpercent>

<applydrc>-1.0</applydrc>

<limiterhold>0.025</limiterhold>

<limiterrelease>0.1</limiterrelease>

<maxpassthroughoffsyncduration>10</maxpassthroughoffsyncduration>

<allowmultichannelfloat>false</allowmultichannelfloat>

<superviseaudiodelay>false</superviseaudiodelay>
</audio>
</syntaxhighlight>

=== forcedswaptime ===
{{anchor|.3Cforcedswaptime.3E}}
Use to force a backbuffer->frontbuffer swap while vsync is enabled. Set to the time (in ms) to allow for the swap (e.g. <forcedswaptime>1</forcedswaptime> is typical).

Default: Off

=== edl ===
{{anchor|.3Cedl.3E}}
{{main|Edit_decision_list}}
Commercial break detection not as good you think it could be? Are some commercial breaks in a series of adverts not being skipped? Are some parts being skipped that are clearly not commercials? Does the end of the previous recording still show? The following advanced settings can be used to better identify full commercial break sequences, remove incorrectly flagged commercial breaks, and have playback start at the actual beginning of the recording.

<syntaxhighlight lang=xml enclose="div">
<edl>

<mergeshortcommbreaks>false</mergeshortcommbreaks>

<maxcommbreaklength>250</maxcommbreaklength>

<mincommbreaklength>90</mincommbreaklength>

<maxcommbreakgap>120</maxcommbreakgap>

<commbreakautowait>0</commbreakautowait>

<commbreakautowind>0</commbreakautowind>

<displaycommbreaknotifications>false</displaycommbreaknotifications>
</edl>
</syntaxhighlight>
'''Notes:'''
* displaycommbreaknotifications<ref>https://github.com/xbmc/xbmc/pull/20711</ref>

== PVR & Live TV ==
{{anchor|.3Cpvr.3E}}
Settings available for PVR, EPG and Live TV. Edit Decision List settings are located in the previous section.

=== pvr ===
<syntaxhighlight lang="xml" line='line'>
<pvr>
<timecorrection>0</timecorrection> 
<infotoggleinterval>3000</infotoggleinterval> 
<channeliconsautoscan>true</channeliconsautoscan> 
<autoscaniconsuserset>false</autoscaniconsuserset> 
<numericchannelswitchtimeout>1000</numericchannelswitchtimeout> 
</pvr>
</syntaxhighlight>

==== pvrrecordings ====
In v19 and later, allows users to modify sort type and order of pvr recordings. <ref>https://github.com/xbmc/xbmc/pull/18605</ref>

;Note- These settings are child tags to the ''<pvr>'' tag in the previous section.

<syntaxhighlight lang="xml" line='line'>
<pvr>
<pvrrecordings>
<sortmethod>2</sortmethod> 
<sortorder>2</sortorder> 
</pvrrecordings>
</pvr>
</syntaxhighlight>

=== epg ===
{{anchor|.3Cpvr.3E}}
<syntaxhighlight lang="xml" line='line'>
<epg>
<updatecheckinterval>300</updatecheckinterval> 
<updateemptytagsinterval>60</updateemptytagsinterval> 
<cleanupinterval>900</cleanupinterval> 
<activetagcheckinterval>60</activetagcheckinterval> 
<retryinterruptedupdateinterval>60</retryinterruptedupdateinterval> 
<displayupdatepopup>true</displayupdatepopup> 
<displayincrementalupdatepopup>false</displayincrementalupdatepopup> 
</epg>
</syntaxhighlight>

== Video library settings ==

=== videoextensions ===
{{anchor|.3Cvideoextensions.3E}}<section begin="videoextensions" />
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Video windows.

Default extensions for VIDEOS:
<pre>
.m4v .3g2 .3gp .nsv .tp .ts .ty .strm .pls .rm .rmvb .mpd .m3u .m3u8 .ifo .mov .qt .divx .xvid
.bivx .vob .nrg .img .iso .udf .pva .wmv .asf .asx .ogm .m2v .avi .bin .dat .mpg .mpeg .mp4
.mkv .mk3d .avc .vp3 .svq3 .nuv .viv .dv .fli .flv .001 .wpl .xspf .zip .vdr .dvr-ms .xsp .mts
.m2t .m2ts .evo .ogv .sdp .avs .rec .url .pxml .vc1 .h264 .rcv .rss .mpls .mpl .webm .bdmv
.bdm .wtv .trp .f4v
</pre>
Examples:
<pre>
<videoextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</videoextensions>
</pre>
<section end="videoextensions" />

=== discstubextensions ===
{{main|Media stubs}}

<section begin="discstubextensions" />
The default filename extension for Disc Stubs is:
<syntaxhighlight lang=xml enclose="div">
.disc
</syntaxhighlight>
Using the following tags, it is possible to <tt><add></tt> additional or <tt><remove></tt> existing disc stub extensions to better suit your requirements.
<syntaxhighlight lang=xml enclose="div">
<discstubextensions>
<add>.disk|.stub</add>
<remove>.disc</remove>
</discstubextensions>
</syntaxhighlight>
<section end="discstubextensions" />

=== languagecodes ===
{{anchor|.3Clanguagecodes.3E}}
User-defined translation table for language codes used in subtitles and audio.
It can be used to add, extend or override Kodi's language codes.

'''How to add a new language code:'''

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>alt</short>
<long>Alternate</long>
</code>
</languagecodes>
</syntaxhighlight>

'''How to add a new language code with subtag (e.g. pt-BR):'''
{{note|This support is available from Kodi v20}}

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>pt-BR</short>
<long>Portuguese - Brazil</long>
</code>
</languagecodes>
</syntaxhighlight>

''NOTE FOR MKV FILES:''<br/>
MKV files that contain audio/subtitle tracks with language codes with subtags are not yet supported, but from <code>Kodi v21</code> a workaround was introduced that allows Kodi to recognize language codes with subtags.
To use the workaround, you must open the MKV file with an editor and in the metadata of the desired audio/subtitle track, edit the track Name (or Title field) by adding the language code wrapped in curly brackets, as in following example:
<br/><code>Original track name: Audio portuguese/brazil</code>
<br/><code>Modified track name: Audio portuguese/brazil {pt-BR}</code>

'''How to extend an existing language code:'''

Set the same "long" description of the existing language, for example we reuse the Portughese language for another language code:

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>pt-BR</short>
<long>Portuguese</long>
</code>
</languagecodes>
</syntaxhighlight>

In this case when in Kodi settings you set the "Portuguese" language, when in playing according to availability the track "pt" or "pt-BR" will be chosen.

'''How to override an existing language code:'''

This allow you to rename an existing language. Set to an existing language code your preferred "long" name description.

''WARNING: This can cause problems with add-ons, so do not override languages if you are not aware of the side effects.''

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>en</short>
<long>English example</long>
</code>
<code>
<short>en-GB</short>
<long>English example</long>
</code>
</languagecodes>
</syntaxhighlight>

=== moviestacking ===
{{anchor|.3Cmoviestacking.3E}}<section begin="moviestacking" />
{{main|Naming_video_files/Movies}}
This is used by the [[Naming_video_files/Movies#Split_Video_Files|file stacking]] algorithm to combine multi-part files and contains a list of regular expressions. For stacking videos that are contained in folders, such as VIDEO_TS folders, see '''[[advancedsettings.xml#folderstacking|<folderstacking>]]'''

As of v9.11, video stacking regular expressions '''must''' contain exactly four (4) capture expressions.

Default:
<syntaxhighlight lang=xml enclose="div">
<moviestacking>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[0-9]+)(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[a-d])(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ ._-]*[a-d])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="append"</tt> or <tt>append="yes"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the end.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="append">

<regexp>(.*?)([ ._-]*[0-9])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="prepend"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the beginning.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="prepend">
<regexp>(Title)(Volume)(Ignore)(Extension)</regexp>
</moviestacking>
</syntaxhighlight>

If no argument is supplied, or the argument <tt>append="no"</tt> is supplied, the default moviestacking regular expressions are overwritten by the user specified ones.
<section end="moviestacking" />

=== folderstacking ===
{{main|Naming_video_files/Movies}}
This is similar to '''[[advancedsettings.xml#moviestacking|<moviestacking>]]''', but is used for videos that are contained in folders that use the folder names to stack, such as VIDEO_TS folders (DVD rips that are not in ISO format).

Default:
<syntaxhighlight lang=xml enclose="div">
<folderstacking>

<regexp>((cd|dvd|dis[ck])[0-9]+)$</regexp>
</folderstacking>
</syntaxhighlight>

=== cleandatetime ===
{{anchor|.3Ccleandatetime.3E}}
Matches a year number in a string using a Regular Expression

Default expression:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleandatetime>(.*[^ _\,\.\[\]\-])[ _\.\[\]\-]+(19[0-9][0-9]|20[0-9][0-9])([ _\,\.\[\]\-]|[^0-9]$)?</cleandatetime>
</video>
</syntaxhighlight>
:* The string found before will be used as basis string getting cleaned by the cleanstrings expressions.
:* By default date formats like MM:YY are ignored.

=== cleanstrings ===
{{anchor|.3Ccleanstrings.3E}}
Clean unwanted characters from filenames or folders by using a list of Regular Expressions. Please note that everything right of the match (at the end of the file name) is removed, so if you would have a file named ''Super movie.mp4'' and would add <tt><regexp> </regexp></tt> (only a space), the only thing that would be left is ''Super'', which is probably not what you want.

{{Github_link|[https://github.com/xbmc/xbmc/blob/Nexus/xbmc/settings/AdvancedSettings.cpp#L201-L211 Code in Github]}}

Default expressions:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleanstrings>
<regexp>([ _\\,\\.\$\$\\[\\]\\-](10bit|480p|480i|576p|576i|720p|720i|1080p|1080i|2160p|3d|aac|ac3|aka|atmos|avi|bd5|bdrip|bluray|brrip|cam|cd[1-9]|custom|dc|ddp|divx|divx5|dolbydigital|dolbyvision|dsr|dsrip|dts|dts-hdma|dts-hra|dts-x|dv|dvd|dvd5|dvd9|dvdivx|dvdrip|dvdscr|dvdscreener|extended|fragment|fs|h264|h265|hdr|hdr10|hevc|hddvd|hdrip|hdtv|hdtvrip|hrhd|hrhdtv|internal|limited|multisubs|nfofix|ntsc|ogg|ogm|pal|pdtv|proper|r3|r5|read.nfo|remastered|remux|repack|rerip|retail|screener|se|svcd|tc|telecine|telesync|truehd|ts|uhd|unrated|ws|x264|x265|xvid|xvidvd|xxx|web-dl|webrip|www.www|\\[.*\\])([ _\\,\\.\$\$\\[\\]\\-]|$)");</regexp>
<regexp>(\[.*\])</regexp>
</cleanstrings>
</video>
</syntaxhighlight>
Updated in v20<ref>https://github.com/xbmc/xbmc/pull/20549</ref>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== tvshowmatching ===
{{anchor|.3Ctvshowmatching.3E}}
Matches the season and episode numbers in file paths by using a list of Regular Expressions

{{Github_link|[https://github.com/xbmc/xbmc/blob/Matrix/xbmc/settings/AdvancedSettings.cpp#L232 Code in Github]}}

Defaults:
<syntaxhighlight lang=xml enclose="div">
<tvshowmatching>
<regexp>s([0-9]+)[ ._x-]*e([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)([^\\\\/]*)$</regexp> 
<regexp>[\._ -]()[Ee][Pp]_?([0-9]+)([^\\/]*)$</regexp> 
<regexp>([0-9]{4})[\.-]([0-9]{2})[\.-]([0-9]{2})</regexp> 
<regexp>([0-9]{2})[\.-]([0-9]{2})[\.-]([0-9]{4})</regexp> 
<regexp>[\\/\._ \[\(-]([0-9]+)x([0-9]+)([^\\/]*)$</regexp> 
<regexp>[\\/\._ -]([0-9]+)([0-9][0-9])([\._ -][^\\/]*)$</regexp> 
<regexp>[\/._ -]p(?:ar)?t[_. -]()([ivx]+)([._ -][^\/]*)$</regexp> 
</tvshowmatching>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)
:* Paths are converted to lower case before matching.
:* For multi-episode matching to work, there needs to be a third set of parentheses '()' at the end, this part is fed back into the regexp engine.
:* A [https://forum.kodi.tv/showthread.php?tid=51614 forum thread] has a discussion of pre-made regex lists to match common names. These might improve Kodi's ability to match TV show names in some situations, at the risk of additional false positives.

==== Filenames without Season ====
There are two methods to add episodes without a season in their file path. Both ways will force the season to '1' by default, so that you can use
the 'Use Absolute Ordering (Single Season)' setting from the TheTvDb.com scraper.

; Simple Method ''(XBMC v9.11 onwards and Kodi)''
: Use only one pair of parentheses
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]([0-9]+)</regexp></syntaxhighlight>
; Advanced Method ''(XBMC v10.05 onwards and Kodi)''
: Supports multi-episode files without season
: Use an empty pair of parentheses for the season
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

; Specifying Default Season ''(XBMC v12.0 onwards and Kodi)''
It is possible to set the default season for specific regular expressions by setting the 'defaultseason' attribute.
: Works with both the simple method and advanced method
: If not used, the season will be set to '1'
: Useful for setting specials to season '0'
<syntaxhighlight lang=xml enclose="div"><regexp defaultseason="0">[/\._ \-]X()([0-9]+)(-[0-9]+)?</regexp>
<regexp defaultseason="1">[/\._ \-]E()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

=== tvmultipartmatching ===
{{anchor|.3Ctvmultipartmatching.3E}}
Matches a multipart episode number based on a previously identified episode file, using a list of Regular Expressions.

Default:
<syntaxhighlight lang=xml enclose="div">
<tvmultipartmatching>^[-_ex]+([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)</tvmultipartmatching>
</syntaxhighlight>
:* Text matching is compared case-insensitive.
:* Specifying this option '''replaces''' the default value

=== excludefromscan ===
{{anchor|.3Cexcludefromscan.3E}}
Matches filenames or folders which should be excluded from a library scan (except tvshows) using a list of Regular Expressions. This can be for both Video or Audio sections of <tt>advancedsettings.xml</tt>.

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromscan>
<regexp>-trailer</regexp>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludefromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== excludefromlisting ===
{{anchor|.3Cexcludefromlisting.3E}}
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromlisting> 
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</video>
</syntaxhighlight>

=== excludetvshowsfromscan ===
{{anchor|.3Cexcludetvshowsfromscan.3E}}
Matches filenames or folders which should be excluded from a tvshow library scan using a list of Regular Expressions

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludetvshowsfromscan>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludetvshowsfromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== trailermatching ===
{{anchor|.3Ctrailermatching.3E}}
Contains Regular Expression syntax to match the locally stored trailers to movies in the library.

<syntaxhighlight lang=xml enclose="div">
<trailermatching>

<regexp>(.*?)(_Trailer)(\.[^.]+)$</regexp>
</trailermatching>
</syntaxhighlight>

=== videolibrary ===
{{anchor|.3Cvideolibrary.3E}}
Options specific to the Video Library

{{Note|Kodi v20 users don't need set "importwatched" or "importresumepoint" to true anymore as that's the default then <ref>https://github.com/xbmc/xbmc/pull/20842</ref>}}

<syntaxhighlight lang="xml" line='line'>
<videolibrary>
<allitemsonbottom>false</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<usefasthash>true</usefasthash> 
<recentlyaddeditems>35</recentlyaddeditems> 
<itemseparator> / </itemseparator> 
<exportautothumbs>false</exportautothumbs> 
<importwatchedstate>false</importwatchedstate> 
<importresumepoint>false</importresumepoint> 
<dateadded>1</dateadded> 
</videolibrary>
</syntaxhighlight>

=== videoscanner ===
{{anchor|.3Cvideoscanner.3E}}
Options specific to the Video scanner
<syntaxhighlight lang=xml enclose="div">
<videoscanner>
<ignoreerrors>true</ignoreerrors> 
</videoscanner>
</syntaxhighlight>

== Library artwork ==

{{note|Using <imageres>9999</imageres> and <fanartres>9999</fanartres> will allow caching artwork at original size.}}

=== imageres ===
{{anchor|.3Cimageres.3E}}

<section begin="imageres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached artwork]] (other than fanart / 16:9 images) should be resized to in pixels. The width is automatically calculated as being 16/9*height. The image will be resized to fit within this size. e.g. an image that is 2000x500 will be cached at size 1280x320. An image that is 500x800 will be cached at size 450x720 using the default value of 720.<section end="imageres description" />

<syntaxhighlight lang=xml enclose="div">
<imageres>720</imageres>
</syntaxhighlight>

=== fanartres ===
{{anchor|.3Cfanartres.3E}}

<section begin="fanartres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached fanart]] should be resized to in pixels. The width is automatically calculated as being 16/9*height. Only images that are exactly 16x9 and equal to or greater than this resolution will be cached at this size - all other images will be cached using <imageres>. The default value is 1080.<section end="fanartres description" />

<syntaxhighlight lang=xml enclose="div">
<fanartres>1080</fanartres>
</syntaxhighlight>

=== imagescalingalgorithm ===
Specify the image scaling algorithm for image resizing when [[Artwork/Cache#Texture optimization| caching artwork]] to the local texture cache.
<br />
<syntaxhighlight lang=xml enclose="div">
<imagescalingalgorithm>bicubic</imagescalingalgorithm>
</syntaxhighlight>

[https://github.com/xbmc/xbmc/blob/master/xbmc/pictures/PictureScalingAlgorithm.cpp#L20-L32 Available image scaling algorithms]

<syntaxhighlight lang=text enclose="div">
fast_bilinear
bilinear
bicubic
experimental
nearest_neighbor
averaging_area
bicublin
gaussian
sinc
lanczos
bicubic_spline
</syntaxhighlight>

=== imagequalityjpeg ===
This specifies the quality of the images when stored in jpeg format. By default kodi uses a quality of 4 which is a good compromise between size and quality. If you want to reduce the thumbnail sizes (decreasing quality) choose a higher value up to 21. If high quality (large thumbnail size) is needed, chose a smaller value, e.g. 0,1,2 or 3. (Added in v20 <ref>https://github.com/xbmc/xbmc/pull/21418</ref>)
<br />
<syntaxhighlight lang=xml enclose="div">
<imagequalityjpeg>4</imagequalityjpeg>
</syntaxhighlight>

== Video and music library settings ==

=== playlistasfolders ===
{{anchor|.3Cplaylistasfolders.3E}}
In the recent releases, playlists are treated as folders. Selecting a playlist no longer plays it, but opens it, as if it were a folder.

Set to false to revert to the previous behaviour. When you select a playlist, its content is added to the list of elements to be played.

:{{note|This setting will not affect smart playlists, they will always show as folders.}}

;Example
<syntaxhighlight lang=xml enclose="div">
<playlistasfolders>true</playlistasfolders>
</syntaxhighlight>

=== playlistretries ===
{{anchor|.3Cplaylistretries.3E}}
The number of retries attempted if a source is offline. With this control you can alter the number of consecutive failed items before a playlist fails.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlistretries>100</playlistretries>
</syntaxhighlight>

=== playlisttimeout ===
{{anchor|.3Cplaylisttimeout.3E}}
The timeout, in seconds, before item failure.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlisttimeout>20</playlisttimeout>
</syntaxhighlight>

=== sorttokens ===
Allows you to specify additional tokens that will be ignored at the start of lines during sorting.
{{note|Sort tokens are case sensitive.}}
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token>the</token>
</sorttokens>
</syntaxhighlight>

In the above example "the ", "the." and "the_" will be ignored at the start of titles or names when sorting items, in both video and music libraries. A separator can also be specified, for example
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token separators="'">L</token>
</sorttokens>
</syntaxhighlight>
In that case the value L', as in French movie name ''L'argent'', will be ignored and the item listed under "A".

=== musicdatabase/videodatabase ===
{{anchor|.3Cmusicdatabase.3E/.3Cvideodatabase.3E|musicdatabase/videodatabase|database tags music/video/tv/epg/adsp}}
{{main|MySQL}}
<section begin="videodatabase" />
Allows advanced customization of the default database settings for music, video, TV, EPG, and ADSP databases.

:{{note| '''It is HIGHLY recommended that you not attempt to place an sqlite3 database outside of kodi's path. sqlite3 contains no filesystem abstraction, so this will plain break on any non-local (as far as Kodi is concerned) paths. Use this for mysql only.'''}}

'''Parent tags:'''

* '''<videodatabase>'''
* '''<musicdatabase>'''
* '''<tvdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<epgdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<adspdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
{{MySQL warning}}

'''Child tags: '''

;<type>
: ''Required'' - Can be either "sqlite3" or "mysql" (default: sqlite3)

;<host>
:''Required'' -
* sqlite3: defines the relative path to the database file (eg. /usr/local/kodi/databases).
* mysql: defines the host of the mysql socket (eg. localhost, 192.168.0.1, etc)

;<port>
: ''Optional'' -
* sqlite3: silently ignored
* mysql: defines the port of the mysql socket (default: 3306)

;<name>
: ''Optional'' -
:by default "MyVideos"+DB number will be used.
* sqlite3: defines the name of the database file to read from, excluding the ".db" extension.
* mysql: defines the name of the database to use

;<user>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the user with privileged access to the database

;<pass>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the password for the user with privileged access to the database

;<compression>
: ''Optional'' - Defaults to false. Set to "true" to enable MySQL compression protocol. Performance benefit is going to be largely dependent on the network bandwidth, latency between database and clients and on the size of the result sets. [https://github.com/xbmc/xbmc/pull/6484]
: {{Note|Slower clients (such as the RPi and others) won't benefit from it as the zlib de-compression overhead is higher than the actual compression savings}}

;<key>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<cert>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ca>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<capath>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ciphers>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

'''Examples:'''

1) Configure a database for MySQL.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<videodatabase>
<type>mysql</type>
<host>192.168.0.10</host>
<name>kodi_video</name>
<user>kodi</user>
<pass>kodi</pass>
</videodatabase>
</syntaxhighlight>

2) Configure a database for an sqlite database.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<musicdatabase>
<type>sqlite3</type>
<host>/usr/local/share/kodi/databases</host>
</musicdatabase>
</syntaxhighlight>

<section end="videodatabase" />

=== externalplayer ===
{{anchor|.3Cexternalplayer.3E}}
{{see|External players}}

== Music settings ==

=== musicextensions ===
{{anchor|.3Cmusicextensions.3E}}
<section begin="musicextensions" />
Default extensions for MUSIC:
<pre>
.nsv .m4a .flac .aac .strm .pls .rm .rma .mpa .wav .wma .ogg .mp3 .mp2 .m3u .gdm .imf .m15 .sfx
.uni .ac3 .dts .cue .aif .aiff .wpl .xspf .ape .mac .mpc .mp+ .mpp .shn .zip .wv .dsp .xsp .xwav
.waa .wvs .wam .gcm .idsp .mpdsp .mss .spt .rsd .sap .cmc .cmr .dmc .mpt .mpd .rmt .tmc .tm8
.tm2 .oga .url .pxml .tta .rss .wtv .mka .tak .opus .dff .dsf .m4b .dtshd
</pre>

It is possible to add or remove extensions for Music, using the following XML tags. Useful if you keep, say, FLAC and mp3 versions of music in the same folder. The <remove> tag can be used to remove mp3 from being listed in the library, leaving only the higher quality FLAC being displayed.

<musicextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</musicextensions>

<section end="musicextensions" />

=== cddbaddress ===
{{anchor|.3Ccddbaddress.3E}}
The address of the online CDDb database. You may set this to another freedb mirror if there is a more suitable one.

Default:
<syntaxhighlight lang=xml enclose="div>
<cddbaddress>freedb.freedb.org</cddbaddress>
</syntaxhighlight>

=== songinfoduration ===
{{anchor|.3Csonginfoduration.3E}}
This controls how long the song information will remain onscreen when the song changes during visualisations. The valid range is "1" to "Indefinite (0)", in seconds. This does not include the duration of any transition effects.

Default:
<syntaxhighlight lang=xml enclose="div">
<songinfoduration>10</songinfoduration>
</syntaxhighlight>

=== musicfilenamefilters ===
{{anchor|.3Cmusicfilenamefilters.3E}}
Contains filters to match music information (artist, title etc.) from a tag-less music filename. The first <filter> to match completely is used. Matched items include:

<pre>
%A - Artist
%T - Title
%B - Album
%N - Track number
%S - Part of set (disk number)
%D - Duration
%G - Genre
%Y - Year
%R - Rating
</pre>

Example:
<syntaxhighlight lang=xml enclose="div">
<musicfilenamefilters>
<filter>%A - %T</filter>
</musicfilenamefilters>
</syntaxhighlight>

=== musiclibrary ===
Options specific to the Music Library
<section begin="MusicLibrary" />
<syntaxhighlight lang="xml" line='line'>
<musiclibrary>
<allitemsonbottom>true</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<recentlyaddeditems>35</recentlyaddeditems> 
<albumformat>%B - %Y</albumformat> 
<prioritiseapetags>true</prioritiseapetags> 
<itemseparator> / </itemseparator> 
<artistseparators> 
<separator>;</separator>
<separator>:</separator>
<separator>|</separator>
<separator> feat. </separator>
<separator> ft. </separator>
</artistseparators>
<dateadded>1</dateadded> 


<useisodates>false</useisodates> 
</musiclibrary>
</syntaxhighlight>
{{Note|Changing the <itemseparator> or <artistseparators> will only affect newly added items. A rescan won't change the existing ones. Remove the Source(s) or delete the Music DB and rebuild. This process should be made easier from v18 and up using <promptfulltagscan>}}<section end="MusicLibrary" />

== Photos settings ==

=== pictureextensions ===
{{anchor|.3Cpictureextensions.3E}}
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Pictures window.

Default extensions for PICTURES:
<pre>
.png .jpg .jpeg .bmp .gif .ico .tif .tiff .tga .pcx .cbz .zip .rss .webp .jp2 .apng
</pre>

Examples:
<syntaxhighlight lang=xml enclose="div">
<pictureextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</pictureextensions>
</syntaxhighlight>

=== pictureexcludes ===
{{anchor|.3Cpictureexcludes.3E}}
Matches filenames or folders which should be excluded from being displayed in My Pictures using a list of Regular Expressions

<syntaxhighlight lang=xml enclose="div">
<pictureexcludes> 
<regexp>small</regexp>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</pictureexcludes>
</syntaxhighlight>

=== slideshow ===
{{anchor|.3Cslideshow.3E}}
<syntaxhighlight lang=xml enclose="div">
<slideshow>

<panamount>2.5</panamount>

<zoomamount>5.0</zoomamount>



<blackbarcompensation>20</blackbarcompensation>
</slideshow>
</syntaxhighlight>

== Network settings ==

=== ftp ===
{{anchor|.3Cftp.3DE}}
Specific settings if a ftp server is in use as a source

<syntaxhighlight lang=xml enclose="div">
<ftp>
<remotethumbs>true</remotethumbs> 
</ftp>
</syntaxhighlight>

=== samba ===
{{anchor|.3Csamba.3E}}
<syntaxhighlight lang=xml enclose="div">
<samba>
<doscodepage></doscodepage> 
<clienttimeout>10</clienttimeout> 
<statfiles>true</statfiles> 
</samba>
</syntaxhighlight>

=== hosts ===
{{anchor|.3Cfhosts.3E}}
Static dns entries which take precedence over your dns server.
<syntaxhighlight lang=xml enclose="div">
<hosts>
<entry name="HOSTNAME">IPADDRESS</entry>
</hosts>
</syntaxhighlight>

=== network ===
{{anchor|.3Cnetwork.3E}}

<syntaxhighlight lang=xml line='line'>
<network>
<curlclienttimeout>10</curlclienttimeout> 
<curllowspeedtime>20</curllowspeedtime> 
<curlretries>2</curlretries> 
<httpproxyusername></httpproxyusername> 
<httpproxypassword></httpproxypassword> 
<disableipv6>false</disableipv6> 
<disablehttp2>false</disablehttp2> 
<nfstimeout>30</nfstimeout> 
<catrustfile>filepath</catrustfile> 
<curlkeepaliveinterval>30</curlkeepaliveinterval> 
<nfsretries>0</nfsretries> 
</network>
</syntaxhighlight>

'''More information:'''<br>
* <curlkeepaliveinterval><ref>https://github.com/xbmc/xbmc/pull/19319</ref><br>
* <nfsretries><ref>https://github.com/xbmc/xbmc/pull/19513</ref>

=== cache ===
{{see also|HOW-TO:Modify_the_video_cache}}
<syntaxhighlight lang=xml enclose="div">
<cache>
<memorysize>0</memorysize> 
<buffermode>0</buffermode> 
<readfactor>4.0</readfactor> 
<chunksize>65536</chunksize> 
</cache>
</syntaxhighlight>

=== airtunesport ===
{{anchor|.3Cairtunesport.3E}}<section begin="airtunesport" />
This overwrites the defalt listening port of the AirTunes server (announced via zeroconf).
<section end="airtunesport" />

=== airplayport ===
{{anchor|.3Cairplayport.3E}}<section begin="airplayport" />
This overwrites the default listening port of the AirPlay server (announced via zeroconf).
<section end="airplayport" />

== File system settings ==

=== packagefoldersize ===
<section begin="packagefoldersize" />
{{anchor|.3Cpackagefoldersize.3E}}
{{xml setting
| tag name = packagefoldersize
| option type = numerical
| option values =
| default values = 200
| platform = all
| XBMC version = 12
| description = The amount (in megabytes) of add-on zip packages saved from previous add-on installs. These packages are mainly used for the [[Add-ons|add-on]] rollback feature. Increasing the size should increase the amount of past versions saved. Defaults to 200 MB.
| example = Example: <syntaxhighlight lang=xml enclose="div"><packagefoldersize>200</packagefoldersize> </syntaxhighlight>
}}
<section end="packagefoldersize" />

=== detectasudf ===
{{anchor|.3Cdetectasudf.3E}}
{{xml setting
| tag name = detectasudf
| option type = binary
| option values = true, false
| default values = false
| platform = all
| XBMC version =
| description = Set to true if you wish to detect joint ISO9660/UDF disks as UDF.
| example = Example: <syntaxhighlight lang=xml enclose="div"><detectasudf>false</detectasudf></syntaxhighlight>
}}

=== handlemounting ===
{{anchor|.3Chandlemounting.3E}}
{{xml setting
| tag name = handlemounting
| option type = binary
| option values = true, false
| default values = false
| platform = Linux
| XBMC version =
| description = Only used in Linux, it defines if Kodi should attempt to mount media drives (via udisks or udisks2).<br/>Default: False. If kodi is executed with the --standalone option (e.g. as done by kodi-standalone.sh) it by default will be True.
| example = Example: <syntaxhighlight lang=xml enclose="div"><handlemounting>false</handlemounting></syntaxhighlight>
}}

=== automountopticalmedia ===
{{xml setting
| tag name = automountopticalmedia
| option type = binary
| option values = true, false
| default values = false
| platform = Linux
| XBMC version =
| description = Only used in linux for the udisks and udisks2 providers<br/>defines if kodi should automount optical discs<ref>https://github.com/xbmc/xbmc/pull/20840</ref>
| example = Example: <syntaxhighlight lang=xml enclose="div"><automountopticalmedia>true</automountopticalmedia></syntaxhighlight>
}}

=== pathsubstitution ===
{{anchor|.3Cpathsubstitution.3E}}
{{main|Path substitution}}

{{divbox|red||'''Note:''' Path substition for "sources" and profiles is broken, and will '''NOT''' be fixed.}}

Path substitutions are for use for redirecting file paths. These are processed in order, and are useful for substituting an absolute path on a PC with a path suitable for Kodi to handle.

Default: No path substitutions defined.

Example:
<syntaxhighlight lang=xml enclose="div">
<pathsubstitution>
<substitute>
<from>G:\dvds\</from>
<to>smb://somecomputer/g-share/dvds/</to> 
</substitute>
</pathsubstitution>
</syntaxhighlight>

== Input control settings ==

=== remotedelay ===
{{anchor|.3Cremotedelay.3E}}
The repeat delay for a LIRC remote control. A delay value between 1 and 20 before a remote button starts repeating on a long keypress (i.e. continuously sending button pushes while it's held down).

Default: 3
<syntaxhighlight lang=xml enclose="div">
<remotedelay>10</remotedelay>
</syntaxhighlight>

=== controllerdeadzone ===
{{anchor|.3Ccontrollerdeadzone.3E}}
This advanced settings has been removed.
Since v17, the [[Advancedsettings.xml#controllerdeadzone|<controllerdeadzone>]] advanced setting has been removed. Deadzones can now be configured by plugging in the controller and selecting it in Settings -> System settings -> Input -> Peripherals.

=== enablemultimediakeys ===
{{anchor|.3Cenablemultimediakeys.3E}}
This setting only has any effect on Windows versions of Kodi, and only applies to builds from 28th May 2011 onwards.
In Windows the multimedia keys generate a WM_APPCOMMAND message in addition the keypress. Kodi processes both keypresses and the WM_APPCOMMAND messages, and the end result would be that the command is executed twice. To avoid this, by default multimedia keypresses are disabled. Although it should rarely be necessary, the enablemultimediakeys setting allows you to enable the multimedia keys.

Example:
<syntaxhighlight lang=xml enclose="div">
<enablemultimediakeys>true</enablemultimediakeys>
</syntaxhighlight>

=== seeksteps ===
{{Main|Skip steps}}

This setting changes which increments are available in the settings GUI for additive seeking. Note that <code><seeksteps></code> is not used to actually choose which seek steps are enabled.

'''Default:'''
<syntaxhighlight lang=xml enclose="div">
<seeksteps>7, 15, 30, 60, 180, 300, 600, 900, 1800</seeksteps>
</syntaxhighlight>

{{editor note|the defaults need to be updated for seeksteps.}}

=== touchscreen ===
{{anchor|.3Ctouchscreen.3E}}
This setting allows you to move/align the origin of the touch screen with the origin of the display used. If touch input does not result in a correct movement of the mouse pointer, the behaviour can be corrected with an offset and a stretch/compress factor.

Example:
<syntaxhighlight lang=xml enclose="div">
<touchscreen>
<x_offset>0</x_offset> 
<y_offset>0</y_offset> 
<x_stretch_factor>1.0</x_stretch_factor> 
<y_stretch_factor>1.0</y_stretch_factor> 
</touchscreen>
</syntaxhighlight>

=== scanirserver ===
Introduced in v18 and used in MS Windows setups only.<ref>https://github.com/xbmc/xbmc/pull/13896</ref>
Used to disable the regular connection attempts to the IR Server Suite when there is no remote to connect to.

The default setting is to allow connection attempts. To disable connection attempts change value to '''false'''.
<syntaxhighlight lang=xml enclose="div">
<scanirserver>true</scanirserver>
</syntaxhighlight>

== Other interface settings ==

=== window ===
{{anchor|.3Cwindow.3E}}
{{note|This is a "hidden" guisettings.xml setting (defined by the mouse moving the window size), but it is mentioned here because it is a particularly useful override when used in advancedsettings.xml}}
This allows you to manually set the default size of Kodi's windowed mode. If you resize the window, it will return to the set size when restarting.

WIDTH and HEIGHT are the values for each dimension, in pixels.

<syntaxhighlight lang=xml enclose="div">
<window>
<width>WIDTH</width>
<height>HEIGHT</height>
</window>
</syntaxhighlight>

=== restrictcapsmask ===
{{anchor|.3Crestrictcapsmask.3E}}
Windows only. A bitmask to prevent Kodi from using detected texture capabilities of the GPU. This helps work around buggy hardware/drivers.

1: prevent the use of compressed textures (DXT1, DXT3, DXT5)
2: prevent the use of non-power-of-two dimensions for textures
4: prevent the use of compressed textures with non-power-of-two dimensions.

<syntaxhighlight lang=xml enclose="div">
<restrictcapsmask>0</restrictcapsmask>
</syntaxhighlight>

=== algorithmdirtyregions ===
{{anchor|.3Calgorithmdirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="algorithmdirtyregions" />{{note|Some GPU/hardware configurations will have some minor issues (such as a visual "flicker"). For those situations try mode 2 or use the default (mode 3, which requires no advancedsetting). Almost all ARM-based devices (such as [[Android]]) willl likely have flickering issues.}}

Enable dirty-region processing. Dirty regions are any parts of the screen that have changed since the last frame. By not re-rendering what hasn't changed the GUI can be sped up. Because all GPUs work differently, only Mode 3 is guaranteed to work for everyone without flickering issues. This mode will reduce CPU/GPU usage, but will not increase GUI speed.

{| class="prettytable"
! value !! result !! description
|-
! 0
| Off
| The entire viewport is always rendered.
|-
! 1
|Union
|All dirty regions are grouped into the smallest possible rectangle. This is typically the fastest mode for slower GPUs due to only making one pass.
|-
! 2
| {{nowrap|Cost reduction}}
| Each dirty region is presented separately, in as many passes as there are regions.
|-
! 3
| {{nowrap|Whole Screen}}
| The entire screen is rendered if there are any dirty regions. This is a safe default for drivers that clear buffer contents (manifests as blinking or vibrating images). '''Default'''
|}<section end="algorithmdirtyregions" />

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<algorithmdirtyregions>1</algorithmdirtyregions>
</gui>
</syntaxhighlight>

=== visualizedirtyregions ===
{{anchor|.3Cvisualizedirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="visualizedirtyregions" />Enable dirty-region visualization. Paints a rectangle over marked controls.

* true: on
* false: off '''(Default)'''

{{note|This is only a development mode and isn't of use to normal users.}}
<section end="visualizedirtyregions" />
Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<visualizedirtyregions>true</visualizedirtyregions>
</gui>
</syntaxhighlight>

=== smartredraw ===

{{note|This is an experimental feature and you might face issues using it. So please be aware of that.}}

This new feature was introduced in Kodi 18 and if enabled, the GUI process call (and therefore the render call) is only done if anything has changed. The result will be a faster GUI and less load if Kodi plays a video

* true: on
* false: off '''(Default)'''

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<smartredraw>true</smartredraw>
</gui>
</syntaxhighlight>

=== showexitbutton ===
{{anchor|.3Cshowexitbutton.3E}}
Setting to hide the exit button, useful for people running appliance based setups where exit would only confuse/complicate the user. Modifiable via the advancedsettings.xml by setting showexitbutton to false, default is true (show)

Example:
<syntaxhighlight lang=xml enclose="div">
<showexitbutton>true</showexitbutton>
</syntaxhighlight>

=== fullscreen ===
{{anchor|.3Cfullscreen.3E}}
Starts Kodi in full screen (check resolutions!).

<syntaxhighlight lang=xml enclose="div">
<fullscreen>false</fullscreen>
</syntaxhighlight>

=== splash ===
{{anchor|.3Csplash.3E}}
Set to false if you wish to disable the startup splash image. Defaults to true.

<syntaxhighlight lang=xml enclose="div">
<splash>true</splash>
</syntaxhighlight>

=== cputempcommand ===
{{anchor|.3Ccputempcommand.3E}}
Provide a shell command Kodi will use to get CPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia and Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sed -e 's/$[0-9]*$[0-9]\{3\}.*/\1 C/' /sys/class/thermal/thermal_zone0/temp</cputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>echo "$(sensors -u | tail -n64 | grep temp1_input | awk '{print $2 }' |awk '{printf("%d\n",$1 + 0.5);}') C"</cputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sensors|sed -ne "s/temp1: \+[-+]$[0-9]\+$.*/\1 C/p"</cputempcommand>
</syntaxhighlight>

=== gputempcommand ===
{{anchor|.3Cgputempcommand.3E}}
Provide a shell command Kodi will use to get GPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-settings -tq gpuCoreTemp) C"</gputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-smi -q -d TEMPERATURE | grep Gpu | cut -c35-36) C"</gputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/usr/bin/aticonfig --od-gettemperature | grep Temperature | cut -f 2 -d "-" | cut -f 1 -d "." | sed -e "s, ,," | sed 's/$/ C/'</gputempcommand>
</syntaxhighlight>

;<u>For Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/opt/vc/bin/vcgencmd measure_temp | sed -e "s/temp=//" -e "s/\..*'/ /"</gputempcommand>
</syntaxhighlight>

=== glrectanglehack ===
{{anchor|.3Cglrectanglehack.3E}}
Problems with ghosting or videos which are only played back in the left upper quarter? The following ATI hack may solve it.
<syntaxhighlight lang=xml enclose="div">
<glrectanglehack>yes</glrectanglehack>
</syntaxhighlight>

=== alwaysontop ===
{{anchor|.3Calwaysontop.3E}}
Added in XBMC v9.11 (Windows OS only). Keeps Kodi always on top when windowed.
<syntaxhighlight lang=xml enclose="div">
<alwaysontop>yes</alwaysontop>
</syntaxhighlight>

There is also a fake fullscreen GUI option in Kodi's settings.

=== minimizetotray ===
{{anchor|.3Cminimizetotray.3E}}
{{note|Available in Kodi v20 and above.}}

Windows only. Minimizes Kodi to the system tray. Defaults to false.
<syntaxhighlight lang=xml enclose="div">
<minimizetotray>true</minimizetotray>
</syntaxhighlight>

= Removed tags =
{{anchor|Recently removed tags}}
* {{anchor|.3Cthumbsize.3E}}'''<thumbsize>''' - replaced by <[[#imageres|imageres]]> in v12 Frodo
* {{anchor|.3Cfanartheight.3E}}'''<fanartheight>''' - replaced by <[[#fanartres|fanartres]]> in v12 Frodo
* {{anchor|.3Cdvdthumbs.3E}}'''<dvdthumbs>''' - removed in v12 Frodo
* {{anchor|.3Cbusydialogdelayms.3E}}'''<busydialogdelayms>''' - removed in v12 Frodo
* {{anchor|.3Cbginfoloadermaxthreads.3E}}'''<bginfoloadermaxthreads>''' - removed in v13 Gotham
* '''<showepginfoonselect>''' - replaced by a GUI setting in v13 Gotham
* '''<resample>''', '''<forceDirectSound>''', '''<audiophile>''', '''<audiosinkbufferdurationmsec>''', '''<allowtranscode44100>''', and '''<streamsilence>''' - These were various sub-tags for <audio> that were removed in v13 Gotham and either replaced by GUI settings or were no longer needed.
* {{anchor|.3Cenableairtunesdebuglog.3E}}'''<enableairtunesdebuglog>''' - replaced by a GUI option in v14 Helix
* '''<videoDisableHi10pMultithreading>''' - renamed to <disableswmultithreading> in v14 Helix
* '''<hideallitems>''' - For both the <code><videolibrary></code> and <code><musiclibrary></code> sections, this is replaced by a GUI option in v15 Isengard
* '''<SmallStepBackSeconds>''' - In v15 the <code>SmallStepBack</code> [[Action_IDs]] has been replaced by <code>seek(-7)</code> in default keymaps. See '''[[skip steps]]''' for details. When the original <code>SmallStepBack</code> action ID is used it defaults to the first backwards [[skip steps|additive seeking value]].
* '''<timeseekforward>/<timeseekbackward>''' - In v15 these tags are replaced by GUI options via [[skip steps|additive seeking]], which is configured in the GUI. See '''[[skip steps]]''' for details.
* {{anchor|.3Ckaraoke.3E}}'''<karaoke>''' - In v16 all of the karaoke features in Kodi were removed.
* '''<useddsfanart>''' - removed in v17 Krypton.
* '''<cachemembuffersize>''' and '''<readbufferfactor>''' - In v17 '''<cachemembuffersize>''' is renamed to '''<memorysize>''' and <code><readbufferfactor></code> is renamed to <code><readfactor></code>. In addition, all three buffer related settings in <network> are moved out of <network> and into a new <cache> parent tag.
* '''<minvideocachelevel>''', '''<minaudiocachelevel>''', and '''<cacheindvdplayer>''' have been removed in v17.
* '''<useffmpegvda>''' - Tag was only used for development testing. Removed in v17.
* '''<nofliptimeout>''' - Removed in v17
* '''<blackbarcolour>''' - Removed in v17 (maybe?)
* '''<disableswmultithreading>''' - Removed in v17 (maybe?)
* '''<controllerdeadzone>''' - Removed in v17
* {{anchor|.3Cmeasurerefreshrate.3E}}'''<measurerefreshrate>''' - Removed in v17 or v18?
* {{anchor|.3Cmyth.3E}}'''<myth>''' - Removed sometime between v16 to v18
* {{anchor|.3Ctuxbox.3E}}'''<tuxbox>''' - Removed
* '''<backgroundupdate>''' - Removed
* '''<hideemptyseries>''' - Replaced by a GUI option.
* '''<mymovies>''' and child tag '''<categoriestogenres>''' - Removed
* '''<albumssortbyartistthenyear'''> - Removed
* '''<albumformatright>''' - Removed
* {{anchor|.3Cremoterepeat.3E}}'''<remoterepeat>''' - Removed
* {{anchor|.3Callowd3d9ex.3E}}'''<allowd3d9ex>''' and {{anchor|.3Cforced3d9ex.3E}}'''<forced3d9ex>''' - Removed sometime between v16 to v18
* '''<lingertime>''' - Replaced by a GUI setting in v18
* '''<forcevaapienabled>''' - Removed in v18
* '''<dxvaallowhqscaling>''' - Removed in v18 <ref>https://github.com/xbmc/xbmc/pull/15466</ref>
* '''<promptfulltagscan>false</promptfulltagscan>''' Removed in v18. Now automatically asked each time a scan is conducted.
* '''<omxdecodestartwithvalidframe>''' - This tag is only in some Raspberry Pi specific distributions, such as OpenELEC. As of March 2015, this tag has not been merged into "vanilla" Kodi builds
* '''<musicthumbs>''' Replaced in v19 by the GUI setting '''Thumbnail image files''' found in Media -> Music
* '''<artistextraart>''' Replaced in v19 by the GUI setting '''Artist art types whitelist''' found in Media -> Music
* '''<albumextraart>''' Replaced in v19 by the GUI setting '''Album art types whitelist''' found in Media -> Music
* '''<episodeextraart>''' Replaced in v19 by the GUI setting '''Episode art types whitelist''' found in Media -> Videos
* '''<tvshowextraart>''' Replaced in v19 by the GUI setting '''TV show art types whitelist''' found in Media -> Videos
* '''<tvseasonextraart>''' Replaced in v19 by the GUI setting '''TV show art types whitelist''' found in Media -> Videos
* '''<movieextraart>''' Replaced in v19 by the GUI setting '''Movie art types whitelist''' found in Media -> Videos
* '''<moviesetextraart>''' Replaced in v19 by the GUI setting '''Movie art types whitelist''' found in Media -> Videos
* '''<musicvideoextraart>''' Replaced in v19 by the GUI setting '''Music video art types whitelist''' found in Media -> Videos
* '''<fanart>''' Removed in v19
* '''<assfixedworks>''' Removed in v20
* '''<try10bitoutput>''' Removed in v20 and replaced with [[Settings/System/Display#Use_10_bit_for_SDR|Use 10 bit for SDR]] setting <ref>https://github.com/xbmc/xbmc/pull/20014</ref>
* '''<enablehighqualityhwscalers>''' Removed in v20 <ref>https://github.com/xbmc/xbmc/pull/21537</ref>

= guisettings.xml Setting Conversion =
It is possible to convert settings found in the '''[[Settings]]''' ''(guisettings.xml)'' pages of {{kodi}} into entries for the advancedsettings.xml file.

When a setting from the guisettings.xml is added to the advancedsettings.xml file, it will override the existing guisettings.xml values and the setting will be removed from the settings pages.

Why would I need to do this?
* You set up multiple devices and then need to individually change settings and preferences on each device. Using this conversion method, you save those settings in the advancedsettings.xml file and simply add the file to each device
* You need to hide settings to prevent those settings from being modified

To convert a guisetting to advancedsettings.xml follow these steps:
# In the {{kodi}} settings pages, adjust the setting(s) to your preference.
# Back out of the settings pages to the main menu, which forces {{kodi}} to save the adjusted settings to the guisettings.xml file
# Locate the guisettings.xml file in the [[Userdata]] folder and open it
# Locate the setting(s) to be converted. The list can be overwhelming so make use of the Search feature of whichever editor you are using
# Using the following setting as an example:
<syntaxhighlight lang="xml">
<setting id="videolibrary.showemptytvshows">true</setting>
</syntaxhighlight>
: Breaking down the string:
::'''videolibrary'''- parent tag
::'''showemptytvshows'''- child tag
::'''true'''- value
: The conversion is as follows and place this in the advancedsettings.xml file
<syntaxhighlight lang="xml">
<advancedsettings version="1.0">
<videolibrary>
<showemptytvshows>true</showemptytvshows>
</videolibrary>
</advancedsettings>
</syntaxhighlight>

'''Note:''' Some parent tags may already be in use in your advancedsettings.xml file. Do not duplicate them, but add the child tag beneath the existing parent tag.

= References =
<references />

{{Updated|18}}
{{DISPLAYTITLE:advancedsettings.xml}}

[[Category:Advanced topics]]
[[Category:Manual]]
[[Category:Settings]]

Advancedsettings.xml

2024-01-21T12:08:19Z

Fritsch: /* audio */

{{TOC right}}{{mininav|[[Settings]]|page=advancedsettings.xml}}
{{bigger|{{note|'''The advancedsettings.xml file does not exist by default. You have to create it first!'''}} }}

<section begin="intro" />The [[advancedsettings.xml]] file, which does not exist by default, can be created by a user in their '''[[Userdata|userdata folder]]'''.

This file is used for advanced settings and options that do not have GUI controls inside of {{kodi}}. Some settings are experimental or very rarely set, so they can only be used via the advancedsettings.xml file. The file is simply a plain text file and can be edited by various text editors, so long as the name is "advancedsettings.xml". These advanced settings can be used to tweak various things such as episode naming patterns, special network ports, special behaviors, and more.<section end="intro" />

The following page will describe the structure of the advancedsettings.xml file and the various individual settings.

{{note|
# All XML tags must be lowercase. The start and end of the advancedsettings.xml file must have the <advancedsettings> and </advancedsettings> tags.
# Kodi will only read the advancedsettings.xml file when it starts up. If you make changes while it is running then you must restart Kodi.
# For some Windows versions, Kodi has two <code>\userdata\</code> folders. The correct one to put the advancedsettings.xml file in is not the one in Program Files, but in <code>%appdata%\Kodi\userdata\.</code>}}

== Layout ==

The layout of <code>advancedsettings.xml</code> is as follows:

<syntaxhighlight lang=xml enclose="div">
<advancedsettings version="1.0">
<setting>value</setting>
...
<setting>value</setting>
</advancedsettings>
</syntaxhighlight>

where "setting" gives the name of the setting, and "value" gives its value.

A list of the available "setting" strings and their values is given below.

= List of available settings =
List of available settings that are recognised in the advancedsettings.xml file <ref>https://github.com/xbmc/xbmc/blob/master/xbmc/settings/AdvancedSettings.cpp</ref>

Recommended: Use the table of contents or the search function in your browser to locate items.

== Troubleshooting settings ==

=== loglevel ===
{{Anchor|.3Cloglevel.3E}}

<section begin="loglevel" />
Sets the logging level used to log errors and information. The "hide" attribute is optional.

<syntaxhighlight lang=xml>
<loglevel hide="attribute">options</loglevel>
</syntaxhighlight>

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Attribute
! style="width:500px;" | Action
|-
! '''true'''
| Hides the "enable debugging" setting in the Settings page. (default)
|-
! '''false'''
| Allows "enable debugging" setting to switch between '''0''' and '''2'''.
|}

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Option
! style="width:500px;" | Action
|-
! '''-1'''
| No logging, suppresses all log output
|-
! '''0'''
| Normal logging, only logging errors (default)
|-
! '''1'''
| Debug logging with freemem, fps and cpu usage (no on screen)
|-
! '''2'''
| Same as 1 (with on screen display)
|-
! '''3'''
| Same as 1 + full smb logging
|}

{| class="wikitable"
|-
! style="width:100px;" | Example
! style="width:500px;" |
|-
! Example 1:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings version="1.0">
<loglevel>2</loglevel>
</advancedsettings>
</syntaxhighlight>
|-
! Example 2:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings version="1.0">
<loglevel hide="true">2</loglevel>
</advancedsettings>
</syntaxhighlight>
|}

'''Note:''' The setting is persistent through shutdown and restarts.<br>
'''Note:''' If debugging is enabled in the GUI, loglevel will be set to '''2'''. This will over-ride the <code>advancedsettings.xml</code> setting. You must disable the GUI Setting before adding the entry to <code>advancedsettings.xml</code>.<br />
<section end="loglevel" />
:''{{see also|Log_file|label 1=Debug Log}}''

=== jsonrpc ===
{{Anchor|.3Cjsonrpc.3E}}
To make it easier for developers using the [[JSON-RPC_API]] API in their (third party) applications to debug during development the json output of Kodi can be prettified by setting '''compactoutput''' to '''false'''. Default json output mode is a compact print which does not contain any unnecessary whitespaces and therefore is difficult to read for humans.
Furthermore using the '''tcpport''' setting it is possible to change the default TCP port used by Kodi for JSON RPC (which is 9090) to any other valid port.

Example:
<syntaxhighlight lang=xml enclose="div">
<jsonrpc>
<compactoutput>false</compactoutput>
<tcpport>9999</tcpport>
</jsonrpc>
</syntaxhighlight>

== Audio/video playback settings ==

=== skiploopfilter ===
{{anchor|.3Cskiploopfilter.3E}}
The amount of the loop filter to skip on h.264 decoding. This can help the performance of slower machines when decoding h264 content. Values, in decreasing CPU usage (and decreasing quality)
* -16 None
* 0 Skip only empty frames (default)
* 8 Skip non-reference frames
* 16 Skip bi-dir frames
* 32 Skip all non-key frames
* 48 Skip all frames
Example:
<syntaxhighlight lang=xml enclose="div">
<skiploopfilter>8</skiploopfilter>
</syntaxhighlight>

=== video ===
{{anchor|.3Cvideo.3E}}

The <video> section also includes the following child-tags, which have their own sections:
*[[#cleandatetime]]
*[[#cleanstrings]]
*[[#excludefromscan]]
*[[#excludefromlisting]]
*[[#excludetvshowsfromscan]]

{{note|Some tags that have a "third-level" and are grouped together are highlighted in color.}}

{| class="prettytable"
! Tag !! Description
|-
|
<syntaxhighlight lang=xml>
<video>
</syntaxhighlight>
| Parent tag that all other child tags need to be placed inside of. Do not use more than one '''<code><video></code>''' tag, but instead place all other child-tags within a single '''<code><video></video></code>''' set.
|-
|
<syntaxhighlight lang=xml>
<subsdelayrange>10</subsdelayrange>
</syntaxhighlight>
| Delay range for subtitles, in seconds.
|-
|
<syntaxhighlight lang=xml>
<maxtempo>2.1</maxtempo>
</syntaxhighlight>
| Allow further increase of playback speed over the default of 1.5<br>
maxtempo must be in the range of 1.5 to 2.1 <br>
Be aware of the limitations of your platform / hardware as not all are capable of the increased maxtempo <ref>https://forum.kodi.tv/showthread.php?tid=10023&pid=2795069#pid2795069</ref>
|-
|
<syntaxhighlight lang=xml>
<audiodelayrange>10</audiodelayrange>
</syntaxhighlight>
| Delay range for audio/video sync, in seconds.
|-
|
<syntaxhighlight lang=xml>
<usetimeseeking>true</usetimeseeking>
</syntaxhighlight>
| Whether to use time based or percentage based seeking. {{small see also|Skip steps}}
|-
|
<syntaxhighlight lang=xml>
<timeseekforwardbig>600</timeseekforwardbig>
<timeseekbackwardbig>-600</timeseekbackwardbig>
</syntaxhighlight>
| Time to seek forward in seconds when doing a long seek. Defaults to 600 (10 minutes) and -600 (-10 minutes) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforward>2</percentseekforward>
<percentseekbackward>-2</percentseekbackward>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a short seek. Defaults to 2 (2%) and -2 (2%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforwardbig>10</percentseekforwardbig>
<percentseekbackwardbig>-10</percentseekbackwardbig>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a long seek. Defaults to 10 (10%) and -10 (10%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<fullscreenonmoviestart>true</fullscreenonmoviestart>
</syntaxhighlight>
| Whether to go to fullscreen or not when starting a movie. Defaults to true.
|-
|
<syntaxhighlight lang=xml>
<defaultplayer>VideoPlayer</defaultplayer>
</syntaxhighlight>
| Set the default video player: VideoPlayer or an external player. See '''[[External players]]''' for more info.
|-
|
<syntaxhighlight lang=xml>
<excludefromscan>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromscan>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be added to library. It is possible to add multiple <code><regexp></code> tags to match multiple patterns
|-
|
<syntaxhighlight lang=xml>
<excludefromlisting>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be displayed in files view.
|-
|
<syntaxhighlight lang=xml>
<playcountminimumpercent>90</playcountminimumpercent>
</syntaxhighlight>
| Minimum percentage that has to be played before it is marked as watched. Set to 101 to never auto-mark items as watched. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignoresecondsatstart>180</ignoresecondsatstart>
</syntaxhighlight>
| Number of seconds to ignore at video start after which a resume point is created. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignorepercentatend>8</ignorepercentatend>
</syntaxhighlight>
| Percentage of video to ignore at the end. If you stop watching the video here no resume point is created. Set to 101 to never save a resume point. The video is already marked as watched at 90%, see above. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<vdpauscaling>true</vdpauscaling>
</syntaxhighlight>
| Scales with vdpau instead of opengl and turns on its HQ scaler when available, enabling this might slow down rendering and cause framedrops especially on ION systems, this setting requires a vdpau feature set C GPU.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegdeinterlacing>linblenddeint</ppffmpegdeinterlacing>
</syntaxhighlight>
| Override the deinterlacing options passed to libpostproc.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegpostprocessing>ha:128:7,va,dr</ppffmpegpostprocessing>
</syntaxhighlight>
| Override the post processing options passed to libpostproc when 'Video post-processing' is activated in GUI Videos-Settings-Playback.
|-
|
<syntaxhighlight lang=xml>
<autoscalemaxfps>30</autoscalemaxfps>
</syntaxhighlight>
| When scaling method is set to auto, bilinear is chosen when the fps is higher than this limit, the default is 30.
|-
|
<syntaxhighlight lang=xml>
<adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" | Settings for when "Adjust refreshrate to match video fps" is enabled in the video playback GUI settings.
|-
|
<syntaxhighlight lang=xml>
<override>
<fps>23.976</fps>
<refresh>60.0</refresh>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' "Adjust refreshrate to match video fps" will try to select the best refreshrate for the video fps but it doesn't always get it right, for example it might switch to an unsupported refreshrate. You can add overrides here to switch to a certain refreshrate based on video fps. It's possible to add as many overrides as you need. Overrides are processed in order, if the first one doesn't match the fps or no refreshrates match that override, it will try the next one until no overrides are left.

* '''fps''' - if the fps is between 23.966 and 23.986
* '''refresh''' - switch to the first found refreshrate that is between 59.99 and 60.01
|-
|
<syntaxhighlight lang=xml>
<override>
<fpsmin>29.96</fpsmin>
<fpsmax>30.01</fpsmax>
<refreshmin>59.0</refreshmin>
<refreshmax>61.0</refreshmax>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -'''
* '''fpsmin''' / '''fpsmin''' - You can also specify the fps range yourself.
* '''refreshmin''' / '''refreshmax''' - Same for the refreshrate
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refresh>50.0</refresh>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' If none of the overrides match, or none of the refreshrates match any of the fps matching overrides, it will choose a fallback refreshrate. Fallbacks are process in order, if the first fallback doesn't match any refreshrate, it will try the next one until no fallbacks are left.

* '''refresh''' - Switch to the first found refreshrate that is between 49.99 and 50.01.
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refreshmin>49.0</refreshmin>
<refreshmax>51.0</refreshmax>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' You can also specify the range for the fallback yourself.

If none of the overrides match the video fps, or no refreshrates match any of the fps matching overrides, and no fallbacks are specified or no refreshrates match any fallbacks, it will automatically choose the best refreshrate (same as having no overrides and fallbacks).
|-
|
<syntaxhighlight lang=xml>
</adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" |
|-
|
<syntaxhighlight lang=xml>
<checkdxvacompatibility>value</checkdxvacompatibility>
</syntaxhighlight>
| Advanced setting not present: let Kodi autodetect cards that support H.264 profile > L4.1. Set value to false to enable DXVA no matter what. Set value to true if Kodi doesn't autodetect that the graphics card doesn't support > L4.1.
|-
|
<syntaxhighlight lang=xml>
<useocclusionquery>-1</useocclusionquery>
</syntaxhighlight>
| Use an occlusion query when capturing videoframes, -1 means auto detect, 0 means disabled, 1 means enabled, the default is -1.
|-
|
<syntaxhighlight lang=xml>
<fpsdetect>1</fpsdetect>
</syntaxhighlight>
| FPS detection for video playback
* 0 = trust codec fps
* 1 = recalculate from video timestamps with uniform spacing
* 2 = recalculate from video timestamps always
|-
|
<syntaxhighlight lang=xml>
<latency>
</syntaxhighlight>
| style="background:#F0E68C;"| Start of '''latency''' tags. Display latency (video lag). Latency is given in msecs.
|-
|
<syntaxhighlight lang=xml>
<delay>0</delay>
</syntaxhighlight>
| style="background:#F0E68C;" | Global default display latency.
|-
|
<syntaxhighlight lang=xml>
<refresh></refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | Override latency for given display (not video) refresh rates. When Kodi is in windowed mode, override is ignored. Multiple overrides are allowed.

Syntax of an override entry:
<syntaxhighlight lang=xml>
<refresh>
<min>, <max> refresh rate range, OR
<rate> exact refresh rate
<delay> display latency for the given refresh rate
</refresh>
</syntaxhighlight>
|-
|
<syntaxhighlight lang=xml>
<refresh>
<min>23</min>
<max>24</max>
<delay>125</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 125 msec latency at 23-24 Hz
|-
|
<syntaxhighlight lang=xml>
<refresh>
<rate>50</rate>
<delay>50</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 50 msec latency at 50 (+/-0.01) Hz
|-
|
<syntaxhighlight lang=xml>
</latency>
</syntaxhighlight>
| style="background:#F0E68C;" |
|-
|
<syntaxhighlight lang=xml>
<stereoscopicregex3d>[-. _]3d[-. _]</stereoscopicregex3d>
<stereoscopicregexsbs>[-. _]h?sbs[-. _]</stereoscopicregexsbs>
<stereoscopicregextab>[-. _]h?tab[-. _]</stereoscopicregextab>
</syntaxhighlight>
| Filename triggers for 3D (stereoscopic) mode.
|-
|
<syntaxhighlight lang=xml>
<assfixedworks>false</assfixedworks>
</syntaxhighlight>
| Position behavior of ass subtitiles when setting "subtitle position on screen" set to "fixed". True to show at the fixed position set in video calibration. False to show at the bottom of video (default). {{note|Removed in Kodi v20.}}
|-
|
<syntaxhighlight lang=xml>
<subtitleverticalmargin>120</subtitleverticalmargin>
</syntaxhighlight>
| Allows to customise the vertical margin of text based subtitles, which will be applied to each type of subtitle position in subtitle settings. {{note|Available in Kodi v20 and above.}}
|-
|
<syntaxhighlight lang=xml>
</video>
</syntaxhighlight>
|
|}

=== audio ===
{{anchor|.3Caudio.3E}}
<syntaxhighlight lang=xml enclose="div">
<audio>

<headroom>0</headroom>

<defaultplayer>paplayer</defaultplayer>

<excludefromscan>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromscan>

<excludefromlisting>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromlisting>

<ac3downmixgain>12.0</ac3downmixgain>

<usetimeseeking>true</usetimeseeking>

<timeseekforwardbig>600</timeseekfowardbig>

<timeseekbackwardbig>-600</timeseekbackward>

<playcountminimumpercent>99</playcountminimumpercent>

<applydrc>-1.0</applydrc>

<limiterhold>0.025</limiterhold>

<limiterrelease>0.1</limiterrelease>

<maxpassthroughoffsyncduration>10</maxpassthroughoffsyncduration>

<allowmultichannelfloat>false</allowmultichannelfloat>
</audio>
</syntaxhighlight>

=== forcedswaptime ===
{{anchor|.3Cforcedswaptime.3E}}
Use to force a backbuffer->frontbuffer swap while vsync is enabled. Set to the time (in ms) to allow for the swap (e.g. <forcedswaptime>1</forcedswaptime> is typical).

Default: Off

=== edl ===
{{anchor|.3Cedl.3E}}
{{main|Edit_decision_list}}
Commercial break detection not as good you think it could be? Are some commercial breaks in a series of adverts not being skipped? Are some parts being skipped that are clearly not commercials? Does the end of the previous recording still show? The following advanced settings can be used to better identify full commercial break sequences, remove incorrectly flagged commercial breaks, and have playback start at the actual beginning of the recording.

<syntaxhighlight lang=xml enclose="div">
<edl>

<mergeshortcommbreaks>false</mergeshortcommbreaks>

<maxcommbreaklength>250</maxcommbreaklength>

<mincommbreaklength>90</mincommbreaklength>

<maxcommbreakgap>120</maxcommbreakgap>

<commbreakautowait>0</commbreakautowait>

<commbreakautowind>0</commbreakautowind>

<displaycommbreaknotifications>false</displaycommbreaknotifications>
</edl>
</syntaxhighlight>
'''Notes:'''
* displaycommbreaknotifications<ref>https://github.com/xbmc/xbmc/pull/20711</ref>

== PVR & Live TV ==
{{anchor|.3Cpvr.3E}}
Settings available for PVR, EPG and Live TV. Edit Decision List settings are located in the previous section.

=== pvr ===
<syntaxhighlight lang="xml" line='line'>
<pvr>
<timecorrection>0</timecorrection> 
<infotoggleinterval>3000</infotoggleinterval> 
<channeliconsautoscan>true</channeliconsautoscan> 
<autoscaniconsuserset>false</autoscaniconsuserset> 
<numericchannelswitchtimeout>1000</numericchannelswitchtimeout> 
</pvr>
</syntaxhighlight>

==== pvrrecordings ====
In v19 and later, allows users to modify sort type and order of pvr recordings. <ref>https://github.com/xbmc/xbmc/pull/18605</ref>

;Note- These settings are child tags to the ''<pvr>'' tag in the previous section.

<syntaxhighlight lang="xml" line='line'>
<pvr>
<pvrrecordings>
<sortmethod>2</sortmethod> 
<sortorder>2</sortorder> 
</pvrrecordings>
</pvr>
</syntaxhighlight>

=== epg ===
{{anchor|.3Cpvr.3E}}
<syntaxhighlight lang="xml" line='line'>
<epg>
<updatecheckinterval>300</updatecheckinterval> 
<updateemptytagsinterval>60</updateemptytagsinterval> 
<cleanupinterval>900</cleanupinterval> 
<activetagcheckinterval>60</activetagcheckinterval> 
<retryinterruptedupdateinterval>60</retryinterruptedupdateinterval> 
<displayupdatepopup>true</displayupdatepopup> 
<displayincrementalupdatepopup>false</displayincrementalupdatepopup> 
</epg>
</syntaxhighlight>

== Video library settings ==

=== videoextensions ===
{{anchor|.3Cvideoextensions.3E}}<section begin="videoextensions" />
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Video windows.

Default extensions for VIDEOS:
<pre>
.m4v .3g2 .3gp .nsv .tp .ts .ty .strm .pls .rm .rmvb .mpd .m3u .m3u8 .ifo .mov .qt .divx .xvid
.bivx .vob .nrg .img .iso .udf .pva .wmv .asf .asx .ogm .m2v .avi .bin .dat .mpg .mpeg .mp4
.mkv .mk3d .avc .vp3 .svq3 .nuv .viv .dv .fli .flv .001 .wpl .xspf .zip .vdr .dvr-ms .xsp .mts
.m2t .m2ts .evo .ogv .sdp .avs .rec .url .pxml .vc1 .h264 .rcv .rss .mpls .mpl .webm .bdmv
.bdm .wtv .trp .f4v
</pre>
Examples:
<pre>
<videoextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</videoextensions>
</pre>
<section end="videoextensions" />

=== discstubextensions ===
{{main|Media stubs}}

<section begin="discstubextensions" />
The default filename extension for Disc Stubs is:
<syntaxhighlight lang=xml enclose="div">
.disc
</syntaxhighlight>
Using the following tags, it is possible to <tt><add></tt> additional or <tt><remove></tt> existing disc stub extensions to better suit your requirements.
<syntaxhighlight lang=xml enclose="div">
<discstubextensions>
<add>.disk|.stub</add>
<remove>.disc</remove>
</discstubextensions>
</syntaxhighlight>
<section end="discstubextensions" />

=== languagecodes ===
{{anchor|.3Clanguagecodes.3E}}
User-defined translation table for language codes used in subtitles and audio.
It can be used to add, extend or override Kodi's language codes.

'''How to add a new language code:'''

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>alt</short>
<long>Alternate</long>
</code>
</languagecodes>
</syntaxhighlight>

'''How to add a new language code with subtag (e.g. pt-BR):'''
{{note|This support is available from Kodi v20}}

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>pt-BR</short>
<long>Portuguese - Brazil</long>
</code>
</languagecodes>
</syntaxhighlight>

''NOTE FOR MKV FILES:''<br/>
MKV files that contain audio/subtitle tracks with language codes with subtags are not yet supported, but from <code>Kodi v21</code> a workaround was introduced that allows Kodi to recognize language codes with subtags.
To use the workaround, you must open the MKV file with an editor and in the metadata of the desired audio/subtitle track, edit the track Name (or Title field) by adding the language code wrapped in curly brackets, as in following example:
<br/><code>Original track name: Audio portuguese/brazil</code>
<br/><code>Modified track name: Audio portuguese/brazil {pt-BR}</code>

'''How to extend an existing language code:'''

Set the same "long" description of the existing language, for example we reuse the Portughese language for another language code:

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>pt-BR</short>
<long>Portuguese</long>
</code>
</languagecodes>
</syntaxhighlight>

In this case when in Kodi settings you set the "Portuguese" language, when in playing according to availability the track "pt" or "pt-BR" will be chosen.

'''How to override an existing language code:'''

This allow you to rename an existing language. Set to an existing language code your preferred "long" name description.

''WARNING: This can cause problems with add-ons, so do not override languages if you are not aware of the side effects.''

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>en</short>
<long>English example</long>
</code>
<code>
<short>en-GB</short>
<long>English example</long>
</code>
</languagecodes>
</syntaxhighlight>

=== moviestacking ===
{{anchor|.3Cmoviestacking.3E}}<section begin="moviestacking" />
{{main|Naming_video_files/Movies}}
This is used by the [[Naming_video_files/Movies#Split_Video_Files|file stacking]] algorithm to combine multi-part files and contains a list of regular expressions. For stacking videos that are contained in folders, such as VIDEO_TS folders, see '''[[advancedsettings.xml#folderstacking|<folderstacking>]]'''

As of v9.11, video stacking regular expressions '''must''' contain exactly four (4) capture expressions.

Default:
<syntaxhighlight lang=xml enclose="div">
<moviestacking>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[0-9]+)(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[a-d])(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ ._-]*[a-d])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="append"</tt> or <tt>append="yes"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the end.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="append">

<regexp>(.*?)([ ._-]*[0-9])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="prepend"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the beginning.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="prepend">
<regexp>(Title)(Volume)(Ignore)(Extension)</regexp>
</moviestacking>
</syntaxhighlight>

If no argument is supplied, or the argument <tt>append="no"</tt> is supplied, the default moviestacking regular expressions are overwritten by the user specified ones.
<section end="moviestacking" />

=== folderstacking ===
{{main|Naming_video_files/Movies}}
This is similar to '''[[advancedsettings.xml#moviestacking|<moviestacking>]]''', but is used for videos that are contained in folders that use the folder names to stack, such as VIDEO_TS folders (DVD rips that are not in ISO format).

Default:
<syntaxhighlight lang=xml enclose="div">
<folderstacking>

<regexp>((cd|dvd|dis[ck])[0-9]+)$</regexp>
</folderstacking>
</syntaxhighlight>

=== cleandatetime ===
{{anchor|.3Ccleandatetime.3E}}
Matches a year number in a string using a Regular Expression

Default expression:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleandatetime>(.*[^ _\,\.\[\]\-])[ _\.\[\]\-]+(19[0-9][0-9]|20[0-9][0-9])([ _\,\.\[\]\-]|[^0-9]$)?</cleandatetime>
</video>
</syntaxhighlight>
:* The string found before will be used as basis string getting cleaned by the cleanstrings expressions.
:* By default date formats like MM:YY are ignored.

=== cleanstrings ===
{{anchor|.3Ccleanstrings.3E}}
Clean unwanted characters from filenames or folders by using a list of Regular Expressions. Please note that everything right of the match (at the end of the file name) is removed, so if you would have a file named ''Super movie.mp4'' and would add <tt><regexp> </regexp></tt> (only a space), the only thing that would be left is ''Super'', which is probably not what you want.

{{Github_link|[https://github.com/xbmc/xbmc/blob/Nexus/xbmc/settings/AdvancedSettings.cpp#L201-L211 Code in Github]}}

Default expressions:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleanstrings>
<regexp>([ _\\,\\.\$\$\\[\\]\\-](10bit|480p|480i|576p|576i|720p|720i|1080p|1080i|2160p|3d|aac|ac3|aka|atmos|avi|bd5|bdrip|bluray|brrip|cam|cd[1-9]|custom|dc|ddp|divx|divx5|dolbydigital|dolbyvision|dsr|dsrip|dts|dts-hdma|dts-hra|dts-x|dv|dvd|dvd5|dvd9|dvdivx|dvdrip|dvdscr|dvdscreener|extended|fragment|fs|h264|h265|hdr|hdr10|hevc|hddvd|hdrip|hdtv|hdtvrip|hrhd|hrhdtv|internal|limited|multisubs|nfofix|ntsc|ogg|ogm|pal|pdtv|proper|r3|r5|read.nfo|remastered|remux|repack|rerip|retail|screener|se|svcd|tc|telecine|telesync|truehd|ts|uhd|unrated|ws|x264|x265|xvid|xvidvd|xxx|web-dl|webrip|www.www|\\[.*\\])([ _\\,\\.\$\$\\[\\]\\-]|$)");</regexp>
<regexp>(\[.*\])</regexp>
</cleanstrings>
</video>
</syntaxhighlight>
Updated in v20<ref>https://github.com/xbmc/xbmc/pull/20549</ref>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== tvshowmatching ===
{{anchor|.3Ctvshowmatching.3E}}
Matches the season and episode numbers in file paths by using a list of Regular Expressions

{{Github_link|[https://github.com/xbmc/xbmc/blob/Matrix/xbmc/settings/AdvancedSettings.cpp#L232 Code in Github]}}

Defaults:
<syntaxhighlight lang=xml enclose="div">
<tvshowmatching>
<regexp>s([0-9]+)[ ._x-]*e([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)([^\\\\/]*)$</regexp> 
<regexp>[\._ -]()[Ee][Pp]_?([0-9]+)([^\\/]*)$</regexp> 
<regexp>([0-9]{4})[\.-]([0-9]{2})[\.-]([0-9]{2})</regexp> 
<regexp>([0-9]{2})[\.-]([0-9]{2})[\.-]([0-9]{4})</regexp> 
<regexp>[\\/\._ \[\(-]([0-9]+)x([0-9]+)([^\\/]*)$</regexp> 
<regexp>[\\/\._ -]([0-9]+)([0-9][0-9])([\._ -][^\\/]*)$</regexp> 
<regexp>[\/._ -]p(?:ar)?t[_. -]()([ivx]+)([._ -][^\/]*)$</regexp> 
</tvshowmatching>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)
:* Paths are converted to lower case before matching.
:* For multi-episode matching to work, there needs to be a third set of parentheses '()' at the end, this part is fed back into the regexp engine.
:* A [https://forum.kodi.tv/showthread.php?tid=51614 forum thread] has a discussion of pre-made regex lists to match common names. These might improve Kodi's ability to match TV show names in some situations, at the risk of additional false positives.

==== Filenames without Season ====
There are two methods to add episodes without a season in their file path. Both ways will force the season to '1' by default, so that you can use
the 'Use Absolute Ordering (Single Season)' setting from the TheTvDb.com scraper.

; Simple Method ''(XBMC v9.11 onwards and Kodi)''
: Use only one pair of parentheses
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]([0-9]+)</regexp></syntaxhighlight>
; Advanced Method ''(XBMC v10.05 onwards and Kodi)''
: Supports multi-episode files without season
: Use an empty pair of parentheses for the season
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

; Specifying Default Season ''(XBMC v12.0 onwards and Kodi)''
It is possible to set the default season for specific regular expressions by setting the 'defaultseason' attribute.
: Works with both the simple method and advanced method
: If not used, the season will be set to '1'
: Useful for setting specials to season '0'
<syntaxhighlight lang=xml enclose="div"><regexp defaultseason="0">[/\._ \-]X()([0-9]+)(-[0-9]+)?</regexp>
<regexp defaultseason="1">[/\._ \-]E()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

=== tvmultipartmatching ===
{{anchor|.3Ctvmultipartmatching.3E}}
Matches a multipart episode number based on a previously identified episode file, using a list of Regular Expressions.

Default:
<syntaxhighlight lang=xml enclose="div">
<tvmultipartmatching>^[-_ex]+([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)</tvmultipartmatching>
</syntaxhighlight>
:* Text matching is compared case-insensitive.
:* Specifying this option '''replaces''' the default value

=== excludefromscan ===
{{anchor|.3Cexcludefromscan.3E}}
Matches filenames or folders which should be excluded from a library scan (except tvshows) using a list of Regular Expressions. This can be for both Video or Audio sections of <tt>advancedsettings.xml</tt>.

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromscan>
<regexp>-trailer</regexp>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludefromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== excludefromlisting ===
{{anchor|.3Cexcludefromlisting.3E}}
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromlisting> 
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</video>
</syntaxhighlight>

=== excludetvshowsfromscan ===
{{anchor|.3Cexcludetvshowsfromscan.3E}}
Matches filenames or folders which should be excluded from a tvshow library scan using a list of Regular Expressions

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludetvshowsfromscan>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludetvshowsfromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== trailermatching ===
{{anchor|.3Ctrailermatching.3E}}
Contains Regular Expression syntax to match the locally stored trailers to movies in the library.

<syntaxhighlight lang=xml enclose="div">
<trailermatching>

<regexp>(.*?)(_Trailer)(\.[^.]+)$</regexp>
</trailermatching>
</syntaxhighlight>

=== videolibrary ===
{{anchor|.3Cvideolibrary.3E}}
Options specific to the Video Library

{{Note|Kodi v20 users don't need set "importwatched" or "importresumepoint" to true anymore as that's the default then <ref>https://github.com/xbmc/xbmc/pull/20842</ref>}}

<syntaxhighlight lang="xml" line='line'>
<videolibrary>
<allitemsonbottom>false</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<usefasthash>true</usefasthash> 
<recentlyaddeditems>35</recentlyaddeditems> 
<itemseparator> / </itemseparator> 
<exportautothumbs>false</exportautothumbs> 
<importwatchedstate>false</importwatchedstate> 
<importresumepoint>false</importresumepoint> 
<dateadded>1</dateadded> 
</videolibrary>
</syntaxhighlight>

=== videoscanner ===
{{anchor|.3Cvideoscanner.3E}}
Options specific to the Video scanner
<syntaxhighlight lang=xml enclose="div">
<videoscanner>
<ignoreerrors>true</ignoreerrors> 
</videoscanner>
</syntaxhighlight>

== Library artwork ==

{{note|Using <imageres>9999</imageres> and <fanartres>9999</fanartres> will allow caching artwork at original size.}}

=== imageres ===
{{anchor|.3Cimageres.3E}}

<section begin="imageres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached artwork]] (other than fanart / 16:9 images) should be resized to in pixels. The width is automatically calculated as being 16/9*height. The image will be resized to fit within this size. e.g. an image that is 2000x500 will be cached at size 1280x320. An image that is 500x800 will be cached at size 450x720 using the default value of 720.<section end="imageres description" />

<syntaxhighlight lang=xml enclose="div">
<imageres>720</imageres>
</syntaxhighlight>

=== fanartres ===
{{anchor|.3Cfanartres.3E}}

<section begin="fanartres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached fanart]] should be resized to in pixels. The width is automatically calculated as being 16/9*height. Only images that are exactly 16x9 and equal to or greater than this resolution will be cached at this size - all other images will be cached using <imageres>. The default value is 1080.<section end="fanartres description" />

<syntaxhighlight lang=xml enclose="div">
<fanartres>1080</fanartres>
</syntaxhighlight>

=== imagescalingalgorithm ===
Specify the image scaling algorithm for image resizing when [[Artwork/Cache#Texture optimization| caching artwork]] to the local texture cache.
<br />
<syntaxhighlight lang=xml enclose="div">
<imagescalingalgorithm>bicubic</imagescalingalgorithm>
</syntaxhighlight>

[https://github.com/xbmc/xbmc/blob/master/xbmc/pictures/PictureScalingAlgorithm.cpp#L20-L32 Available image scaling algorithms]

<syntaxhighlight lang=text enclose="div">
fast_bilinear
bilinear
bicubic
experimental
nearest_neighbor
averaging_area
bicublin
gaussian
sinc
lanczos
bicubic_spline
</syntaxhighlight>

=== imagequalityjpeg ===
This specifies the quality of the images when stored in jpeg format. By default kodi uses a quality of 4 which is a good compromise between size and quality. If you want to reduce the thumbnail sizes (decreasing quality) choose a higher value up to 21. If high quality (large thumbnail size) is needed, chose a smaller value, e.g. 0,1,2 or 3. (Added in v20 <ref>https://github.com/xbmc/xbmc/pull/21418</ref>)
<br />
<syntaxhighlight lang=xml enclose="div">
<imagequalityjpeg>4</imagequalityjpeg>
</syntaxhighlight>

== Video and music library settings ==

=== playlistasfolders ===
{{anchor|.3Cplaylistasfolders.3E}}
In the recent releases, playlists are treated as folders. Selecting a playlist no longer plays it, but opens it, as if it were a folder.

Set to false to revert to the previous behaviour. When you select a playlist, its content is added to the list of elements to be played.

:{{note|This setting will not affect smart playlists, they will always show as folders.}}

;Example
<syntaxhighlight lang=xml enclose="div">
<playlistasfolders>true</playlistasfolders>
</syntaxhighlight>

=== playlistretries ===
{{anchor|.3Cplaylistretries.3E}}
The number of retries attempted if a source is offline. With this control you can alter the number of consecutive failed items before a playlist fails.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlistretries>100</playlistretries>
</syntaxhighlight>

=== playlisttimeout ===
{{anchor|.3Cplaylisttimeout.3E}}
The timeout, in seconds, before item failure.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlisttimeout>20</playlisttimeout>
</syntaxhighlight>

=== sorttokens ===
Allows you to specify additional tokens that will be ignored at the start of lines during sorting.
{{note|Sort tokens are case sensitive.}}
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token>the</token>
</sorttokens>
</syntaxhighlight>

In the above example "the ", "the." and "the_" will be ignored at the start of titles or names when sorting items, in both video and music libraries. A separator can also be specified, for example
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token separators="'">L</token>
</sorttokens>
</syntaxhighlight>
In that case the value L', as in French movie name ''L'argent'', will be ignored and the item listed under "A".

=== musicdatabase/videodatabase ===
{{anchor|.3Cmusicdatabase.3E/.3Cvideodatabase.3E|musicdatabase/videodatabase|database tags music/video/tv/epg/adsp}}
{{main|MySQL}}
<section begin="videodatabase" />
Allows advanced customization of the default database settings for music, video, TV, EPG, and ADSP databases.

:{{note| '''It is HIGHLY recommended that you not attempt to place an sqlite3 database outside of kodi's path. sqlite3 contains no filesystem abstraction, so this will plain break on any non-local (as far as Kodi is concerned) paths. Use this for mysql only.'''}}

'''Parent tags:'''

* '''<videodatabase>'''
* '''<musicdatabase>'''
* '''<tvdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<epgdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<adspdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
{{MySQL warning}}

'''Child tags: '''

;<type>
: ''Required'' - Can be either "sqlite3" or "mysql" (default: sqlite3)

;<host>
:''Required'' -
* sqlite3: defines the relative path to the database file (eg. /usr/local/kodi/databases).
* mysql: defines the host of the mysql socket (eg. localhost, 192.168.0.1, etc)

;<port>
: ''Optional'' -
* sqlite3: silently ignored
* mysql: defines the port of the mysql socket (default: 3306)

;<name>
: ''Optional'' -
:by default "MyVideos"+DB number will be used.
* sqlite3: defines the name of the database file to read from, excluding the ".db" extension.
* mysql: defines the name of the database to use

;<user>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the user with privileged access to the database

;<pass>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the password for the user with privileged access to the database

;<compression>
: ''Optional'' - Defaults to false. Set to "true" to enable MySQL compression protocol. Performance benefit is going to be largely dependent on the network bandwidth, latency between database and clients and on the size of the result sets. [https://github.com/xbmc/xbmc/pull/6484]
: {{Note|Slower clients (such as the RPi and others) won't benefit from it as the zlib de-compression overhead is higher than the actual compression savings}}

;<key>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<cert>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ca>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<capath>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ciphers>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

'''Examples:'''

1) Configure a database for MySQL.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<videodatabase>
<type>mysql</type>
<host>192.168.0.10</host>
<name>kodi_video</name>
<user>kodi</user>
<pass>kodi</pass>
</videodatabase>
</syntaxhighlight>

2) Configure a database for an sqlite database.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<musicdatabase>
<type>sqlite3</type>
<host>/usr/local/share/kodi/databases</host>
</musicdatabase>
</syntaxhighlight>

<section end="videodatabase" />

=== externalplayer ===
{{anchor|.3Cexternalplayer.3E}}
{{see|External players}}

== Music settings ==

=== musicextensions ===
{{anchor|.3Cmusicextensions.3E}}
<section begin="musicextensions" />
Default extensions for MUSIC:
<pre>
.nsv .m4a .flac .aac .strm .pls .rm .rma .mpa .wav .wma .ogg .mp3 .mp2 .m3u .gdm .imf .m15 .sfx
.uni .ac3 .dts .cue .aif .aiff .wpl .xspf .ape .mac .mpc .mp+ .mpp .shn .zip .wv .dsp .xsp .xwav
.waa .wvs .wam .gcm .idsp .mpdsp .mss .spt .rsd .sap .cmc .cmr .dmc .mpt .mpd .rmt .tmc .tm8
.tm2 .oga .url .pxml .tta .rss .wtv .mka .tak .opus .dff .dsf .m4b .dtshd
</pre>

It is possible to add or remove extensions for Music, using the following XML tags. Useful if you keep, say, FLAC and mp3 versions of music in the same folder. The <remove> tag can be used to remove mp3 from being listed in the library, leaving only the higher quality FLAC being displayed.

<musicextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</musicextensions>

<section end="musicextensions" />

=== cddbaddress ===
{{anchor|.3Ccddbaddress.3E}}
The address of the online CDDb database. You may set this to another freedb mirror if there is a more suitable one.

Default:
<syntaxhighlight lang=xml enclose="div>
<cddbaddress>freedb.freedb.org</cddbaddress>
</syntaxhighlight>

=== songinfoduration ===
{{anchor|.3Csonginfoduration.3E}}
This controls how long the song information will remain onscreen when the song changes during visualisations. The valid range is "1" to "Indefinite (0)", in seconds. This does not include the duration of any transition effects.

Default:
<syntaxhighlight lang=xml enclose="div">
<songinfoduration>10</songinfoduration>
</syntaxhighlight>

=== musicfilenamefilters ===
{{anchor|.3Cmusicfilenamefilters.3E}}
Contains filters to match music information (artist, title etc.) from a tag-less music filename. The first <filter> to match completely is used. Matched items include:

<pre>
%A - Artist
%T - Title
%B - Album
%N - Track number
%S - Part of set (disk number)
%D - Duration
%G - Genre
%Y - Year
%R - Rating
</pre>

Example:
<syntaxhighlight lang=xml enclose="div">
<musicfilenamefilters>
<filter>%A - %T</filter>
</musicfilenamefilters>
</syntaxhighlight>

=== musiclibrary ===
Options specific to the Music Library
<section begin="MusicLibrary" />
<syntaxhighlight lang="xml" line='line'>
<musiclibrary>
<allitemsonbottom>true</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<recentlyaddeditems>35</recentlyaddeditems> 
<albumformat>%B - %Y</albumformat> 
<prioritiseapetags>true</prioritiseapetags> 
<itemseparator> / </itemseparator> 
<artistseparators> 
<separator>;</separator>
<separator>:</separator>
<separator>|</separator>
<separator> feat. </separator>
<separator> ft. </separator>
</artistseparators>
<dateadded>1</dateadded> 


<useisodates>false</useisodates> 
</musiclibrary>
</syntaxhighlight>
{{Note|Changing the <itemseparator> or <artistseparators> will only affect newly added items. A rescan won't change the existing ones. Remove the Source(s) or delete the Music DB and rebuild. This process should be made easier from v18 and up using <promptfulltagscan>}}<section end="MusicLibrary" />

== Photos settings ==

=== pictureextensions ===
{{anchor|.3Cpictureextensions.3E}}
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Pictures window.

Default extensions for PICTURES:
<pre>
.png .jpg .jpeg .bmp .gif .ico .tif .tiff .tga .pcx .cbz .zip .rss .webp .jp2 .apng
</pre>

Examples:
<syntaxhighlight lang=xml enclose="div">
<pictureextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</pictureextensions>
</syntaxhighlight>

=== pictureexcludes ===
{{anchor|.3Cpictureexcludes.3E}}
Matches filenames or folders which should be excluded from being displayed in My Pictures using a list of Regular Expressions

<syntaxhighlight lang=xml enclose="div">
<pictureexcludes> 
<regexp>small</regexp>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</pictureexcludes>
</syntaxhighlight>

=== slideshow ===
{{anchor|.3Cslideshow.3E}}
<syntaxhighlight lang=xml enclose="div">
<slideshow>

<panamount>2.5</panamount>

<zoomamount>5.0</zoomamount>



<blackbarcompensation>20</blackbarcompensation>
</slideshow>
</syntaxhighlight>

== Network settings ==

=== ftp ===
{{anchor|.3Cftp.3DE}}
Specific settings if a ftp server is in use as a source

<syntaxhighlight lang=xml enclose="div">
<ftp>
<remotethumbs>true</remotethumbs> 
</ftp>
</syntaxhighlight>

=== samba ===
{{anchor|.3Csamba.3E}}
<syntaxhighlight lang=xml enclose="div">
<samba>
<doscodepage></doscodepage> 
<clienttimeout>10</clienttimeout> 
<statfiles>true</statfiles> 
</samba>
</syntaxhighlight>

=== hosts ===
{{anchor|.3Cfhosts.3E}}
Static dns entries which take precedence over your dns server.
<syntaxhighlight lang=xml enclose="div">
<hosts>
<entry name="HOSTNAME">IPADDRESS</entry>
</hosts>
</syntaxhighlight>

=== network ===
{{anchor|.3Cnetwork.3E}}

<syntaxhighlight lang=xml line='line'>
<network>
<curlclienttimeout>10</curlclienttimeout> 
<curllowspeedtime>20</curllowspeedtime> 
<curlretries>2</curlretries> 
<httpproxyusername></httpproxyusername> 
<httpproxypassword></httpproxypassword> 
<disableipv6>false</disableipv6> 
<disablehttp2>false</disablehttp2> 
<nfstimeout>30</nfstimeout> 
<catrustfile>filepath</catrustfile> 
<curlkeepaliveinterval>30</curlkeepaliveinterval> 
<nfsretries>0</nfsretries> 
</network>
</syntaxhighlight>

'''More information:'''<br>
* <curlkeepaliveinterval><ref>https://github.com/xbmc/xbmc/pull/19319</ref><br>
* <nfsretries><ref>https://github.com/xbmc/xbmc/pull/19513</ref>

=== cache ===
{{see also|HOW-TO:Modify_the_video_cache}}
<syntaxhighlight lang=xml enclose="div">
<cache>
<memorysize>0</memorysize> 
<buffermode>0</buffermode> 
<readfactor>4.0</readfactor> 
<chunksize>65536</chunksize> 
</cache>
</syntaxhighlight>

=== airtunesport ===
{{anchor|.3Cairtunesport.3E}}<section begin="airtunesport" />
This overwrites the defalt listening port of the AirTunes server (announced via zeroconf).
<section end="airtunesport" />

=== airplayport ===
{{anchor|.3Cairplayport.3E}}<section begin="airplayport" />
This overwrites the default listening port of the AirPlay server (announced via zeroconf).
<section end="airplayport" />

== File system settings ==

=== packagefoldersize ===
<section begin="packagefoldersize" />
{{anchor|.3Cpackagefoldersize.3E}}
{{xml setting
| tag name = packagefoldersize
| option type = numerical
| option values =
| default values = 200
| platform = all
| XBMC version = 12
| description = The amount (in megabytes) of add-on zip packages saved from previous add-on installs. These packages are mainly used for the [[Add-ons|add-on]] rollback feature. Increasing the size should increase the amount of past versions saved. Defaults to 200 MB.
| example = Example: <syntaxhighlight lang=xml enclose="div"><packagefoldersize>200</packagefoldersize> </syntaxhighlight>
}}
<section end="packagefoldersize" />

=== detectasudf ===
{{anchor|.3Cdetectasudf.3E}}
{{xml setting
| tag name = detectasudf
| option type = binary
| option values = true, false
| default values = false
| platform = all
| XBMC version =
| description = Set to true if you wish to detect joint ISO9660/UDF disks as UDF.
| example = Example: <syntaxhighlight lang=xml enclose="div"><detectasudf>false</detectasudf></syntaxhighlight>
}}

=== handlemounting ===
{{anchor|.3Chandlemounting.3E}}
{{xml setting
| tag name = handlemounting
| option type = binary
| option values = true, false
| default values = false
| platform = Linux
| XBMC version =
| description = Only used in Linux, it defines if Kodi should attempt to mount media drives (via udisks or udisks2).<br/>Default: False. If kodi is executed with the --standalone option (e.g. as done by kodi-standalone.sh) it by default will be True.
| example = Example: <syntaxhighlight lang=xml enclose="div"><handlemounting>false</handlemounting></syntaxhighlight>
}}

=== automountopticalmedia ===
{{xml setting
| tag name = automountopticalmedia
| option type = binary
| option values = true, false
| default values = false
| platform = Linux
| XBMC version =
| description = Only used in linux for the udisks and udisks2 providers<br/>defines if kodi should automount optical discs<ref>https://github.com/xbmc/xbmc/pull/20840</ref>
| example = Example: <syntaxhighlight lang=xml enclose="div"><automountopticalmedia>true</automountopticalmedia></syntaxhighlight>
}}

=== pathsubstitution ===
{{anchor|.3Cpathsubstitution.3E}}
{{main|Path substitution}}

{{divbox|red||'''Note:''' Path substition for "sources" and profiles is broken, and will '''NOT''' be fixed.}}

Path substitutions are for use for redirecting file paths. These are processed in order, and are useful for substituting an absolute path on a PC with a path suitable for Kodi to handle.

Default: No path substitutions defined.

Example:
<syntaxhighlight lang=xml enclose="div">
<pathsubstitution>
<substitute>
<from>G:\dvds\</from>
<to>smb://somecomputer/g-share/dvds/</to> 
</substitute>
</pathsubstitution>
</syntaxhighlight>

== Input control settings ==

=== remotedelay ===
{{anchor|.3Cremotedelay.3E}}
The repeat delay for a LIRC remote control. A delay value between 1 and 20 before a remote button starts repeating on a long keypress (i.e. continuously sending button pushes while it's held down).

Default: 3
<syntaxhighlight lang=xml enclose="div">
<remotedelay>10</remotedelay>
</syntaxhighlight>

=== controllerdeadzone ===
{{anchor|.3Ccontrollerdeadzone.3E}}
This advanced settings has been removed.
Since v17, the [[Advancedsettings.xml#controllerdeadzone|<controllerdeadzone>]] advanced setting has been removed. Deadzones can now be configured by plugging in the controller and selecting it in Settings -> System settings -> Input -> Peripherals.

=== enablemultimediakeys ===
{{anchor|.3Cenablemultimediakeys.3E}}
This setting only has any effect on Windows versions of Kodi, and only applies to builds from 28th May 2011 onwards.
In Windows the multimedia keys generate a WM_APPCOMMAND message in addition the keypress. Kodi processes both keypresses and the WM_APPCOMMAND messages, and the end result would be that the command is executed twice. To avoid this, by default multimedia keypresses are disabled. Although it should rarely be necessary, the enablemultimediakeys setting allows you to enable the multimedia keys.

Example:
<syntaxhighlight lang=xml enclose="div">
<enablemultimediakeys>true</enablemultimediakeys>
</syntaxhighlight>

=== seeksteps ===
{{Main|Skip steps}}

This setting changes which increments are available in the settings GUI for additive seeking. Note that <code><seeksteps></code> is not used to actually choose which seek steps are enabled.

'''Default:'''
<syntaxhighlight lang=xml enclose="div">
<seeksteps>7, 15, 30, 60, 180, 300, 600, 900, 1800</seeksteps>
</syntaxhighlight>

{{editor note|the defaults need to be updated for seeksteps.}}

=== touchscreen ===
{{anchor|.3Ctouchscreen.3E}}
This setting allows you to move/align the origin of the touch screen with the origin of the display used. If touch input does not result in a correct movement of the mouse pointer, the behaviour can be corrected with an offset and a stretch/compress factor.

Example:
<syntaxhighlight lang=xml enclose="div">
<touchscreen>
<x_offset>0</x_offset> 
<y_offset>0</y_offset> 
<x_stretch_factor>1.0</x_stretch_factor> 
<y_stretch_factor>1.0</y_stretch_factor> 
</touchscreen>
</syntaxhighlight>

=== scanirserver ===
Introduced in v18 and used in MS Windows setups only.<ref>https://github.com/xbmc/xbmc/pull/13896</ref>
Used to disable the regular connection attempts to the IR Server Suite when there is no remote to connect to.

The default setting is to allow connection attempts. To disable connection attempts change value to '''false'''.
<syntaxhighlight lang=xml enclose="div">
<scanirserver>true</scanirserver>
</syntaxhighlight>

== Other interface settings ==

=== window ===
{{anchor|.3Cwindow.3E}}
{{note|This is a "hidden" guisettings.xml setting (defined by the mouse moving the window size), but it is mentioned here because it is a particularly useful override when used in advancedsettings.xml}}
This allows you to manually set the default size of Kodi's windowed mode. If you resize the window, it will return to the set size when restarting.

WIDTH and HEIGHT are the values for each dimension, in pixels.

<syntaxhighlight lang=xml enclose="div">
<window>
<width>WIDTH</width>
<height>HEIGHT</height>
</window>
</syntaxhighlight>

=== restrictcapsmask ===
{{anchor|.3Crestrictcapsmask.3E}}
Windows only. A bitmask to prevent Kodi from using detected texture capabilities of the GPU. This helps work around buggy hardware/drivers.

1: prevent the use of compressed textures (DXT1, DXT3, DXT5)
2: prevent the use of non-power-of-two dimensions for textures
4: prevent the use of compressed textures with non-power-of-two dimensions.

<syntaxhighlight lang=xml enclose="div">
<restrictcapsmask>0</restrictcapsmask>
</syntaxhighlight>

=== algorithmdirtyregions ===
{{anchor|.3Calgorithmdirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="algorithmdirtyregions" />{{note|Some GPU/hardware configurations will have some minor issues (such as a visual "flicker"). For those situations try mode 2 or use the default (mode 3, which requires no advancedsetting). Almost all ARM-based devices (such as [[Android]]) willl likely have flickering issues.}}

Enable dirty-region processing. Dirty regions are any parts of the screen that have changed since the last frame. By not re-rendering what hasn't changed the GUI can be sped up. Because all GPUs work differently, only Mode 3 is guaranteed to work for everyone without flickering issues. This mode will reduce CPU/GPU usage, but will not increase GUI speed.

{| class="prettytable"
! value !! result !! description
|-
! 0
| Off
| The entire viewport is always rendered.
|-
! 1
|Union
|All dirty regions are grouped into the smallest possible rectangle. This is typically the fastest mode for slower GPUs due to only making one pass.
|-
! 2
| {{nowrap|Cost reduction}}
| Each dirty region is presented separately, in as many passes as there are regions.
|-
! 3
| {{nowrap|Whole Screen}}
| The entire screen is rendered if there are any dirty regions. This is a safe default for drivers that clear buffer contents (manifests as blinking or vibrating images). '''Default'''
|}<section end="algorithmdirtyregions" />

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<algorithmdirtyregions>1</algorithmdirtyregions>
</gui>
</syntaxhighlight>

=== visualizedirtyregions ===
{{anchor|.3Cvisualizedirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="visualizedirtyregions" />Enable dirty-region visualization. Paints a rectangle over marked controls.

* true: on
* false: off '''(Default)'''

{{note|This is only a development mode and isn't of use to normal users.}}
<section end="visualizedirtyregions" />
Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<visualizedirtyregions>true</visualizedirtyregions>
</gui>
</syntaxhighlight>

=== smartredraw ===

{{note|This is an experimental feature and you might face issues using it. So please be aware of that.}}

This new feature was introduced in Kodi 18 and if enabled, the GUI process call (and therefore the render call) is only done if anything has changed. The result will be a faster GUI and less load if Kodi plays a video

* true: on
* false: off '''(Default)'''

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<smartredraw>true</smartredraw>
</gui>
</syntaxhighlight>

=== showexitbutton ===
{{anchor|.3Cshowexitbutton.3E}}
Setting to hide the exit button, useful for people running appliance based setups where exit would only confuse/complicate the user. Modifiable via the advancedsettings.xml by setting showexitbutton to false, default is true (show)

Example:
<syntaxhighlight lang=xml enclose="div">
<showexitbutton>true</showexitbutton>
</syntaxhighlight>

=== fullscreen ===
{{anchor|.3Cfullscreen.3E}}
Starts Kodi in full screen (check resolutions!).

<syntaxhighlight lang=xml enclose="div">
<fullscreen>false</fullscreen>
</syntaxhighlight>

=== splash ===
{{anchor|.3Csplash.3E}}
Set to false if you wish to disable the startup splash image. Defaults to true.

<syntaxhighlight lang=xml enclose="div">
<splash>true</splash>
</syntaxhighlight>

=== cputempcommand ===
{{anchor|.3Ccputempcommand.3E}}
Provide a shell command Kodi will use to get CPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia and Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sed -e 's/$[0-9]*$[0-9]\{3\}.*/\1 C/' /sys/class/thermal/thermal_zone0/temp</cputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>echo "$(sensors -u | tail -n64 | grep temp1_input | awk '{print $2 }' |awk '{printf("%d\n",$1 + 0.5);}') C"</cputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sensors|sed -ne "s/temp1: \+[-+]$[0-9]\+$.*/\1 C/p"</cputempcommand>
</syntaxhighlight>

=== gputempcommand ===
{{anchor|.3Cgputempcommand.3E}}
Provide a shell command Kodi will use to get GPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-settings -tq gpuCoreTemp) C"</gputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-smi -q -d TEMPERATURE | grep Gpu | cut -c35-36) C"</gputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/usr/bin/aticonfig --od-gettemperature | grep Temperature | cut -f 2 -d "-" | cut -f 1 -d "." | sed -e "s, ,," | sed 's/$/ C/'</gputempcommand>
</syntaxhighlight>

;<u>For Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/opt/vc/bin/vcgencmd measure_temp | sed -e "s/temp=//" -e "s/\..*'/ /"</gputempcommand>
</syntaxhighlight>

=== glrectanglehack ===
{{anchor|.3Cglrectanglehack.3E}}
Problems with ghosting or videos which are only played back in the left upper quarter? The following ATI hack may solve it.
<syntaxhighlight lang=xml enclose="div">
<glrectanglehack>yes</glrectanglehack>
</syntaxhighlight>

=== alwaysontop ===
{{anchor|.3Calwaysontop.3E}}
Added in XBMC v9.11 (Windows OS only). Keeps Kodi always on top when windowed.
<syntaxhighlight lang=xml enclose="div">
<alwaysontop>yes</alwaysontop>
</syntaxhighlight>

There is also a fake fullscreen GUI option in Kodi's settings.

=== minimizetotray ===
{{anchor|.3Cminimizetotray.3E}}
{{note|Available in Kodi v20 and above.}}

Windows only. Minimizes Kodi to the system tray. Defaults to false.
<syntaxhighlight lang=xml enclose="div">
<minimizetotray>true</minimizetotray>
</syntaxhighlight>

= Removed tags =
{{anchor|Recently removed tags}}
* {{anchor|.3Cthumbsize.3E}}'''<thumbsize>''' - replaced by <[[#imageres|imageres]]> in v12 Frodo
* {{anchor|.3Cfanartheight.3E}}'''<fanartheight>''' - replaced by <[[#fanartres|fanartres]]> in v12 Frodo
* {{anchor|.3Cdvdthumbs.3E}}'''<dvdthumbs>''' - removed in v12 Frodo
* {{anchor|.3Cbusydialogdelayms.3E}}'''<busydialogdelayms>''' - removed in v12 Frodo
* {{anchor|.3Cbginfoloadermaxthreads.3E}}'''<bginfoloadermaxthreads>''' - removed in v13 Gotham
* '''<showepginfoonselect>''' - replaced by a GUI setting in v13 Gotham
* '''<resample>''', '''<forceDirectSound>''', '''<audiophile>''', '''<audiosinkbufferdurationmsec>''', '''<allowtranscode44100>''', and '''<streamsilence>''' - These were various sub-tags for <audio> that were removed in v13 Gotham and either replaced by GUI settings or were no longer needed.
* {{anchor|.3Cenableairtunesdebuglog.3E}}'''<enableairtunesdebuglog>''' - replaced by a GUI option in v14 Helix
* '''<videoDisableHi10pMultithreading>''' - renamed to <disableswmultithreading> in v14 Helix
* '''<hideallitems>''' - For both the <code><videolibrary></code> and <code><musiclibrary></code> sections, this is replaced by a GUI option in v15 Isengard
* '''<SmallStepBackSeconds>''' - In v15 the <code>SmallStepBack</code> [[Action_IDs]] has been replaced by <code>seek(-7)</code> in default keymaps. See '''[[skip steps]]''' for details. When the original <code>SmallStepBack</code> action ID is used it defaults to the first backwards [[skip steps|additive seeking value]].
* '''<timeseekforward>/<timeseekbackward>''' - In v15 these tags are replaced by GUI options via [[skip steps|additive seeking]], which is configured in the GUI. See '''[[skip steps]]''' for details.
* {{anchor|.3Ckaraoke.3E}}'''<karaoke>''' - In v16 all of the karaoke features in Kodi were removed.
* '''<useddsfanart>''' - removed in v17 Krypton.
* '''<cachemembuffersize>''' and '''<readbufferfactor>''' - In v17 '''<cachemembuffersize>''' is renamed to '''<memorysize>''' and <code><readbufferfactor></code> is renamed to <code><readfactor></code>. In addition, all three buffer related settings in <network> are moved out of <network> and into a new <cache> parent tag.
* '''<minvideocachelevel>''', '''<minaudiocachelevel>''', and '''<cacheindvdplayer>''' have been removed in v17.
* '''<useffmpegvda>''' - Tag was only used for development testing. Removed in v17.
* '''<nofliptimeout>''' - Removed in v17
* '''<blackbarcolour>''' - Removed in v17 (maybe?)
* '''<disableswmultithreading>''' - Removed in v17 (maybe?)
* '''<controllerdeadzone>''' - Removed in v17
* {{anchor|.3Cmeasurerefreshrate.3E}}'''<measurerefreshrate>''' - Removed in v17 or v18?
* {{anchor|.3Cmyth.3E}}'''<myth>''' - Removed sometime between v16 to v18
* {{anchor|.3Ctuxbox.3E}}'''<tuxbox>''' - Removed
* '''<backgroundupdate>''' - Removed
* '''<hideemptyseries>''' - Replaced by a GUI option.
* '''<mymovies>''' and child tag '''<categoriestogenres>''' - Removed
* '''<albumssortbyartistthenyear'''> - Removed
* '''<albumformatright>''' - Removed
* {{anchor|.3Cremoterepeat.3E}}'''<remoterepeat>''' - Removed
* {{anchor|.3Callowd3d9ex.3E}}'''<allowd3d9ex>''' and {{anchor|.3Cforced3d9ex.3E}}'''<forced3d9ex>''' - Removed sometime between v16 to v18
* '''<lingertime>''' - Replaced by a GUI setting in v18
* '''<forcevaapienabled>''' - Removed in v18
* '''<dxvaallowhqscaling>''' - Removed in v18 <ref>https://github.com/xbmc/xbmc/pull/15466</ref>
* '''<promptfulltagscan>false</promptfulltagscan>''' Removed in v18. Now automatically asked each time a scan is conducted.
* '''<omxdecodestartwithvalidframe>''' - This tag is only in some Raspberry Pi specific distributions, such as OpenELEC. As of March 2015, this tag has not been merged into "vanilla" Kodi builds
* '''<musicthumbs>''' Replaced in v19 by the GUI setting '''Thumbnail image files''' found in Media -> Music
* '''<artistextraart>''' Replaced in v19 by the GUI setting '''Artist art types whitelist''' found in Media -> Music
* '''<albumextraart>''' Replaced in v19 by the GUI setting '''Album art types whitelist''' found in Media -> Music
* '''<episodeextraart>''' Replaced in v19 by the GUI setting '''Episode art types whitelist''' found in Media -> Videos
* '''<tvshowextraart>''' Replaced in v19 by the GUI setting '''TV show art types whitelist''' found in Media -> Videos
* '''<tvseasonextraart>''' Replaced in v19 by the GUI setting '''TV show art types whitelist''' found in Media -> Videos
* '''<movieextraart>''' Replaced in v19 by the GUI setting '''Movie art types whitelist''' found in Media -> Videos
* '''<moviesetextraart>''' Replaced in v19 by the GUI setting '''Movie art types whitelist''' found in Media -> Videos
* '''<musicvideoextraart>''' Replaced in v19 by the GUI setting '''Music video art types whitelist''' found in Media -> Videos
* '''<fanart>''' Removed in v19
* '''<assfixedworks>''' Removed in v20
* '''<try10bitoutput>''' Removed in v20 and replaced with [[Settings/System/Display#Use_10_bit_for_SDR|Use 10 bit for SDR]] setting <ref>https://github.com/xbmc/xbmc/pull/20014</ref>
* '''<enablehighqualityhwscalers>''' Removed in v20 <ref>https://github.com/xbmc/xbmc/pull/21537</ref>

= guisettings.xml Setting Conversion =
It is possible to convert settings found in the '''[[Settings]]''' ''(guisettings.xml)'' pages of {{kodi}} into entries for the advancedsettings.xml file.

When a setting from the guisettings.xml is added to the advancedsettings.xml file, it will override the existing guisettings.xml values and the setting will be removed from the settings pages.

Why would I need to do this?
* You set up multiple devices and then need to individually change settings and preferences on each device. Using this conversion method, you save those settings in the advancedsettings.xml file and simply add the file to each device
* You need to hide settings to prevent those settings from being modified

To convert a guisetting to advancedsettings.xml follow these steps:
# In the {{kodi}} settings pages, adjust the setting(s) to your preference.
# Back out of the settings pages to the main menu, which forces {{kodi}} to save the adjusted settings to the guisettings.xml file
# Locate the guisettings.xml file in the [[Userdata]] folder and open it
# Locate the setting(s) to be converted. The list can be overwhelming so make use of the Search feature of whichever editor you are using
# Using the following setting as an example:
<syntaxhighlight lang="xml">
<setting id="videolibrary.showemptytvshows">true</setting>
</syntaxhighlight>
: Breaking down the string:
::'''videolibrary'''- parent tag
::'''showemptytvshows'''- child tag
::'''true'''- value
: The conversion is as follows and place this in the advancedsettings.xml file
<syntaxhighlight lang="xml">
<advancedsettings version="1.0">
<videolibrary>
<showemptytvshows>true</showemptytvshows>
</videolibrary>
</advancedsettings>
</syntaxhighlight>

'''Note:''' Some parent tags may already be in use in your advancedsettings.xml file. Do not duplicate them, but add the child tag beneath the existing parent tag.

= References =
<references />

{{Updated|18}}
{{DISPLAYTITLE:advancedsettings.xml}}

[[Category:Advanced topics]]
[[Category:Manual]]
[[Category:Settings]]

Advancedsettings.xml

2024-01-21T11:54:47Z

Fritsch: Add allowmultichannelfloat.

{{TOC right}}{{mininav|[[Settings]]|page=advancedsettings.xml}}
{{bigger|{{note|'''The advancedsettings.xml file does not exist by default. You have to create it first!'''}} }}

<section begin="intro" />The [[advancedsettings.xml]] file, which does not exist by default, can be created by a user in their '''[[Userdata|userdata folder]]'''.

This file is used for advanced settings and options that do not have GUI controls inside of {{kodi}}. Some settings are experimental or very rarely set, so they can only be used via the advancedsettings.xml file. The file is simply a plain text file and can be edited by various text editors, so long as the name is "advancedsettings.xml". These advanced settings can be used to tweak various things such as episode naming patterns, special network ports, special behaviors, and more.<section end="intro" />

The following page will describe the structure of the advancedsettings.xml file and the various individual settings.

{{note|
# All XML tags must be lowercase. The start and end of the advancedsettings.xml file must have the <advancedsettings> and </advancedsettings> tags.
# Kodi will only read the advancedsettings.xml file when it starts up. If you make changes while it is running then you must restart Kodi.
# For some Windows versions, Kodi has two <code>\userdata\</code> folders. The correct one to put the advancedsettings.xml file in is not the one in Program Files, but in <code>%appdata%\Kodi\userdata\.</code>}}

== Layout ==

The layout of <code>advancedsettings.xml</code> is as follows:

<syntaxhighlight lang=xml enclose="div">
<advancedsettings version="1.0">
<setting>value</setting>
...
<setting>value</setting>
</advancedsettings>
</syntaxhighlight>

where "setting" gives the name of the setting, and "value" gives its value.

A list of the available "setting" strings and their values is given below.

= List of available settings =
List of available settings that are recognised in the advancedsettings.xml file <ref>https://github.com/xbmc/xbmc/blob/master/xbmc/settings/AdvancedSettings.cpp</ref>

Recommended: Use the table of contents or the search function in your browser to locate items.

== Troubleshooting settings ==

=== loglevel ===
{{Anchor|.3Cloglevel.3E}}

<section begin="loglevel" />
Sets the logging level used to log errors and information. The "hide" attribute is optional.

<syntaxhighlight lang=xml>
<loglevel hide="attribute">options</loglevel>
</syntaxhighlight>

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Attribute
! style="width:500px;" | Action
|-
! '''true'''
| Hides the "enable debugging" setting in the Settings page. (default)
|-
! '''false'''
| Allows "enable debugging" setting to switch between '''0''' and '''2'''.
|}

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Option
! style="width:500px;" | Action
|-
! '''-1'''
| No logging, suppresses all log output
|-
! '''0'''
| Normal logging, only logging errors (default)
|-
! '''1'''
| Debug logging with freemem, fps and cpu usage (no on screen)
|-
! '''2'''
| Same as 1 (with on screen display)
|-
! '''3'''
| Same as 1 + full smb logging
|}

{| class="wikitable"
|-
! style="width:100px;" | Example
! style="width:500px;" |
|-
! Example 1:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings version="1.0">
<loglevel>2</loglevel>
</advancedsettings>
</syntaxhighlight>
|-
! Example 2:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings version="1.0">
<loglevel hide="true">2</loglevel>
</advancedsettings>
</syntaxhighlight>
|}

'''Note:''' The setting is persistent through shutdown and restarts.<br>
'''Note:''' If debugging is enabled in the GUI, loglevel will be set to '''2'''. This will over-ride the <code>advancedsettings.xml</code> setting. You must disable the GUI Setting before adding the entry to <code>advancedsettings.xml</code>.<br />
<section end="loglevel" />
:''{{see also|Log_file|label 1=Debug Log}}''

=== jsonrpc ===
{{Anchor|.3Cjsonrpc.3E}}
To make it easier for developers using the [[JSON-RPC_API]] API in their (third party) applications to debug during development the json output of Kodi can be prettified by setting '''compactoutput''' to '''false'''. Default json output mode is a compact print which does not contain any unnecessary whitespaces and therefore is difficult to read for humans.
Furthermore using the '''tcpport''' setting it is possible to change the default TCP port used by Kodi for JSON RPC (which is 9090) to any other valid port.

Example:
<syntaxhighlight lang=xml enclose="div">
<jsonrpc>
<compactoutput>false</compactoutput>
<tcpport>9999</tcpport>
</jsonrpc>
</syntaxhighlight>

== Audio/video playback settings ==

=== skiploopfilter ===
{{anchor|.3Cskiploopfilter.3E}}
The amount of the loop filter to skip on h.264 decoding. This can help the performance of slower machines when decoding h264 content. Values, in decreasing CPU usage (and decreasing quality)
* -16 None
* 0 Skip only empty frames (default)
* 8 Skip non-reference frames
* 16 Skip bi-dir frames
* 32 Skip all non-key frames
* 48 Skip all frames
Example:
<syntaxhighlight lang=xml enclose="div">
<skiploopfilter>8</skiploopfilter>
</syntaxhighlight>

=== video ===
{{anchor|.3Cvideo.3E}}

The <video> section also includes the following child-tags, which have their own sections:
*[[#cleandatetime]]
*[[#cleanstrings]]
*[[#excludefromscan]]
*[[#excludefromlisting]]
*[[#excludetvshowsfromscan]]

{{note|Some tags that have a "third-level" and are grouped together are highlighted in color.}}

{| class="prettytable"
! Tag !! Description
|-
|
<syntaxhighlight lang=xml>
<video>
</syntaxhighlight>
| Parent tag that all other child tags need to be placed inside of. Do not use more than one '''<code><video></code>''' tag, but instead place all other child-tags within a single '''<code><video></video></code>''' set.
|-
|
<syntaxhighlight lang=xml>
<subsdelayrange>10</subsdelayrange>
</syntaxhighlight>
| Delay range for subtitles, in seconds.
|-
|
<syntaxhighlight lang=xml>
<maxtempo>2.1</maxtempo>
</syntaxhighlight>
| Allow further increase of playback speed over the default of 1.5<br>
maxtempo must be in the range of 1.5 to 2.1 <br>
Be aware of the limitations of your platform / hardware as not all are capable of the increased maxtempo <ref>https://forum.kodi.tv/showthread.php?tid=10023&pid=2795069#pid2795069</ref>
|-
|
<syntaxhighlight lang=xml>
<audiodelayrange>10</audiodelayrange>
</syntaxhighlight>
| Delay range for audio/video sync, in seconds.
|-
|
<syntaxhighlight lang=xml>
<usetimeseeking>true</usetimeseeking>
</syntaxhighlight>
| Whether to use time based or percentage based seeking. {{small see also|Skip steps}}
|-
|
<syntaxhighlight lang=xml>
<timeseekforwardbig>600</timeseekforwardbig>
<timeseekbackwardbig>-600</timeseekbackwardbig>
</syntaxhighlight>
| Time to seek forward in seconds when doing a long seek. Defaults to 600 (10 minutes) and -600 (-10 minutes) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforward>2</percentseekforward>
<percentseekbackward>-2</percentseekbackward>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a short seek. Defaults to 2 (2%) and -2 (2%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforwardbig>10</percentseekforwardbig>
<percentseekbackwardbig>-10</percentseekbackwardbig>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a long seek. Defaults to 10 (10%) and -10 (10%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<fullscreenonmoviestart>true</fullscreenonmoviestart>
</syntaxhighlight>
| Whether to go to fullscreen or not when starting a movie. Defaults to true.
|-
|
<syntaxhighlight lang=xml>
<defaultplayer>VideoPlayer</defaultplayer>
</syntaxhighlight>
| Set the default video player: VideoPlayer or an external player. See '''[[External players]]''' for more info.
|-
|
<syntaxhighlight lang=xml>
<excludefromscan>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromscan>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be added to library. It is possible to add multiple <code><regexp></code> tags to match multiple patterns
|-
|
<syntaxhighlight lang=xml>
<excludefromlisting>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be displayed in files view.
|-
|
<syntaxhighlight lang=xml>
<playcountminimumpercent>90</playcountminimumpercent>
</syntaxhighlight>
| Minimum percentage that has to be played before it is marked as watched. Set to 101 to never auto-mark items as watched. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignoresecondsatstart>180</ignoresecondsatstart>
</syntaxhighlight>
| Number of seconds to ignore at video start after which a resume point is created. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignorepercentatend>8</ignorepercentatend>
</syntaxhighlight>
| Percentage of video to ignore at the end. If you stop watching the video here no resume point is created. Set to 101 to never save a resume point. The video is already marked as watched at 90%, see above. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<vdpauscaling>true</vdpauscaling>
</syntaxhighlight>
| Scales with vdpau instead of opengl and turns on its HQ scaler when available, enabling this might slow down rendering and cause framedrops especially on ION systems, this setting requires a vdpau feature set C GPU.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegdeinterlacing>linblenddeint</ppffmpegdeinterlacing>
</syntaxhighlight>
| Override the deinterlacing options passed to libpostproc.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegpostprocessing>ha:128:7,va,dr</ppffmpegpostprocessing>
</syntaxhighlight>
| Override the post processing options passed to libpostproc when 'Video post-processing' is activated in GUI Videos-Settings-Playback.
|-
|
<syntaxhighlight lang=xml>
<autoscalemaxfps>30</autoscalemaxfps>
</syntaxhighlight>
| When scaling method is set to auto, bilinear is chosen when the fps is higher than this limit, the default is 30.
|-
|
<syntaxhighlight lang=xml>
<adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" | Settings for when "Adjust refreshrate to match video fps" is enabled in the video playback GUI settings.
|-
|
<syntaxhighlight lang=xml>
<override>
<fps>23.976</fps>
<refresh>60.0</refresh>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' "Adjust refreshrate to match video fps" will try to select the best refreshrate for the video fps but it doesn't always get it right, for example it might switch to an unsupported refreshrate. You can add overrides here to switch to a certain refreshrate based on video fps. It's possible to add as many overrides as you need. Overrides are processed in order, if the first one doesn't match the fps or no refreshrates match that override, it will try the next one until no overrides are left.

* '''fps''' - if the fps is between 23.966 and 23.986
* '''refresh''' - switch to the first found refreshrate that is between 59.99 and 60.01
|-
|
<syntaxhighlight lang=xml>
<override>
<fpsmin>29.96</fpsmin>
<fpsmax>30.01</fpsmax>
<refreshmin>59.0</refreshmin>
<refreshmax>61.0</refreshmax>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -'''
* '''fpsmin''' / '''fpsmin''' - You can also specify the fps range yourself.
* '''refreshmin''' / '''refreshmax''' - Same for the refreshrate
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refresh>50.0</refresh>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' If none of the overrides match, or none of the refreshrates match any of the fps matching overrides, it will choose a fallback refreshrate. Fallbacks are process in order, if the first fallback doesn't match any refreshrate, it will try the next one until no fallbacks are left.

* '''refresh''' - Switch to the first found refreshrate that is between 49.99 and 50.01.
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refreshmin>49.0</refreshmin>
<refreshmax>51.0</refreshmax>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' You can also specify the range for the fallback yourself.

If none of the overrides match the video fps, or no refreshrates match any of the fps matching overrides, and no fallbacks are specified or no refreshrates match any fallbacks, it will automatically choose the best refreshrate (same as having no overrides and fallbacks).
|-
|
<syntaxhighlight lang=xml>
</adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" |
|-
|
<syntaxhighlight lang=xml>
<checkdxvacompatibility>value</checkdxvacompatibility>
</syntaxhighlight>
| Advanced setting not present: let Kodi autodetect cards that support H.264 profile > L4.1. Set value to false to enable DXVA no matter what. Set value to true if Kodi doesn't autodetect that the graphics card doesn't support > L4.1.
|-
|
<syntaxhighlight lang=xml>
<useocclusionquery>-1</useocclusionquery>
</syntaxhighlight>
| Use an occlusion query when capturing videoframes, -1 means auto detect, 0 means disabled, 1 means enabled, the default is -1.
|-
|
<syntaxhighlight lang=xml>
<fpsdetect>1</fpsdetect>
</syntaxhighlight>
| FPS detection for video playback
* 0 = trust codec fps
* 1 = recalculate from video timestamps with uniform spacing
* 2 = recalculate from video timestamps always
|-
|
<syntaxhighlight lang=xml>
<latency>
</syntaxhighlight>
| style="background:#F0E68C;"| Start of '''latency''' tags. Display latency (video lag). Latency is given in msecs.
|-
|
<syntaxhighlight lang=xml>
<delay>0</delay>
</syntaxhighlight>
| style="background:#F0E68C;" | Global default display latency.
|-
|
<syntaxhighlight lang=xml>
<refresh></refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | Override latency for given display (not video) refresh rates. When Kodi is in windowed mode, override is ignored. Multiple overrides are allowed.

Syntax of an override entry:
<syntaxhighlight lang=xml>
<refresh>
<min>, <max> refresh rate range, OR
<rate> exact refresh rate
<delay> display latency for the given refresh rate
</refresh>
</syntaxhighlight>
|-
|
<syntaxhighlight lang=xml>
<refresh>
<min>23</min>
<max>24</max>
<delay>125</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 125 msec latency at 23-24 Hz
|-
|
<syntaxhighlight lang=xml>
<refresh>
<rate>50</rate>
<delay>50</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 50 msec latency at 50 (+/-0.01) Hz
|-
|
<syntaxhighlight lang=xml>
</latency>
</syntaxhighlight>
| style="background:#F0E68C;" |
|-
|
<syntaxhighlight lang=xml>
<stereoscopicregex3d>[-. _]3d[-. _]</stereoscopicregex3d>
<stereoscopicregexsbs>[-. _]h?sbs[-. _]</stereoscopicregexsbs>
<stereoscopicregextab>[-. _]h?tab[-. _]</stereoscopicregextab>
</syntaxhighlight>
| Filename triggers for 3D (stereoscopic) mode.
|-
|
<syntaxhighlight lang=xml>
<assfixedworks>false</assfixedworks>
</syntaxhighlight>
| Position behavior of ass subtitiles when setting "subtitle position on screen" set to "fixed". True to show at the fixed position set in video calibration. False to show at the bottom of video (default). {{note|Removed in Kodi v20.}}
|-
|
<syntaxhighlight lang=xml>
<subtitleverticalmargin>120</subtitleverticalmargin>
</syntaxhighlight>
| Allows to customise the vertical margin of text based subtitles, which will be applied to each type of subtitle position in subtitle settings. {{note|Available in Kodi v20 and above.}}
|-
|
<syntaxhighlight lang=xml>
</video>
</syntaxhighlight>
|
|}

=== audio ===
{{anchor|.3Caudio.3E}}
<syntaxhighlight lang=xml enclose="div">
<audio>

<headroom>0</headroom>

<defaultplayer>paplayer</defaultplayer>

<excludefromscan>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromscan>

<excludefromlisting>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromlisting>

<ac3downmixgain>12.0</ac3downmixgain>

<usetimeseeking>true</usetimeseeking>

<timeseekforwardbig>600</timeseekfowardbig>

<timeseekbackwardbig>-600</timeseekbackward>

<playcountminimumpercent>99</playcountminimumpercent>

<applydrc>-1.0</applydrc>

<limiterhold>0.025</limiterhold>

<limiterrelease>0.1</limiterrelease>

<maxpassthroughoffsyncduration>10</maxpassthroughoffsyncduration>

<allowmultichannelfloat>true</allowmultichannelfloat>
</audio>
</syntaxhighlight>

=== forcedswaptime ===
{{anchor|.3Cforcedswaptime.3E}}
Use to force a backbuffer->frontbuffer swap while vsync is enabled. Set to the time (in ms) to allow for the swap (e.g. <forcedswaptime>1</forcedswaptime> is typical).

Default: Off

=== edl ===
{{anchor|.3Cedl.3E}}
{{main|Edit_decision_list}}
Commercial break detection not as good you think it could be? Are some commercial breaks in a series of adverts not being skipped? Are some parts being skipped that are clearly not commercials? Does the end of the previous recording still show? The following advanced settings can be used to better identify full commercial break sequences, remove incorrectly flagged commercial breaks, and have playback start at the actual beginning of the recording.

<syntaxhighlight lang=xml enclose="div">
<edl>

<mergeshortcommbreaks>false</mergeshortcommbreaks>

<maxcommbreaklength>250</maxcommbreaklength>

<mincommbreaklength>90</mincommbreaklength>

<maxcommbreakgap>120</maxcommbreakgap>

<commbreakautowait>0</commbreakautowait>

<commbreakautowind>0</commbreakautowind>

<displaycommbreaknotifications>false</displaycommbreaknotifications>
</edl>
</syntaxhighlight>
'''Notes:'''
* displaycommbreaknotifications<ref>https://github.com/xbmc/xbmc/pull/20711</ref>

== PVR & Live TV ==
{{anchor|.3Cpvr.3E}}
Settings available for PVR, EPG and Live TV. Edit Decision List settings are located in the previous section.

=== pvr ===
<syntaxhighlight lang="xml" line='line'>
<pvr>
<timecorrection>0</timecorrection> 
<infotoggleinterval>3000</infotoggleinterval> 
<channeliconsautoscan>true</channeliconsautoscan> 
<autoscaniconsuserset>false</autoscaniconsuserset> 
<numericchannelswitchtimeout>1000</numericchannelswitchtimeout> 
</pvr>
</syntaxhighlight>

==== pvrrecordings ====
In v19 and later, allows users to modify sort type and order of pvr recordings. <ref>https://github.com/xbmc/xbmc/pull/18605</ref>

;Note- These settings are child tags to the ''<pvr>'' tag in the previous section.

<syntaxhighlight lang="xml" line='line'>
<pvr>
<pvrrecordings>
<sortmethod>2</sortmethod> 
<sortorder>2</sortorder> 
</pvrrecordings>
</pvr>
</syntaxhighlight>

=== epg ===
{{anchor|.3Cpvr.3E}}
<syntaxhighlight lang="xml" line='line'>
<epg>
<updatecheckinterval>300</updatecheckinterval> 
<updateemptytagsinterval>60</updateemptytagsinterval> 
<cleanupinterval>900</cleanupinterval> 
<activetagcheckinterval>60</activetagcheckinterval> 
<retryinterruptedupdateinterval>60</retryinterruptedupdateinterval> 
<displayupdatepopup>true</displayupdatepopup> 
<displayincrementalupdatepopup>false</displayincrementalupdatepopup> 
</epg>
</syntaxhighlight>

== Video library settings ==

=== videoextensions ===
{{anchor|.3Cvideoextensions.3E}}<section begin="videoextensions" />
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Video windows.

Default extensions for VIDEOS:
<pre>
.m4v .3g2 .3gp .nsv .tp .ts .ty .strm .pls .rm .rmvb .mpd .m3u .m3u8 .ifo .mov .qt .divx .xvid
.bivx .vob .nrg .img .iso .udf .pva .wmv .asf .asx .ogm .m2v .avi .bin .dat .mpg .mpeg .mp4
.mkv .mk3d .avc .vp3 .svq3 .nuv .viv .dv .fli .flv .001 .wpl .xspf .zip .vdr .dvr-ms .xsp .mts
.m2t .m2ts .evo .ogv .sdp .avs .rec .url .pxml .vc1 .h264 .rcv .rss .mpls .mpl .webm .bdmv
.bdm .wtv .trp .f4v
</pre>
Examples:
<pre>
<videoextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</videoextensions>
</pre>
<section end="videoextensions" />

=== discstubextensions ===
{{main|Media stubs}}

<section begin="discstubextensions" />
The default filename extension for Disc Stubs is:
<syntaxhighlight lang=xml enclose="div">
.disc
</syntaxhighlight>
Using the following tags, it is possible to <tt><add></tt> additional or <tt><remove></tt> existing disc stub extensions to better suit your requirements.
<syntaxhighlight lang=xml enclose="div">
<discstubextensions>
<add>.disk|.stub</add>
<remove>.disc</remove>
</discstubextensions>
</syntaxhighlight>
<section end="discstubextensions" />

=== languagecodes ===
{{anchor|.3Clanguagecodes.3E}}
User-defined translation table for language codes used in subtitles and audio.
It can be used to add, extend or override Kodi's language codes.

'''How to add a new language code:'''

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>alt</short>
<long>Alternate</long>
</code>
</languagecodes>
</syntaxhighlight>

'''How to add a new language code with subtag (e.g. pt-BR):'''
{{note|This support is available from Kodi v20}}

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>pt-BR</short>
<long>Portuguese - Brazil</long>
</code>
</languagecodes>
</syntaxhighlight>

''NOTE FOR MKV FILES:''<br/>
MKV files that contain audio/subtitle tracks with language codes with subtags are not yet supported, but from <code>Kodi v21</code> a workaround was introduced that allows Kodi to recognize language codes with subtags.
To use the workaround, you must open the MKV file with an editor and in the metadata of the desired audio/subtitle track, edit the track Name (or Title field) by adding the language code wrapped in curly brackets, as in following example:
<br/><code>Original track name: Audio portuguese/brazil</code>
<br/><code>Modified track name: Audio portuguese/brazil {pt-BR}</code>

'''How to extend an existing language code:'''

Set the same "long" description of the existing language, for example we reuse the Portughese language for another language code:

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>pt-BR</short>
<long>Portuguese</long>
</code>
</languagecodes>
</syntaxhighlight>

In this case when in Kodi settings you set the "Portuguese" language, when in playing according to availability the track "pt" or "pt-BR" will be chosen.

'''How to override an existing language code:'''

This allow you to rename an existing language. Set to an existing language code your preferred "long" name description.

''WARNING: This can cause problems with add-ons, so do not override languages if you are not aware of the side effects.''

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>en</short>
<long>English example</long>
</code>
<code>
<short>en-GB</short>
<long>English example</long>
</code>
</languagecodes>
</syntaxhighlight>

=== moviestacking ===
{{anchor|.3Cmoviestacking.3E}}<section begin="moviestacking" />
{{main|Naming_video_files/Movies}}
This is used by the [[Naming_video_files/Movies#Split_Video_Files|file stacking]] algorithm to combine multi-part files and contains a list of regular expressions. For stacking videos that are contained in folders, such as VIDEO_TS folders, see '''[[advancedsettings.xml#folderstacking|<folderstacking>]]'''

As of v9.11, video stacking regular expressions '''must''' contain exactly four (4) capture expressions.

Default:
<syntaxhighlight lang=xml enclose="div">
<moviestacking>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[0-9]+)(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[a-d])(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ ._-]*[a-d])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="append"</tt> or <tt>append="yes"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the end.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="append">

<regexp>(.*?)([ ._-]*[0-9])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="prepend"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the beginning.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="prepend">
<regexp>(Title)(Volume)(Ignore)(Extension)</regexp>
</moviestacking>
</syntaxhighlight>

If no argument is supplied, or the argument <tt>append="no"</tt> is supplied, the default moviestacking regular expressions are overwritten by the user specified ones.
<section end="moviestacking" />

=== folderstacking ===
{{main|Naming_video_files/Movies}}
This is similar to '''[[advancedsettings.xml#moviestacking|<moviestacking>]]''', but is used for videos that are contained in folders that use the folder names to stack, such as VIDEO_TS folders (DVD rips that are not in ISO format).

Default:
<syntaxhighlight lang=xml enclose="div">
<folderstacking>

<regexp>((cd|dvd|dis[ck])[0-9]+)$</regexp>
</folderstacking>
</syntaxhighlight>

=== cleandatetime ===
{{anchor|.3Ccleandatetime.3E}}
Matches a year number in a string using a Regular Expression

Default expression:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleandatetime>(.*[^ _\,\.\[\]\-])[ _\.\[\]\-]+(19[0-9][0-9]|20[0-9][0-9])([ _\,\.\[\]\-]|[^0-9]$)?</cleandatetime>
</video>
</syntaxhighlight>
:* The string found before will be used as basis string getting cleaned by the cleanstrings expressions.
:* By default date formats like MM:YY are ignored.

=== cleanstrings ===
{{anchor|.3Ccleanstrings.3E}}
Clean unwanted characters from filenames or folders by using a list of Regular Expressions. Please note that everything right of the match (at the end of the file name) is removed, so if you would have a file named ''Super movie.mp4'' and would add <tt><regexp> </regexp></tt> (only a space), the only thing that would be left is ''Super'', which is probably not what you want.

{{Github_link|[https://github.com/xbmc/xbmc/blob/Nexus/xbmc/settings/AdvancedSettings.cpp#L201-L211 Code in Github]}}

Default expressions:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleanstrings>
<regexp>([ _\\,\\.\$\$\\[\\]\\-](10bit|480p|480i|576p|576i|720p|720i|1080p|1080i|2160p|3d|aac|ac3|aka|atmos|avi|bd5|bdrip|bluray|brrip|cam|cd[1-9]|custom|dc|ddp|divx|divx5|dolbydigital|dolbyvision|dsr|dsrip|dts|dts-hdma|dts-hra|dts-x|dv|dvd|dvd5|dvd9|dvdivx|dvdrip|dvdscr|dvdscreener|extended|fragment|fs|h264|h265|hdr|hdr10|hevc|hddvd|hdrip|hdtv|hdtvrip|hrhd|hrhdtv|internal|limited|multisubs|nfofix|ntsc|ogg|ogm|pal|pdtv|proper|r3|r5|read.nfo|remastered|remux|repack|rerip|retail|screener|se|svcd|tc|telecine|telesync|truehd|ts|uhd|unrated|ws|x264|x265|xvid|xvidvd|xxx|web-dl|webrip|www.www|\\[.*\\])([ _\\,\\.\$\$\\[\\]\\-]|$)");</regexp>
<regexp>(\[.*\])</regexp>
</cleanstrings>
</video>
</syntaxhighlight>
Updated in v20<ref>https://github.com/xbmc/xbmc/pull/20549</ref>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== tvshowmatching ===
{{anchor|.3Ctvshowmatching.3E}}
Matches the season and episode numbers in file paths by using a list of Regular Expressions

{{Github_link|[https://github.com/xbmc/xbmc/blob/Matrix/xbmc/settings/AdvancedSettings.cpp#L232 Code in Github]}}

Defaults:
<syntaxhighlight lang=xml enclose="div">
<tvshowmatching>
<regexp>s([0-9]+)[ ._x-]*e([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)([^\\\\/]*)$</regexp> 
<regexp>[\._ -]()[Ee][Pp]_?([0-9]+)([^\\/]*)$</regexp> 
<regexp>([0-9]{4})[\.-]([0-9]{2})[\.-]([0-9]{2})</regexp> 
<regexp>([0-9]{2})[\.-]([0-9]{2})[\.-]([0-9]{4})</regexp> 
<regexp>[\\/\._ \[\(-]([0-9]+)x([0-9]+)([^\\/]*)$</regexp> 
<regexp>[\\/\._ -]([0-9]+)([0-9][0-9])([\._ -][^\\/]*)$</regexp> 
<regexp>[\/._ -]p(?:ar)?t[_. -]()([ivx]+)([._ -][^\/]*)$</regexp> 
</tvshowmatching>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)
:* Paths are converted to lower case before matching.
:* For multi-episode matching to work, there needs to be a third set of parentheses '()' at the end, this part is fed back into the regexp engine.
:* A [https://forum.kodi.tv/showthread.php?tid=51614 forum thread] has a discussion of pre-made regex lists to match common names. These might improve Kodi's ability to match TV show names in some situations, at the risk of additional false positives.

==== Filenames without Season ====
There are two methods to add episodes without a season in their file path. Both ways will force the season to '1' by default, so that you can use
the 'Use Absolute Ordering (Single Season)' setting from the TheTvDb.com scraper.

; Simple Method ''(XBMC v9.11 onwards and Kodi)''
: Use only one pair of parentheses
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]([0-9]+)</regexp></syntaxhighlight>
; Advanced Method ''(XBMC v10.05 onwards and Kodi)''
: Supports multi-episode files without season
: Use an empty pair of parentheses for the season
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

; Specifying Default Season ''(XBMC v12.0 onwards and Kodi)''
It is possible to set the default season for specific regular expressions by setting the 'defaultseason' attribute.
: Works with both the simple method and advanced method
: If not used, the season will be set to '1'
: Useful for setting specials to season '0'
<syntaxhighlight lang=xml enclose="div"><regexp defaultseason="0">[/\._ \-]X()([0-9]+)(-[0-9]+)?</regexp>
<regexp defaultseason="1">[/\._ \-]E()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

=== tvmultipartmatching ===
{{anchor|.3Ctvmultipartmatching.3E}}
Matches a multipart episode number based on a previously identified episode file, using a list of Regular Expressions.

Default:
<syntaxhighlight lang=xml enclose="div">
<tvmultipartmatching>^[-_ex]+([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)</tvmultipartmatching>
</syntaxhighlight>
:* Text matching is compared case-insensitive.
:* Specifying this option '''replaces''' the default value

=== excludefromscan ===
{{anchor|.3Cexcludefromscan.3E}}
Matches filenames or folders which should be excluded from a library scan (except tvshows) using a list of Regular Expressions. This can be for both Video or Audio sections of <tt>advancedsettings.xml</tt>.

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromscan>
<regexp>-trailer</regexp>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludefromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== excludefromlisting ===
{{anchor|.3Cexcludefromlisting.3E}}
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromlisting> 
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</video>
</syntaxhighlight>

=== excludetvshowsfromscan ===
{{anchor|.3Cexcludetvshowsfromscan.3E}}
Matches filenames or folders which should be excluded from a tvshow library scan using a list of Regular Expressions

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludetvshowsfromscan>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludetvshowsfromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== trailermatching ===
{{anchor|.3Ctrailermatching.3E}}
Contains Regular Expression syntax to match the locally stored trailers to movies in the library.

<syntaxhighlight lang=xml enclose="div">
<trailermatching>

<regexp>(.*?)(_Trailer)(\.[^.]+)$</regexp>
</trailermatching>
</syntaxhighlight>

=== videolibrary ===
{{anchor|.3Cvideolibrary.3E}}
Options specific to the Video Library

{{Note|Kodi v20 users don't need set "importwatched" or "importresumepoint" to true anymore as that's the default then <ref>https://github.com/xbmc/xbmc/pull/20842</ref>}}

<syntaxhighlight lang="xml" line='line'>
<videolibrary>
<allitemsonbottom>false</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<usefasthash>true</usefasthash> 
<recentlyaddeditems>35</recentlyaddeditems> 
<itemseparator> / </itemseparator> 
<exportautothumbs>false</exportautothumbs> 
<importwatchedstate>false</importwatchedstate> 
<importresumepoint>false</importresumepoint> 
<dateadded>1</dateadded> 
</videolibrary>
</syntaxhighlight>

=== videoscanner ===
{{anchor|.3Cvideoscanner.3E}}
Options specific to the Video scanner
<syntaxhighlight lang=xml enclose="div">
<videoscanner>
<ignoreerrors>true</ignoreerrors> 
</videoscanner>
</syntaxhighlight>

== Library artwork ==

{{note|Using <imageres>9999</imageres> and <fanartres>9999</fanartres> will allow caching artwork at original size.}}

=== imageres ===
{{anchor|.3Cimageres.3E}}

<section begin="imageres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached artwork]] (other than fanart / 16:9 images) should be resized to in pixels. The width is automatically calculated as being 16/9*height. The image will be resized to fit within this size. e.g. an image that is 2000x500 will be cached at size 1280x320. An image that is 500x800 will be cached at size 450x720 using the default value of 720.<section end="imageres description" />

<syntaxhighlight lang=xml enclose="div">
<imageres>720</imageres>
</syntaxhighlight>

=== fanartres ===
{{anchor|.3Cfanartres.3E}}

<section begin="fanartres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached fanart]] should be resized to in pixels. The width is automatically calculated as being 16/9*height. Only images that are exactly 16x9 and equal to or greater than this resolution will be cached at this size - all other images will be cached using <imageres>. The default value is 1080.<section end="fanartres description" />

<syntaxhighlight lang=xml enclose="div">
<fanartres>1080</fanartres>
</syntaxhighlight>

=== imagescalingalgorithm ===
Specify the image scaling algorithm for image resizing when [[Artwork/Cache#Texture optimization| caching artwork]] to the local texture cache.
<br />
<syntaxhighlight lang=xml enclose="div">
<imagescalingalgorithm>bicubic</imagescalingalgorithm>
</syntaxhighlight>

[https://github.com/xbmc/xbmc/blob/master/xbmc/pictures/PictureScalingAlgorithm.cpp#L20-L32 Available image scaling algorithms]

<syntaxhighlight lang=text enclose="div">
fast_bilinear
bilinear
bicubic
experimental
nearest_neighbor
averaging_area
bicublin
gaussian
sinc
lanczos
bicubic_spline
</syntaxhighlight>

=== imagequalityjpeg ===
This specifies the quality of the images when stored in jpeg format. By default kodi uses a quality of 4 which is a good compromise between size and quality. If you want to reduce the thumbnail sizes (decreasing quality) choose a higher value up to 21. If high quality (large thumbnail size) is needed, chose a smaller value, e.g. 0,1,2 or 3. (Added in v20 <ref>https://github.com/xbmc/xbmc/pull/21418</ref>)
<br />
<syntaxhighlight lang=xml enclose="div">
<imagequalityjpeg>4</imagequalityjpeg>
</syntaxhighlight>

== Video and music library settings ==

=== playlistasfolders ===
{{anchor|.3Cplaylistasfolders.3E}}
In the recent releases, playlists are treated as folders. Selecting a playlist no longer plays it, but opens it, as if it were a folder.

Set to false to revert to the previous behaviour. When you select a playlist, its content is added to the list of elements to be played.

:{{note|This setting will not affect smart playlists, they will always show as folders.}}

;Example
<syntaxhighlight lang=xml enclose="div">
<playlistasfolders>true</playlistasfolders>
</syntaxhighlight>

=== playlistretries ===
{{anchor|.3Cplaylistretries.3E}}
The number of retries attempted if a source is offline. With this control you can alter the number of consecutive failed items before a playlist fails.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlistretries>100</playlistretries>
</syntaxhighlight>

=== playlisttimeout ===
{{anchor|.3Cplaylisttimeout.3E}}
The timeout, in seconds, before item failure.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlisttimeout>20</playlisttimeout>
</syntaxhighlight>

=== sorttokens ===
Allows you to specify additional tokens that will be ignored at the start of lines during sorting.
{{note|Sort tokens are case sensitive.}}
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token>the</token>
</sorttokens>
</syntaxhighlight>

In the above example "the ", "the." and "the_" will be ignored at the start of titles or names when sorting items, in both video and music libraries. A separator can also be specified, for example
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token separators="'">L</token>
</sorttokens>
</syntaxhighlight>
In that case the value L', as in French movie name ''L'argent'', will be ignored and the item listed under "A".

=== musicdatabase/videodatabase ===
{{anchor|.3Cmusicdatabase.3E/.3Cvideodatabase.3E|musicdatabase/videodatabase|database tags music/video/tv/epg/adsp}}
{{main|MySQL}}
<section begin="videodatabase" />
Allows advanced customization of the default database settings for music, video, TV, EPG, and ADSP databases.

:{{note| '''It is HIGHLY recommended that you not attempt to place an sqlite3 database outside of kodi's path. sqlite3 contains no filesystem abstraction, so this will plain break on any non-local (as far as Kodi is concerned) paths. Use this for mysql only.'''}}

'''Parent tags:'''

* '''<videodatabase>'''
* '''<musicdatabase>'''
* '''<tvdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<epgdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<adspdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
{{MySQL warning}}

'''Child tags: '''

;<type>
: ''Required'' - Can be either "sqlite3" or "mysql" (default: sqlite3)

;<host>
:''Required'' -
* sqlite3: defines the relative path to the database file (eg. /usr/local/kodi/databases).
* mysql: defines the host of the mysql socket (eg. localhost, 192.168.0.1, etc)

;<port>
: ''Optional'' -
* sqlite3: silently ignored
* mysql: defines the port of the mysql socket (default: 3306)

;<name>
: ''Optional'' -
:by default "MyVideos"+DB number will be used.
* sqlite3: defines the name of the database file to read from, excluding the ".db" extension.
* mysql: defines the name of the database to use

;<user>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the user with privileged access to the database

;<pass>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the password for the user with privileged access to the database

;<compression>
: ''Optional'' - Defaults to false. Set to "true" to enable MySQL compression protocol. Performance benefit is going to be largely dependent on the network bandwidth, latency between database and clients and on the size of the result sets. [https://github.com/xbmc/xbmc/pull/6484]
: {{Note|Slower clients (such as the RPi and others) won't benefit from it as the zlib de-compression overhead is higher than the actual compression savings}}

;<key>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<cert>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ca>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<capath>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ciphers>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

'''Examples:'''

1) Configure a database for MySQL.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<videodatabase>
<type>mysql</type>
<host>192.168.0.10</host>
<name>kodi_video</name>
<user>kodi</user>
<pass>kodi</pass>
</videodatabase>
</syntaxhighlight>

2) Configure a database for an sqlite database.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<musicdatabase>
<type>sqlite3</type>
<host>/usr/local/share/kodi/databases</host>
</musicdatabase>
</syntaxhighlight>

<section end="videodatabase" />

=== externalplayer ===
{{anchor|.3Cexternalplayer.3E}}
{{see|External players}}

== Music settings ==

=== musicextensions ===
{{anchor|.3Cmusicextensions.3E}}
<section begin="musicextensions" />
Default extensions for MUSIC:
<pre>
.nsv .m4a .flac .aac .strm .pls .rm .rma .mpa .wav .wma .ogg .mp3 .mp2 .m3u .gdm .imf .m15 .sfx
.uni .ac3 .dts .cue .aif .aiff .wpl .xspf .ape .mac .mpc .mp+ .mpp .shn .zip .wv .dsp .xsp .xwav
.waa .wvs .wam .gcm .idsp .mpdsp .mss .spt .rsd .sap .cmc .cmr .dmc .mpt .mpd .rmt .tmc .tm8
.tm2 .oga .url .pxml .tta .rss .wtv .mka .tak .opus .dff .dsf .m4b .dtshd
</pre>

It is possible to add or remove extensions for Music, using the following XML tags. Useful if you keep, say, FLAC and mp3 versions of music in the same folder. The <remove> tag can be used to remove mp3 from being listed in the library, leaving only the higher quality FLAC being displayed.

<musicextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</musicextensions>

<section end="musicextensions" />

=== cddbaddress ===
{{anchor|.3Ccddbaddress.3E}}
The address of the online CDDb database. You may set this to another freedb mirror if there is a more suitable one.

Default:
<syntaxhighlight lang=xml enclose="div>
<cddbaddress>freedb.freedb.org</cddbaddress>
</syntaxhighlight>

=== songinfoduration ===
{{anchor|.3Csonginfoduration.3E}}
This controls how long the song information will remain onscreen when the song changes during visualisations. The valid range is "1" to "Indefinite (0)", in seconds. This does not include the duration of any transition effects.

Default:
<syntaxhighlight lang=xml enclose="div">
<songinfoduration>10</songinfoduration>
</syntaxhighlight>

=== musicfilenamefilters ===
{{anchor|.3Cmusicfilenamefilters.3E}}
Contains filters to match music information (artist, title etc.) from a tag-less music filename. The first <filter> to match completely is used. Matched items include:

<pre>
%A - Artist
%T - Title
%B - Album
%N - Track number
%S - Part of set (disk number)
%D - Duration
%G - Genre
%Y - Year
%R - Rating
</pre>

Example:
<syntaxhighlight lang=xml enclose="div">
<musicfilenamefilters>
<filter>%A - %T</filter>
</musicfilenamefilters>
</syntaxhighlight>

=== musiclibrary ===
Options specific to the Music Library
<section begin="MusicLibrary" />
<syntaxhighlight lang="xml" line='line'>
<musiclibrary>
<allitemsonbottom>true</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<recentlyaddeditems>35</recentlyaddeditems> 
<albumformat>%B - %Y</albumformat> 
<prioritiseapetags>true</prioritiseapetags> 
<itemseparator> / </itemseparator> 
<artistseparators> 
<separator>;</separator>
<separator>:</separator>
<separator>|</separator>
<separator> feat. </separator>
<separator> ft. </separator>
</artistseparators>
<dateadded>1</dateadded> 


<useisodates>false</useisodates> 
</musiclibrary>
</syntaxhighlight>
{{Note|Changing the <itemseparator> or <artistseparators> will only affect newly added items. A rescan won't change the existing ones. Remove the Source(s) or delete the Music DB and rebuild. This process should be made easier from v18 and up using <promptfulltagscan>}}<section end="MusicLibrary" />

== Photos settings ==

=== pictureextensions ===
{{anchor|.3Cpictureextensions.3E}}
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Pictures window.

Default extensions for PICTURES:
<pre>
.png .jpg .jpeg .bmp .gif .ico .tif .tiff .tga .pcx .cbz .zip .rss .webp .jp2 .apng
</pre>

Examples:
<syntaxhighlight lang=xml enclose="div">
<pictureextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</pictureextensions>
</syntaxhighlight>

=== pictureexcludes ===
{{anchor|.3Cpictureexcludes.3E}}
Matches filenames or folders which should be excluded from being displayed in My Pictures using a list of Regular Expressions

<syntaxhighlight lang=xml enclose="div">
<pictureexcludes> 
<regexp>small</regexp>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</pictureexcludes>
</syntaxhighlight>

=== slideshow ===
{{anchor|.3Cslideshow.3E}}
<syntaxhighlight lang=xml enclose="div">
<slideshow>

<panamount>2.5</panamount>

<zoomamount>5.0</zoomamount>



<blackbarcompensation>20</blackbarcompensation>
</slideshow>
</syntaxhighlight>

== Network settings ==

=== ftp ===
{{anchor|.3Cftp.3DE}}
Specific settings if a ftp server is in use as a source

<syntaxhighlight lang=xml enclose="div">
<ftp>
<remotethumbs>true</remotethumbs> 
</ftp>
</syntaxhighlight>

=== samba ===
{{anchor|.3Csamba.3E}}
<syntaxhighlight lang=xml enclose="div">
<samba>
<doscodepage></doscodepage> 
<clienttimeout>10</clienttimeout> 
<statfiles>true</statfiles> 
</samba>
</syntaxhighlight>

=== hosts ===
{{anchor|.3Cfhosts.3E}}
Static dns entries which take precedence over your dns server.
<syntaxhighlight lang=xml enclose="div">
<hosts>
<entry name="HOSTNAME">IPADDRESS</entry>
</hosts>
</syntaxhighlight>

=== network ===
{{anchor|.3Cnetwork.3E}}

<syntaxhighlight lang=xml line='line'>
<network>
<curlclienttimeout>10</curlclienttimeout> 
<curllowspeedtime>20</curllowspeedtime> 
<curlretries>2</curlretries> 
<httpproxyusername></httpproxyusername> 
<httpproxypassword></httpproxypassword> 
<disableipv6>false</disableipv6> 
<disablehttp2>false</disablehttp2> 
<nfstimeout>30</nfstimeout> 
<catrustfile>filepath</catrustfile> 
<curlkeepaliveinterval>30</curlkeepaliveinterval> 
<nfsretries>0</nfsretries> 
</network>
</syntaxhighlight>

'''More information:'''<br>
* <curlkeepaliveinterval><ref>https://github.com/xbmc/xbmc/pull/19319</ref><br>
* <nfsretries><ref>https://github.com/xbmc/xbmc/pull/19513</ref>

=== cache ===
{{see also|HOW-TO:Modify_the_video_cache}}
<syntaxhighlight lang=xml enclose="div">
<cache>
<memorysize>0</memorysize> 
<buffermode>0</buffermode> 
<readfactor>4.0</readfactor> 
<chunksize>65536</chunksize> 
</cache>
</syntaxhighlight>

=== airtunesport ===
{{anchor|.3Cairtunesport.3E}}<section begin="airtunesport" />
This overwrites the defalt listening port of the AirTunes server (announced via zeroconf).
<section end="airtunesport" />

=== airplayport ===
{{anchor|.3Cairplayport.3E}}<section begin="airplayport" />
This overwrites the default listening port of the AirPlay server (announced via zeroconf).
<section end="airplayport" />

== File system settings ==

=== packagefoldersize ===
<section begin="packagefoldersize" />
{{anchor|.3Cpackagefoldersize.3E}}
{{xml setting
| tag name = packagefoldersize
| option type = numerical
| option values =
| default values = 200
| platform = all
| XBMC version = 12
| description = The amount (in megabytes) of add-on zip packages saved from previous add-on installs. These packages are mainly used for the [[Add-ons|add-on]] rollback feature. Increasing the size should increase the amount of past versions saved. Defaults to 200 MB.
| example = Example: <syntaxhighlight lang=xml enclose="div"><packagefoldersize>200</packagefoldersize> </syntaxhighlight>
}}
<section end="packagefoldersize" />

=== detectasudf ===
{{anchor|.3Cdetectasudf.3E}}
{{xml setting
| tag name = detectasudf
| option type = binary
| option values = true, false
| default values = false
| platform = all
| XBMC version =
| description = Set to true if you wish to detect joint ISO9660/UDF disks as UDF.
| example = Example: <syntaxhighlight lang=xml enclose="div"><detectasudf>false</detectasudf></syntaxhighlight>
}}

=== handlemounting ===
{{anchor|.3Chandlemounting.3E}}
{{xml setting
| tag name = handlemounting
| option type = binary
| option values = true, false
| default values = false
| platform = Linux
| XBMC version =
| description = Only used in Linux, it defines if Kodi should attempt to mount media drives (via udisks or udisks2).<br/>Default: False. If kodi is executed with the --standalone option (e.g. as done by kodi-standalone.sh) it by default will be True.
| example = Example: <syntaxhighlight lang=xml enclose="div"><handlemounting>false</handlemounting></syntaxhighlight>
}}

=== automountopticalmedia ===
{{xml setting
| tag name = automountopticalmedia
| option type = binary
| option values = true, false
| default values = false
| platform = Linux
| XBMC version =
| description = Only used in linux for the udisks and udisks2 providers<br/>defines if kodi should automount optical discs<ref>https://github.com/xbmc/xbmc/pull/20840</ref>
| example = Example: <syntaxhighlight lang=xml enclose="div"><automountopticalmedia>true</automountopticalmedia></syntaxhighlight>
}}

=== pathsubstitution ===
{{anchor|.3Cpathsubstitution.3E}}
{{main|Path substitution}}

{{divbox|red||'''Note:''' Path substition for "sources" and profiles is broken, and will '''NOT''' be fixed.}}

Path substitutions are for use for redirecting file paths. These are processed in order, and are useful for substituting an absolute path on a PC with a path suitable for Kodi to handle.

Default: No path substitutions defined.

Example:
<syntaxhighlight lang=xml enclose="div">
<pathsubstitution>
<substitute>
<from>G:\dvds\</from>
<to>smb://somecomputer/g-share/dvds/</to> 
</substitute>
</pathsubstitution>
</syntaxhighlight>

== Input control settings ==

=== remotedelay ===
{{anchor|.3Cremotedelay.3E}}
The repeat delay for a LIRC remote control. A delay value between 1 and 20 before a remote button starts repeating on a long keypress (i.e. continuously sending button pushes while it's held down).

Default: 3
<syntaxhighlight lang=xml enclose="div">
<remotedelay>10</remotedelay>
</syntaxhighlight>

=== controllerdeadzone ===
{{anchor|.3Ccontrollerdeadzone.3E}}
This advanced settings has been removed.
Since v17, the [[Advancedsettings.xml#controllerdeadzone|<controllerdeadzone>]] advanced setting has been removed. Deadzones can now be configured by plugging in the controller and selecting it in Settings -> System settings -> Input -> Peripherals.

=== enablemultimediakeys ===
{{anchor|.3Cenablemultimediakeys.3E}}
This setting only has any effect on Windows versions of Kodi, and only applies to builds from 28th May 2011 onwards.
In Windows the multimedia keys generate a WM_APPCOMMAND message in addition the keypress. Kodi processes both keypresses and the WM_APPCOMMAND messages, and the end result would be that the command is executed twice. To avoid this, by default multimedia keypresses are disabled. Although it should rarely be necessary, the enablemultimediakeys setting allows you to enable the multimedia keys.

Example:
<syntaxhighlight lang=xml enclose="div">
<enablemultimediakeys>true</enablemultimediakeys>
</syntaxhighlight>

=== seeksteps ===
{{Main|Skip steps}}

This setting changes which increments are available in the settings GUI for additive seeking. Note that <code><seeksteps></code> is not used to actually choose which seek steps are enabled.

'''Default:'''
<syntaxhighlight lang=xml enclose="div">
<seeksteps>7, 15, 30, 60, 180, 300, 600, 900, 1800</seeksteps>
</syntaxhighlight>

{{editor note|the defaults need to be updated for seeksteps.}}

=== touchscreen ===
{{anchor|.3Ctouchscreen.3E}}
This setting allows you to move/align the origin of the touch screen with the origin of the display used. If touch input does not result in a correct movement of the mouse pointer, the behaviour can be corrected with an offset and a stretch/compress factor.

Example:
<syntaxhighlight lang=xml enclose="div">
<touchscreen>
<x_offset>0</x_offset> 
<y_offset>0</y_offset> 
<x_stretch_factor>1.0</x_stretch_factor> 
<y_stretch_factor>1.0</y_stretch_factor> 
</touchscreen>
</syntaxhighlight>

=== scanirserver ===
Introduced in v18 and used in MS Windows setups only.<ref>https://github.com/xbmc/xbmc/pull/13896</ref>
Used to disable the regular connection attempts to the IR Server Suite when there is no remote to connect to.

The default setting is to allow connection attempts. To disable connection attempts change value to '''false'''.
<syntaxhighlight lang=xml enclose="div">
<scanirserver>true</scanirserver>
</syntaxhighlight>

== Other interface settings ==

=== window ===
{{anchor|.3Cwindow.3E}}
{{note|This is a "hidden" guisettings.xml setting (defined by the mouse moving the window size), but it is mentioned here because it is a particularly useful override when used in advancedsettings.xml}}
This allows you to manually set the default size of Kodi's windowed mode. If you resize the window, it will return to the set size when restarting.

WIDTH and HEIGHT are the values for each dimension, in pixels.

<syntaxhighlight lang=xml enclose="div">
<window>
<width>WIDTH</width>
<height>HEIGHT</height>
</window>
</syntaxhighlight>

=== restrictcapsmask ===
{{anchor|.3Crestrictcapsmask.3E}}
Windows only. A bitmask to prevent Kodi from using detected texture capabilities of the GPU. This helps work around buggy hardware/drivers.

1: prevent the use of compressed textures (DXT1, DXT3, DXT5)
2: prevent the use of non-power-of-two dimensions for textures
4: prevent the use of compressed textures with non-power-of-two dimensions.

<syntaxhighlight lang=xml enclose="div">
<restrictcapsmask>0</restrictcapsmask>
</syntaxhighlight>

=== algorithmdirtyregions ===
{{anchor|.3Calgorithmdirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="algorithmdirtyregions" />{{note|Some GPU/hardware configurations will have some minor issues (such as a visual "flicker"). For those situations try mode 2 or use the default (mode 3, which requires no advancedsetting). Almost all ARM-based devices (such as [[Android]]) willl likely have flickering issues.}}

Enable dirty-region processing. Dirty regions are any parts of the screen that have changed since the last frame. By not re-rendering what hasn't changed the GUI can be sped up. Because all GPUs work differently, only Mode 3 is guaranteed to work for everyone without flickering issues. This mode will reduce CPU/GPU usage, but will not increase GUI speed.

{| class="prettytable"
! value !! result !! description
|-
! 0
| Off
| The entire viewport is always rendered.
|-
! 1
|Union
|All dirty regions are grouped into the smallest possible rectangle. This is typically the fastest mode for slower GPUs due to only making one pass.
|-
! 2
| {{nowrap|Cost reduction}}
| Each dirty region is presented separately, in as many passes as there are regions.
|-
! 3
| {{nowrap|Whole Screen}}
| The entire screen is rendered if there are any dirty regions. This is a safe default for drivers that clear buffer contents (manifests as blinking or vibrating images). '''Default'''
|}<section end="algorithmdirtyregions" />

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<algorithmdirtyregions>1</algorithmdirtyregions>
</gui>
</syntaxhighlight>

=== visualizedirtyregions ===
{{anchor|.3Cvisualizedirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="visualizedirtyregions" />Enable dirty-region visualization. Paints a rectangle over marked controls.

* true: on
* false: off '''(Default)'''

{{note|This is only a development mode and isn't of use to normal users.}}
<section end="visualizedirtyregions" />
Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<visualizedirtyregions>true</visualizedirtyregions>
</gui>
</syntaxhighlight>

=== smartredraw ===

{{note|This is an experimental feature and you might face issues using it. So please be aware of that.}}

This new feature was introduced in Kodi 18 and if enabled, the GUI process call (and therefore the render call) is only done if anything has changed. The result will be a faster GUI and less load if Kodi plays a video

* true: on
* false: off '''(Default)'''

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<smartredraw>true</smartredraw>
</gui>
</syntaxhighlight>

=== showexitbutton ===
{{anchor|.3Cshowexitbutton.3E}}
Setting to hide the exit button, useful for people running appliance based setups where exit would only confuse/complicate the user. Modifiable via the advancedsettings.xml by setting showexitbutton to false, default is true (show)

Example:
<syntaxhighlight lang=xml enclose="div">
<showexitbutton>true</showexitbutton>
</syntaxhighlight>

=== fullscreen ===
{{anchor|.3Cfullscreen.3E}}
Starts Kodi in full screen (check resolutions!).

<syntaxhighlight lang=xml enclose="div">
<fullscreen>false</fullscreen>
</syntaxhighlight>

=== splash ===
{{anchor|.3Csplash.3E}}
Set to false if you wish to disable the startup splash image. Defaults to true.

<syntaxhighlight lang=xml enclose="div">
<splash>true</splash>
</syntaxhighlight>

=== cputempcommand ===
{{anchor|.3Ccputempcommand.3E}}
Provide a shell command Kodi will use to get CPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia and Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sed -e 's/$[0-9]*$[0-9]\{3\}.*/\1 C/' /sys/class/thermal/thermal_zone0/temp</cputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>echo "$(sensors -u | tail -n64 | grep temp1_input | awk '{print $2 }' |awk '{printf("%d\n",$1 + 0.5);}') C"</cputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sensors|sed -ne "s/temp1: \+[-+]$[0-9]\+$.*/\1 C/p"</cputempcommand>
</syntaxhighlight>

=== gputempcommand ===
{{anchor|.3Cgputempcommand.3E}}
Provide a shell command Kodi will use to get GPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-settings -tq gpuCoreTemp) C"</gputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-smi -q -d TEMPERATURE | grep Gpu | cut -c35-36) C"</gputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/usr/bin/aticonfig --od-gettemperature | grep Temperature | cut -f 2 -d "-" | cut -f 1 -d "." | sed -e "s, ,," | sed 's/$/ C/'</gputempcommand>
</syntaxhighlight>

;<u>For Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/opt/vc/bin/vcgencmd measure_temp | sed -e "s/temp=//" -e "s/\..*'/ /"</gputempcommand>
</syntaxhighlight>

=== glrectanglehack ===
{{anchor|.3Cglrectanglehack.3E}}
Problems with ghosting or videos which are only played back in the left upper quarter? The following ATI hack may solve it.
<syntaxhighlight lang=xml enclose="div">
<glrectanglehack>yes</glrectanglehack>
</syntaxhighlight>

=== alwaysontop ===
{{anchor|.3Calwaysontop.3E}}
Added in XBMC v9.11 (Windows OS only). Keeps Kodi always on top when windowed.
<syntaxhighlight lang=xml enclose="div">
<alwaysontop>yes</alwaysontop>
</syntaxhighlight>

There is also a fake fullscreen GUI option in Kodi's settings.

=== minimizetotray ===
{{anchor|.3Cminimizetotray.3E}}
{{note|Available in Kodi v20 and above.}}

Windows only. Minimizes Kodi to the system tray. Defaults to false.
<syntaxhighlight lang=xml enclose="div">
<minimizetotray>true</minimizetotray>
</syntaxhighlight>

= Removed tags =
{{anchor|Recently removed tags}}
* {{anchor|.3Cthumbsize.3E}}'''<thumbsize>''' - replaced by <[[#imageres|imageres]]> in v12 Frodo
* {{anchor|.3Cfanartheight.3E}}'''<fanartheight>''' - replaced by <[[#fanartres|fanartres]]> in v12 Frodo
* {{anchor|.3Cdvdthumbs.3E}}'''<dvdthumbs>''' - removed in v12 Frodo
* {{anchor|.3Cbusydialogdelayms.3E}}'''<busydialogdelayms>''' - removed in v12 Frodo
* {{anchor|.3Cbginfoloadermaxthreads.3E}}'''<bginfoloadermaxthreads>''' - removed in v13 Gotham
* '''<showepginfoonselect>''' - replaced by a GUI setting in v13 Gotham
* '''<resample>''', '''<forceDirectSound>''', '''<audiophile>''', '''<audiosinkbufferdurationmsec>''', '''<allowtranscode44100>''', and '''<streamsilence>''' - These were various sub-tags for <audio> that were removed in v13 Gotham and either replaced by GUI settings or were no longer needed.
* {{anchor|.3Cenableairtunesdebuglog.3E}}'''<enableairtunesdebuglog>''' - replaced by a GUI option in v14 Helix
* '''<videoDisableHi10pMultithreading>''' - renamed to <disableswmultithreading> in v14 Helix
* '''<hideallitems>''' - For both the <code><videolibrary></code> and <code><musiclibrary></code> sections, this is replaced by a GUI option in v15 Isengard
* '''<SmallStepBackSeconds>''' - In v15 the <code>SmallStepBack</code> [[Action_IDs]] has been replaced by <code>seek(-7)</code> in default keymaps. See '''[[skip steps]]''' for details. When the original <code>SmallStepBack</code> action ID is used it defaults to the first backwards [[skip steps|additive seeking value]].
* '''<timeseekforward>/<timeseekbackward>''' - In v15 these tags are replaced by GUI options via [[skip steps|additive seeking]], which is configured in the GUI. See '''[[skip steps]]''' for details.
* {{anchor|.3Ckaraoke.3E}}'''<karaoke>''' - In v16 all of the karaoke features in Kodi were removed.
* '''<useddsfanart>''' - removed in v17 Krypton.
* '''<cachemembuffersize>''' and '''<readbufferfactor>''' - In v17 '''<cachemembuffersize>''' is renamed to '''<memorysize>''' and <code><readbufferfactor></code> is renamed to <code><readfactor></code>. In addition, all three buffer related settings in <network> are moved out of <network> and into a new <cache> parent tag.
* '''<minvideocachelevel>''', '''<minaudiocachelevel>''', and '''<cacheindvdplayer>''' have been removed in v17.
* '''<useffmpegvda>''' - Tag was only used for development testing. Removed in v17.
* '''<nofliptimeout>''' - Removed in v17
* '''<blackbarcolour>''' - Removed in v17 (maybe?)
* '''<disableswmultithreading>''' - Removed in v17 (maybe?)
* '''<controllerdeadzone>''' - Removed in v17
* {{anchor|.3Cmeasurerefreshrate.3E}}'''<measurerefreshrate>''' - Removed in v17 or v18?
* {{anchor|.3Cmyth.3E}}'''<myth>''' - Removed sometime between v16 to v18
* {{anchor|.3Ctuxbox.3E}}'''<tuxbox>''' - Removed
* '''<backgroundupdate>''' - Removed
* '''<hideemptyseries>''' - Replaced by a GUI option.
* '''<mymovies>''' and child tag '''<categoriestogenres>''' - Removed
* '''<albumssortbyartistthenyear'''> - Removed
* '''<albumformatright>''' - Removed
* {{anchor|.3Cremoterepeat.3E}}'''<remoterepeat>''' - Removed
* {{anchor|.3Callowd3d9ex.3E}}'''<allowd3d9ex>''' and {{anchor|.3Cforced3d9ex.3E}}'''<forced3d9ex>''' - Removed sometime between v16 to v18
* '''<lingertime>''' - Replaced by a GUI setting in v18
* '''<forcevaapienabled>''' - Removed in v18
* '''<dxvaallowhqscaling>''' - Removed in v18 <ref>https://github.com/xbmc/xbmc/pull/15466</ref>
* '''<promptfulltagscan>false</promptfulltagscan>''' Removed in v18. Now automatically asked each time a scan is conducted.
* '''<omxdecodestartwithvalidframe>''' - This tag is only in some Raspberry Pi specific distributions, such as OpenELEC. As of March 2015, this tag has not been merged into "vanilla" Kodi builds
* '''<musicthumbs>''' Replaced in v19 by the GUI setting '''Thumbnail image files''' found in Media -> Music
* '''<artistextraart>''' Replaced in v19 by the GUI setting '''Artist art types whitelist''' found in Media -> Music
* '''<albumextraart>''' Replaced in v19 by the GUI setting '''Album art types whitelist''' found in Media -> Music
* '''<episodeextraart>''' Replaced in v19 by the GUI setting '''Episode art types whitelist''' found in Media -> Videos
* '''<tvshowextraart>''' Replaced in v19 by the GUI setting '''TV show art types whitelist''' found in Media -> Videos
* '''<tvseasonextraart>''' Replaced in v19 by the GUI setting '''TV show art types whitelist''' found in Media -> Videos
* '''<movieextraart>''' Replaced in v19 by the GUI setting '''Movie art types whitelist''' found in Media -> Videos
* '''<moviesetextraart>''' Replaced in v19 by the GUI setting '''Movie art types whitelist''' found in Media -> Videos
* '''<musicvideoextraart>''' Replaced in v19 by the GUI setting '''Music video art types whitelist''' found in Media -> Videos
* '''<fanart>''' Removed in v19
* '''<assfixedworks>''' Removed in v20
* '''<try10bitoutput>''' Removed in v20 and replaced with [[Settings/System/Display#Use_10_bit_for_SDR|Use 10 bit for SDR]] setting <ref>https://github.com/xbmc/xbmc/pull/20014</ref>
* '''<enablehighqualityhwscalers>''' Removed in v20 <ref>https://github.com/xbmc/xbmc/pull/21537</ref>

= guisettings.xml Setting Conversion =
It is possible to convert settings found in the '''[[Settings]]''' ''(guisettings.xml)'' pages of {{kodi}} into entries for the advancedsettings.xml file.

When a setting from the guisettings.xml is added to the advancedsettings.xml file, it will override the existing guisettings.xml values and the setting will be removed from the settings pages.

Why would I need to do this?
* You set up multiple devices and then need to individually change settings and preferences on each device. Using this conversion method, you save those settings in the advancedsettings.xml file and simply add the file to each device
* You need to hide settings to prevent those settings from being modified

To convert a guisetting to advancedsettings.xml follow these steps:
# In the {{kodi}} settings pages, adjust the setting(s) to your preference.
# Back out of the settings pages to the main menu, which forces {{kodi}} to save the adjusted settings to the guisettings.xml file
# Locate the guisettings.xml file in the [[Userdata]] folder and open it
# Locate the setting(s) to be converted. The list can be overwhelming so make use of the Search feature of whichever editor you are using
# Using the following setting as an example:
<syntaxhighlight lang="xml">
<setting id="videolibrary.showemptytvshows">true</setting>
</syntaxhighlight>
: Breaking down the string:
::'''videolibrary'''- parent tag
::'''showemptytvshows'''- child tag
::'''true'''- value
: The conversion is as follows and place this in the advancedsettings.xml file
<syntaxhighlight lang="xml">
<advancedsettings version="1.0">
<videolibrary>
<showemptytvshows>true</showemptytvshows>
</videolibrary>
</advancedsettings>
</syntaxhighlight>

'''Note:''' Some parent tags may already be in use in your advancedsettings.xml file. Do not duplicate them, but add the child tag beneath the existing parent tag.

= References =
<references />

{{Updated|18}}
{{DISPLAYTITLE:advancedsettings.xml}}

[[Category:Advanced topics]]
[[Category:Manual]]
[[Category:Settings]]

Advancedsettings.xml

2023-02-15T20:07:31Z

Fritsch: Document chunksize

{{TOC right}}{{mininav|[[Settings]]|page=advancedsettings.xml}}
{{bigger|{{note|'''The advancedsettings.xml file does not exist by default. You have to create it first!'''}} }}

<section begin="intro" />The [[advancedsettings.xml]] file, which does not exist by default, can be created by a user in their '''[[Userdata|userdata folder]]'''.

This file is used for advanced settings and options that do not have GUI controls inside of {{kodi}}. Some settings are experimental or very rarely set, so they can only be used via the advancedsettings.xml file. The file is simply a plain text file and can be edited by various text editors, so long as the name is "advancedsettings.xml". These advanced settings can be used to tweak various things such as episode naming patterns, special network ports, special behaviors, and more.<section end="intro" />

The following page will describe the structure of the advancedsettings.xml file and the various individual settings.

{{note|
# All XML tags must be lowercase. The start and end of the advancedsettings.xml file must have the <advancedsettings> and </advancedsettings> tags.
# Kodi will only read the advancedsettings.xml file when it starts up. If you make changes while it is running then you must restart Kodi.
# For some Windows versions, Kodi has two <code>\userdata\</code> folders. The correct one to put the advancedsettings.xml file in is not the one in Program Files, but in <code>%appdata%\Kodi\userdata\.</code>}}

== Layout ==

The layout of <code>advancedsettings.xml</code> is as follows:

<syntaxhighlight lang=xml enclose="div">
<advancedsettings version="1.0">
<setting>value</setting>
...
<setting>value</setting>
</advancedsettings>
</syntaxhighlight>

where "setting" gives the name of the setting, and "value" gives its value.

A list of the available "setting" strings and their values is given below.

= List of available settings =
List of available settings that are recognised in the advancedsettings.xml file <ref>https://github.com/xbmc/xbmc/blob/master/xbmc/settings/AdvancedSettings.cpp</ref>

Recommended: Use the table of contents or the search function in your browser to locate items.

== Troubleshooting settings ==

=== loglevel ===
{{Anchor|.3Cloglevel.3E}}

<section begin="loglevel" />
Sets the logging level used to log errors and information. The "hide" attribute is optional.

<syntaxhighlight lang=xml>
<loglevel hide="attribute">options</loglevel>
</syntaxhighlight>

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Attribute
! style="width:500px;" | Action
|-
! '''true'''
| Hides the "enable debugging" setting in the Settings page. (default)
|-
! '''false'''
| Allows "enable debugging" setting to switch between '''0''' and '''2'''.
|}

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Option
! style="width:500px;" | Action
|-
! '''-1'''
| No logging, suppresses all log output
|-
! '''0'''
| Normal logging, only logging errors (default)
|-
! '''1'''
| Debug logging with freemem, fps and cpu usage (no on screen)
|-
! '''2'''
| Same as 1 (with on screen display)
|-
! '''3'''
| Same as 1 + full smb logging
|}

{| class="wikitable"
|-
! style="width:100px;" | Example
! style="width:500px;" |
|-
! Example 1:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings>
<loglevel>2</loglevel>
</advancedsettings>
</syntaxhighlight>
|-
! Example 2:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings>
<loglevel hide="true">2</loglevel>
</advancedsettings>
</syntaxhighlight>
|}

'''Note:''' The setting is persistent through shutdown and restarts.<br>
'''Note:''' If debugging is enabled in the GUI, loglevel will be set to '''2'''. This will over-ride the <code>advancedsettings.xml</code> setting. You must disable the GUI Setting before adding the entry to <code>advancedsettings.xml</code>.<br />
<section end="loglevel" />
:''{{see also|Log_file|label 1=Debug Log}}''

=== jsonrpc ===
{{Anchor|.3Cjsonrpc.3E}}
To make it easier for developers using the [[JSON-RPC_API]] API in their (third party) applications to debug during development the json output of Kodi can be prettified by setting '''compactoutput''' to '''false'''. Default json output mode is a compact print which does not contain any unnecessary whitespaces and therefore is difficult to read for humans.
Furthermore using the '''tcpport''' setting it is possible to change the default TCP port used by Kodi for JSON RPC (which is 9090) to any other valid port.

Example:
<syntaxhighlight lang=xml enclose="div">
<jsonrpc>
<compactoutput>false</compactoutput>
<tcpport>9999</tcpport>
</jsonrpc>
</syntaxhighlight>

== Audio/video playback settings ==

=== skiploopfilter ===
{{anchor|.3Cskiploopfilter.3E}}
The amount of the loop filter to skip on h.264 decoding. This can help the performance of slower machines when decoding h264 content. Values, in decreasing CPU usage (and decreasing quality)
* -16 None
* 0 Skip only empty frames (default)
* 8 Skip non-reference frames
* 16 Skip bi-dir frames
* 32 Skip all non-key frames
* 48 Skip all frames
Example:
<syntaxhighlight lang=xml enclose="div">
<skiploopfilter>8</skiploopfilter>
</syntaxhighlight>

=== video ===
{{anchor|.3Cvideo.3E}}

The <video> section also includes the following child-tags, which have their own sections:
*[[#cleandatetime]]
*[[#cleanstrings]]
*[[#excludefromscan]]
*[[#excludefromlisting]]
*[[#excludetvshowsfromscan]]

{{note|Some tags that have a "third-level" and are grouped together are highlighted in color.}}

{| class="prettytable"
! Tag !! Description
|-
|
<syntaxhighlight lang=xml>
<video>
</syntaxhighlight>
| Parent tag that all other child tags need to be placed inside of. Do not use more than one '''<code><video></code>''' tag, but instead place all other child-tags within a single '''<code><video></video></code>''' set.
|-
|
<syntaxhighlight lang=xml>
<subsdelayrange>10</subsdelayrange>
</syntaxhighlight>
| Delay range for subtitles, in seconds.
|-
|
<syntaxhighlight lang=xml>
<maxtempo>2.1</maxtempo>
</syntaxhighlight>
| Allow further increase of playback speed over the default of 1.5<br>
maxtempo must be in the range of 1.5 to 2.1 <br>
Be aware of the limitations of your platform / hardware as not all are capable of the increased maxtempo <ref>https://forum.kodi.tv/showthread.php?tid=10023&pid=2795069#pid2795069</ref>
|-
|
<syntaxhighlight lang=xml>
<audiodelayrange>10</audiodelayrange>
</syntaxhighlight>
| Delay range for audio/video sync, in seconds.
|-
|
<syntaxhighlight lang=xml>
<usetimeseeking>true</usetimeseeking>
</syntaxhighlight>
| Whether to use time based or percentage based seeking. {{small see also|Skip steps}}
|-
|
<syntaxhighlight lang=xml>
<timeseekforwardbig>600</timeseekforwardbig>
<timeseekbackwardbig>-600</timeseekbackwardbig>
</syntaxhighlight>
| Time to seek forward in seconds when doing a long seek. Defaults to 600 (10 minutes) and -600 (-10 minutes) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforward>2</percentseekforward>
<percentseekbackward>-2</percentseekbackward>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a short seek. Defaults to 2 (2%) and -2 (2%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforwardbig>10</percentseekforwardbig>
<percentseekbackwardbig>-10</percentseekbackwardbig>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a long seek. Defaults to 10 (10%) and -10 (10%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<fullscreenonmoviestart>true</fullscreenonmoviestart>
</syntaxhighlight>
| Whether to go to fullscreen or not when starting a movie. Defaults to true.
|-
|
<syntaxhighlight lang=xml>
<defaultplayer>VideoPlayer</defaultplayer>
</syntaxhighlight>
| Set the default video player: VideoPlayer or an external player. See '''[[External players]]''' for more info.
|-
|
<syntaxhighlight lang=xml>
<excludefromscan>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromscan>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be added to library. It is possible to add multiple <code><regexp></code> tags to match multiple patterns
|-
|
<syntaxhighlight lang=xml>
<excludefromlisting>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be displayed in files view.
|-
|
<syntaxhighlight lang=xml>
<playcountminimumpercent>90</playcountminimumpercent>
</syntaxhighlight>
| Minimum percentage that has to be played before it is marked as watched. Set to 101 to never auto-mark items as watched. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignoresecondsatstart>180</ignoresecondsatstart>
</syntaxhighlight>
| Number of seconds to ignore at video start after which a resume point is created. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignorepercentatend>8</ignorepercentatend>
</syntaxhighlight>
| Percentage of video to ignore at the end. If you stop watching the video here no resume point is created. Set to 101 to never save a resume point. The video is already marked as watched at 90%, see above. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<vdpauscaling>true</vdpauscaling>
</syntaxhighlight>
| Scales with vdpau instead of opengl and turns on its HQ scaler when available, enabling this might slow down rendering and cause framedrops especially on ION systems, this setting requires a vdpau feature set C GPU.
|-
|
<syntaxhighlight lang=xml>
<enablehighqualityhwscalers>true</enablehighqualityhwscalers>
</syntaxhighlight>
| Allow turning on the spline36 and lanczos3 shader (for GL builds).
|-
|
<syntaxhighlight lang=xml>
<dxvaallowhqscaling>false</dxvaallowhqscaling>
</syntaxhighlight>
| Enables high quality video upscaling for Windows.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegdeinterlacing>linblenddeint</ppffmpegdeinterlacing>
</syntaxhighlight>
| Override the deinterlacing options passed to libpostproc.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegpostprocessing>ha:128:7,va,dr</ppffmpegpostprocessing>
</syntaxhighlight>
| Override the post processing options passed to libpostproc when 'Video post-processing' is activated in GUI Videos-Settings-Playback.
|-
|
<syntaxhighlight lang=xml>
<autoscalemaxfps>30</autoscalemaxfps>
</syntaxhighlight>
| When scaling method is set to auto, bilinear is chosen when the fps is higher than this limit, the default is 30.
|-
|
<syntaxhighlight lang=xml>
<adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" | Settings for when "Adjust refreshrate to match video fps" is enabled in the video playback GUI settings.
|-
|
<syntaxhighlight lang=xml>
<override>
<fps>23.976</fps>
<refresh>60.0</refresh>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' "Adjust refreshrate to match video fps" will try to select the best refreshrate for the video fps but it doesn't always get it right, for example it might switch to an unsupported refreshrate. You can add overrides here to switch to a certain refreshrate based on video fps. It's possible to add as many overrides as you need. Overrides are processed in order, if the first one doesn't match the fps or no refreshrates match that override, it will try the next one until no overrides are left.

* '''fps''' - if the fps is between 23.966 and 23.986
* '''refresh''' - switch to the first found refreshrate that is between 59.99 and 60.01
|-
|
<syntaxhighlight lang=xml>
<override>
<fpsmin>29.96</fpsmin>
<fpsmax>30.01</fpsmax>
<refreshmin>59.0</refreshmin>
<refreshmax>61.0</refreshmax>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -'''
* '''fpsmin''' / '''fpsmin''' - You can also specify the fps range yourself.
* '''refreshmin''' / '''refreshmax''' - Same for the refreshrate
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refresh>50.0</refresh>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' If none of the overrides match, or none of the refreshrates match any of the fps matching overrides, it will choose a fallback refreshrate. Fallbacks are process in order, if the first fallback doesn't match any refreshrate, it will try the next one until no fallbacks are left.

* '''refresh''' - Switch to the first found refreshrate that is between 49.99 and 50.01.
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refreshmin>49.0</refreshmin>
<refreshmax>51.0</refreshmax>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' You can also specify the range for the fallback yourself.

If none of the overrides match the video fps, or no refreshrates match any of the fps matching overrides, and no fallbacks are specified or no refreshrates match any fallbacks, it will automatically choose the best refreshrate (same as having no overrides and fallbacks).
|-
|
<syntaxhighlight lang=xml>
</adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" |
|-
|
<syntaxhighlight lang=xml>
<checkdxvacompatibility>value</checkdxvacompatibility>
</syntaxhighlight>
| Advanced setting not present: let Kodi autodetect cards that support H.264 profile > L4.1. Set value to false to enable DXVA no matter what. Set value to true if Kodi doesn't autodetect that the graphics card doesn't support > L4.1.
|-
|
<syntaxhighlight lang=xml>
<useocclusionquery>-1</useocclusionquery>
</syntaxhighlight>
| Use an occlusion query when capturing videoframes, -1 means auto detect, 0 means disabled, 1 means enabled, the default is -1.
|-
|
<syntaxhighlight lang=xml>
<fpsdetect>1</fpsdetect>
</syntaxhighlight>
| FPS detection for video playback
* 0 = trust codec fps
* 1 = recalculate from video timestamps with uniform spacing
* 2 = recalculate from video timestamps always
|-
|
<syntaxhighlight lang=xml>
<latency>
</syntaxhighlight>
| style="background:#F0E68C;"| Start of '''latency''' tags. Display latency (video lag). Latency is given in msecs.
|-
|
<syntaxhighlight lang=xml>
<delay>0</delay>
</syntaxhighlight>
| style="background:#F0E68C;" | Global default display latency.
|-
|
<syntaxhighlight lang=xml>
<refresh></refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | Override latency for given display (not video) refresh rates. When Kodi is in windowed mode, override is ignored. Multiple overrides are allowed.

Syntax of an override entry:
<syntaxhighlight lang=xml>
<refresh>
<min>, <max> refresh rate range, OR
<rate> exact refresh rate
<delay> display latency for the given refresh rate
</refresh>
</syntaxhighlight>
|-
|
<syntaxhighlight lang=xml>
<refresh>
<min>23</min>
<max>24</max>
<delay>125</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 125 msec latency at 23-24 Hz
|-
|
<syntaxhighlight lang=xml>
<refresh>
<rate>50</rate>
<delay>50</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 50 msec latency at 50 (+/-0.01) Hz
|-
|
<syntaxhighlight lang=xml>
</latency>
</syntaxhighlight>
| style="background:#F0E68C;" |
|-
|
<syntaxhighlight lang=xml>
<stereoscopicregex3d>[-. _]3d[-. _]</stereoscopicregex3d>
<stereoscopicregexsbs>[-. _]h?sbs[-. _]</stereoscopicregexsbs>
<stereoscopicregextab>[-. _]h?tab[-. _]</stereoscopicregextab>
</syntaxhighlight>
| Filename triggers for 3D (stereoscopic) mode.
|-
|
<syntaxhighlight lang=xml>
<assfixedworks>false</assfixedworks>
</syntaxhighlight>
| Position behavior of ass subtitiles when setting "subtitle position on screen" set to "fixed". True to show at the fixed position set in video calibration. False to show at the bottom of video (default). {{note|Removed in Kodi v20.}}
|-
|
<syntaxhighlight lang=xml>
<subtitleverticalmargin>120</subtitleverticalmargin>
</syntaxhighlight>
| Allows to customise the vertical margin of text based subtitles, which will be applied to each type of subtitle position in subtitle settings. {{note|Available in Kodi v20 and above.}}
|-
|
<syntaxhighlight lang=xml>
</video>
</syntaxhighlight>
|
|}

=== audio ===
{{anchor|.3Caudio.3E}}
<syntaxhighlight lang=xml enclose="div">
<audio>

<headroom>0</headroom>

<defaultplayer>paplayer</defaultplayer>

<excludefromscan>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromscan>

<excludefromlisting>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromlisting>

<ac3downmixgain>12.0</ac3downmixgain>

<usetimeseeking>true</usetimeseeking>

<timeseekforwardbig>600</timeseekfowardbig>

<timeseekbackwardbig>-600</timeseekbackward>

<playcountminimumpercent>99</playcountminimumpercent>

<applydrc>-1.0</applydrc>

<limiterhold>0.025</limiterhold>

<limiterrelease>0.1</limiterrelease>

<maxpassthroughoffsyncduration>10</maxpassthroughoffsyncduration>
</audio>
</syntaxhighlight>

=== forcedswaptime ===
{{anchor|.3Cforcedswaptime.3E}}
Use to force a backbuffer->frontbuffer swap while vsync is enabled. Set to the time (in ms) to allow for the swap (e.g. <forcedswaptime>1</forcedswaptime> is typical).

Default: Off

=== edl ===
{{anchor|.3Cedl.3E}}
{{main|Edit_decision_list}}
Commercial break detection not as good you think it could be? Are some commercial breaks in a series of adverts not being skipped? Are some parts being skipped that are clearly not commercials? Does the end of the previous recording still show? The following advanced settings can be used to better identify full commercial break sequences, remove incorrectly flagged commercial breaks, and have playback start at the actual beginning of the recording.

<syntaxhighlight lang=xml enclose="div">
<edl>

<mergeshortcommbreaks>false</mergeshortcommbreaks>

<maxcommbreaklength>250</maxcommbreaklength>

<mincommbreaklength>90</mincommbreaklength>

<maxcommbreakgap>120</maxcommbreakgap>

<commbreakautowait>0</commbreakautowait>

<commbreakautowind>0</commbreakautowind>
</edl>
</syntaxhighlight>

== PVR & Live TV ==
{{anchor|.3Cpvr.3E}}
Settings available for PVR, EPG and Live TV. Edit Decision List settings are located in the previous section.

=== pvr ===
<syntaxhighlight lang="xml" line='line'>
<pvr>
<timecorrection>0</timecorrection> 
<infotoggleinterval>3000</infotoggleinterval> 
<channeliconsautoscan>true</channeliconsautoscan> 
<autoscaniconsuserset>false</autoscaniconsuserset> 
<numericchannelswitchtimeout>1000</numericchannelswitchtimeout> 
</pvr>
</syntaxhighlight>

==== pvrrecordings ====
In v19 and later, allows users to modify sort type and order of pvr recordings. <ref>https://github.com/xbmc/xbmc/pull/18605</ref>

;Note- These settings are child tags to the ''<pvr>'' tag in the previous section.

<syntaxhighlight lang="xml" line='line'>
<pvr>
<pvrrecordings>
<sortmethod>2</sortmethod> 
<sortorder>2</sortorder> 
</pvrrecordings>
</pvr>
</syntaxhighlight>

=== epg ===
{{anchor|.3Cpvr.3E}}
<syntaxhighlight lang="xml" line='line'>
<epg>
<updatecheckinterval>300</updatecheckinterval> 
<updateemptytagsinterval>60</updateemptytagsinterval> 
<cleanupinterval>900</cleanupinterval> 
<activetagcheckinterval>60</activetagcheckinterval> 
<retryinterruptedupdateinterval>60</retryinterruptedupdateinterval> 
<displayupdatepopup>true</displayupdatepopup> 
<displayincrementalupdatepopup>false</displayincrementalupdatepopup> 
</epg>
</syntaxhighlight>

== Video library settings ==

=== videoextensions ===
{{anchor|.3Cvideoextensions.3E}}<section begin="videoextensions" />
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Video windows.

Default extensions for VIDEOS:
<pre>
.m4v .3g2 .3gp .nsv .tp .ts .ty .strm .pls .rm .rmvb .mpd .m3u .m3u8 .ifo .mov .qt .divx .xvid
.bivx .vob .nrg .img .iso .udf .pva .wmv .asf .asx .ogm .m2v .avi .bin .dat .mpg .mpeg .mp4
.mkv .mk3d .avc .vp3 .svq3 .nuv .viv .dv .fli .flv .001 .wpl .xspf .zip .vdr .dvr-ms .xsp .mts
.m2t .m2ts .evo .ogv .sdp .avs .rec .url .pxml .vc1 .h264 .rcv .rss .mpls .mpl .webm .bdmv
.bdm .wtv .trp .f4v
</pre>
Examples:
<pre>
<videoextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</videoextensions>
</pre>
<section end="videoextensions" />

=== discstubextensions ===
{{main|Media stubs}}

<section begin="discstubextensions" />
The default filename extension for Disc Stubs is:
<syntaxhighlight lang=xml enclose="div">
.disc
</syntaxhighlight>
Using the following tags, it is possible to <tt><add></tt> additional or <tt><remove></tt> existing disc stub extensions to better suit your requirements.
<syntaxhighlight lang=xml enclose="div">
<discstubextensions>
<add>.disk|.stub</add>
<remove>.disc</remove>
</discstubextensions>
</syntaxhighlight>
<section end="discstubextensions" />

=== languagecodes ===
{{anchor|.3Clanguagecodes.3E}}
User-defined translation table for language codes used in subtitles and audio.
It can be used to add, extend or override Kodi's language codes.

'''How to add a new language code:'''

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>alt</short>
<long>Alternate</long>
</code>
</languagecodes>
</syntaxhighlight>

'''How to add a new language code with subtag (e.g. pt-BR):'''
{{note|This support is available from Kodi v20}}

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>pt-BR</short>
<long>Portuguese - Brazil</long>
</code>
</languagecodes>
</syntaxhighlight>

'''How to extend an existing language code:'''

Set the same "long" description of the existing language, for example we reuse the Portughese language for another language code:

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>pt-BR</short>
<long>Portuguese</long>
</code>
</languagecodes>
</syntaxhighlight>

In this case when in Kodi settings you set the "Portuguese" language, when in playing according to availability the track "pt" or "pt-BR" will be chosen.

'''How to override an existing language code:'''

This allow you to rename an existing language. Set to an existing language code your preferred "long" name description.

''WARNING: This can cause problems with add-ons, so do not override languages if you are not aware of the side effects.''

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>en</short>
<long>English example</long>
</code>
<code>
<short>en-GB</short>
<long>English example</long>
</code>
</languagecodes>
</syntaxhighlight>

=== moviestacking ===
{{anchor|.3Cmoviestacking.3E}}<section begin="moviestacking" />
{{main|Naming_video_files/Movies}}
This is used by the [[Naming_video_files/Movies#Split_Video_Files|file stacking]] algorithm to combine multi-part files and contains a list of regular expressions. For stacking videos that are contained in folders, such as VIDEO_TS folders, see '''[[advancedsettings.xml#folderstacking|<folderstacking>]]'''

As of v9.11, video stacking regular expressions '''must''' contain exactly four (4) capture expressions.

Default:
<syntaxhighlight lang=xml enclose="div">
<moviestacking>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[0-9]+)(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[a-d])(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ ._-]*[a-d])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="append"</tt> or <tt>append="yes"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the end.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="append">

<regexp>(.*?)([ ._-]*[0-9])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="prepend"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the beginning.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="prepend">
<regexp>(Title)(Volume)(Ignore)(Extension)</regexp>
</moviestacking>
</syntaxhighlight>

If no argument is supplied, or the argument <tt>append="no"</tt> is supplied, the default moviestacking regular expressions are overwritten by the user specified ones.
<section end="moviestacking" />

=== folderstacking ===
{{main|Naming_video_files/Movies}}
This is similar to '''[[advancedsettings.xml#moviestacking|<moviestacking>]]''', but is used for videos that are contained in folders that use the folder names to stack, such as VIDEO_TS folders (DVD rips that are not in ISO format).

Default:
<syntaxhighlight lang=xml enclose="div">
<folderstacking>

<regexp>((cd|dvd|dis[ck])[0-9]+)$</regexp>
</folderstacking>
</syntaxhighlight>

=== cleandatetime ===
{{anchor|.3Ccleandatetime.3E}}
Matches a year number in a string using a Regular Expression

Default expression:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleandatetime>(.*[^ _\,\.\[\]\-])[ _\.\[\]\-]+(19[0-9][0-9]|20[0-9][0-9])([ _\,\.\[\]\-]|[^0-9]$)?</cleandatetime>
</video>
</syntaxhighlight>
:* The string found before will be used as basis string getting cleaned by the cleanstrings expressions.
:* By default date formats like MM:YY are ignored.

=== cleanstrings ===
{{anchor|.3Ccleanstrings.3E}}
Clean unwanted characters from filenames or folders by using a list of Regular Expressions. Please note that everything right of the match (at the end of the file name) is removed, so if you would have a file named ''Super movie.mp4'' and would add <tt><regexp> </regexp></tt> (only a space), the only thing that would be left is ''Super'', which is probably not what you want.

{{Github_link|[https://github.com/xbmc/xbmc/blob/Matrix/xbmc/settings/AdvancedSettings.cpp#L188 Code in Github]}}

Default expressions:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleanstrings>
<regexp>[ _\,\.\[\]\-](aka|ac3|dts|custom|dc|remastered|divx|divx5|dsr|dsrip|dutch|dvd|dvd5|dvd9|dvdrip|dvdscr|dvdscreener|screener|dvdivx|cam|fragment|fs|hdtv|hdrip|hdtvrip|internal|limited|multisubs|ntsc|ogg|ogm|pal|pdtv|proper|repack|rerip|retail|r3|r5|bd5|se|svcd|swedish|german|read.nfo|nfofix|unrated|extended|ws|telesync|ts|telecine|tc|brrip|bdrip|480p|480i|576p|576i|720p|720i|1080p|1080i|3d|hrhd|hrhdtv|hddvd|bluray|x264|h264|xvid|xvidvd|xxx|www.www|cd[1-9]|\[.*\])([ _\,\.\[\]\-]|$)</regexp>
<regexp>(\[.*\])</regexp>
</cleanstrings>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== tvshowmatching ===
{{anchor|.3Ctvshowmatching.3E}}
Matches the season and episode numbers in file paths by using a list of Regular Expressions

{{Github_link|[https://github.com/xbmc/xbmc/blob/Matrix/xbmc/settings/AdvancedSettings.cpp#L232 Code in Github]}}

Defaults:
<syntaxhighlight lang=xml enclose="div">
<tvshowmatching>
<regexp>s([0-9]+)[ ._x-]*e([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)([^\\\\/]*)$</regexp> 
<regexp>[\._ -]()[Ee][Pp]_?([0-9]+)([^\\/]*)$</regexp> 
<regexp>([0-9]{4})[\.-]([0-9]{2})[\.-]([0-9]{2})</regexp> 
<regexp>([0-9]{2})[\.-]([0-9]{2})[\.-]([0-9]{4})</regexp> 
<regexp>[\\/\._ \[\(-]([0-9]+)x([0-9]+)([^\\/]*)$</regexp> 
<regexp>[\\/\._ -]([0-9]+)([0-9][0-9])([\._ -][^\\/]*)$</regexp> 
<regexp>[\/._ -]p(?:ar)?t[_. -]()([ivx]+)([._ -][^\/]*)$</regexp> 
</tvshowmatching>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)
:* Paths are converted to lower case before matching.
:* For multi-episode matching to work, there needs to be a third set of parentheses '()' at the end, this part is fed back into the regexp engine.
:* A [https://forum.kodi.tv/showthread.php?tid=51614 forum thread] has a discussion of pre-made regex lists to match common names. These might improve Kodi's ability to match TV show names in some situations, at the risk of additional false positives.

==== Filenames without Season ====
There are two methods to add episodes without a season in their file path. Both ways will force the season to '1' by default, so that you can use
the 'Use Absolute Ordering (Single Season)' setting from the TheTvDb.com scraper.

; Simple Method ''(XBMC v9.11 onwards and Kodi)''
: Use only one pair of parentheses
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]([0-9]+)</regexp></syntaxhighlight>
; Advanced Method ''(XBMC v10.05 onwards and Kodi)''
: Supports multi-episode files without season
: Use an empty pair of parentheses for the season
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

; Specifying Default Season ''(XBMC v12.0 onwards and Kodi)''
It is possible to set the default season for specific regular expressions by setting the 'defaultseason' attribute.
: Works with both the simple method and advanced method
: If not used, the season will be set to '1'
: Useful for setting specials to season '0'
<syntaxhighlight lang=xml enclose="div"><regexp defaultseason="0">[/\._ \-]X()([0-9]+)(-[0-9]+)?</regexp>
<regexp defaultseason="1">[/\._ \-]E()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

=== tvmultipartmatching ===
{{anchor|.3Ctvmultipartmatching.3E}}
Matches a multipart episode number based on a previously identified episode file, using a list of Regular Expressions.

Default:
<syntaxhighlight lang=xml enclose="div">
<tvmultipartmatching>^[-_ex]+([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)</tvmultipartmatching>
</syntaxhighlight>
:* Text matching is compared case-insensitive.
:* Specifying this option '''replaces''' the default value

=== excludefromscan ===
{{anchor|.3Cexcludefromscan.3E}}
Matches filenames or folders which should be excluded from a library scan (except tvshows) using a list of Regular Expressions. This can be for both Video or Audio sections of <tt>advancedsettings.xml</tt>.

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromscan>
<regexp>-trailer</regexp>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludefromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== excludefromlisting ===
{{anchor|.3Cexcludefromlisting.3E}}
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromlisting> 
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</video>
</syntaxhighlight>

=== excludetvshowsfromscan ===
{{anchor|.3Cexcludetvshowsfromscan.3E}}
Matches filenames or folders which should be excluded from a tvshow library scan using a list of Regular Expressions

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludetvshowsfromscan>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludetvshowsfromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== trailermatching ===
{{anchor|.3Ctrailermatching.3E}}
Contains Regular Expression syntax to match the locally stored trailers to movies in the library.

<syntaxhighlight lang=xml enclose="div">
<trailermatching>

<regexp>(.*?)(_Trailer)(\.[^.]+)$</regexp>
</trailermatching>
</syntaxhighlight>

=== videolibrary ===
{{anchor|.3Cvideolibrary.3E}}
Options specific to the Video Library

{{Note|Kodi v20 users don't need set "importwatched" or "importresumepoint" to true anymore as that's the default then <ref>https://github.com/xbmc/xbmc/pull/20842</ref>}}

<syntaxhighlight lang="xml" line='line'>
<videolibrary>
<allitemsonbottom>false</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<usefasthash>true</usefasthash> 
<recentlyaddeditems>35</recentlyaddeditems> 
<itemseparator> / </itemseparator> 
<exportautothumbs>false</exportautothumbs> 
<importwatchedstate>false</importwatchedstate> 
<importresumepoint>false</importresumepoint> 
<dateadded>1</dateadded> 
</videolibrary>
</syntaxhighlight>

=== videoscanner ===
{{anchor|.3Cvideoscanner.3E}}
Options specific to the Video scanner
<syntaxhighlight lang=xml enclose="div">
<videoscanner>
<ignoreerrors>true</ignoreerrors> 
</videoscanner>
</syntaxhighlight>

== Library artwork ==

{{note|Using <imageres>9999</imageres> and <fanartres>9999</fanartres> will allow caching artwork at original size.}}

=== imageres ===
{{anchor|.3Cimageres.3E}}

<section begin="imageres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached artwork]] (other than fanart / 16:9 images) should be resized to in pixels. The width is automatically calculated as being 16/9*height. The image will be resized to fit within this size. e.g. an image that is 2000x500 will be cached at size 1280x320. An image that is 500x800 will be cached at size 450x720 using the default value of 720.<section end="imageres description" />

<syntaxhighlight lang=xml enclose="div">
<imageres>720</imageres>
</syntaxhighlight>

=== fanartres ===
{{anchor|.3Cfanartres.3E}}

<section begin="fanartres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached fanart]] should be resized to in pixels. The width is automatically calculated as being 16/9*height. Only images that are exactly 16x9 and equal to or greater than this resolution will be cached at this size - all other images will be cached using <imageres>. The default value is 1080.<section end="fanartres description" />

<syntaxhighlight lang=xml enclose="div">
<fanartres>1080</fanartres>
</syntaxhighlight>

=== imagescalingalgorithm ===
Specify the image scaling algorithm for image resizing when [[Artwork/Cache#Texture optimization| caching artwork]] to the local texture cache.
<br />
<syntaxhighlight lang=xml enclose="div">
<imagescalingalgorithm>bicubic</imagescalingalgorithm>
</syntaxhighlight>

[https://github.com/xbmc/xbmc/blob/1a8753d5cd93890dc6a9f9d4b2ce8848066ea5d0/xbmc/pictures/PictureScalingAlgorithm.cpp#L32-L43 Available image scaling algorithms]

<syntaxhighlight lang=text enclose="div">
fast_bilinear
bilinear
bicubic
experimental
nearest_neighbor
averaging_area
bicublin
gaussian
sinc
lanczos
bicubic_spline
</syntaxhighlight>

=== imagequalityjpeg ===
This specifies the quality of the images when stored in jpeg format. By default kodi uses a quality of 4 which is a good compromise between size and quality. If you want to reduce the thumbnail sizes (decreasing quality) choose a higher value up to 21. If high quality (large thumbnail size) is needed, chose a smaller value, e.g. 0,1,2 or 3. (Added in v20 <ref>https://github.com/xbmc/xbmc/pull/21418</ref>)
<br />
<syntaxhighlight lang=xml enclose="div">
<imagequalityjpeg>4</imagequalityjpeg>
</syntaxhighlight>

== Video and music library settings ==

=== playlistasfolders ===
{{anchor|.3Cplaylistasfolders.3E}}
In the recent releases, playlists are treated as folders. Selecting a playlist no longer plays it, but opens it, as if it were a folder.

Set to false to revert to the previous behaviour. When you select a playlist, its content is added to the list of elements to be played.

:{{note|This setting will not affect smart playlists, they will always show as folders.}}

;Example
<syntaxhighlight lang=xml enclose="div">
<playlistasfolders>true</playlistasfolders>
</syntaxhighlight>

=== playlistretries ===
{{anchor|.3Cplaylistretries.3E}}
The number of retries attempted if a source is offline. With this control you can alter the number of consecutive failed items before a playlist fails.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlistretries>100</playlistretries>
</syntaxhighlight>

=== playlisttimeout ===
{{anchor|.3Cplaylisttimeout.3E}}
The timeout, in seconds, before item failure.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlisttimeout>20</playlisttimeout>
</syntaxhighlight>

=== sorttokens ===
Allows you to specify additional tokens that will be ignored at the start of lines during sorting.
{{note|Sort tokens are case sensitive.}}
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token>the</token>
</sorttokens>
</syntaxhighlight>

In the above example "the ", "the." and "the_" will be ignored at the start of titles or names when sorting items, in both video and music libraries. A separator can also be specified, for example
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token separators="'">L</token>
</sorttokens>
</syntaxhighlight>
In that case the value L', as in French movie name ''L'argent'', will be ignored and the item listed under "A".

=== musicdatabase/videodatabase ===
{{anchor|.3Cmusicdatabase.3E/.3Cvideodatabase.3E|musicdatabase/videodatabase|database tags music/video/tv/epg/adsp}}
{{main|MySQL}}
<section begin="videodatabase" />
Allows advanced customization of the default database settings for music, video, TV, EPG, and ADSP databases.

:{{note| '''It is HIGHLY recommended that you not attempt to place an sqlite3 database outside of kodi's path. sqlite3 contains no filesystem abstraction, so this will plain break on any non-local (as far as Kodi is concerned) paths. Use this for mysql only.'''}}

'''Parent tags:'''

* '''<videodatabase>'''
* '''<musicdatabase>'''
* '''<tvdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<epgdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<adspdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
{{MySQL warning}}

'''Child tags: '''

;<type>
: ''Required'' - Can be either "sqlite3" or "mysql" (default: sqlite3)

;<host>
:''Required'' -
* sqlite3: defines the relative path to the database file (eg. /usr/local/kodi/databases).
* mysql: defines the host of the mysql socket (eg. localhost, 192.168.0.1, etc)

;<port>
: ''Optional'' -
* sqlite3: silently ignored
* mysql: defines the port of the mysql socket (default: 3306)

;<name>
: ''Optional'' -
:by default "MyVideos"+DB number will be used.
* sqlite3: defines the name of the database file to read from, excluding the ".db" extension.
* mysql: defines the name of the database to use

;<user>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the user with privileged access to the database

;<pass>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the password for the user with privileged access to the database

;<compression>
: ''Optional'' - Defaults to false. Set to "true" to enable MySQL compression protocol. Performance benefit is going to be largely dependent on the network bandwidth, latency between database and clients and on the size of the result sets. [https://github.com/xbmc/xbmc/pull/6484]
: {{Note|Slower clients (such as the RPi and others) won't benefit from it as the zlib de-compression overhead is higher than the actual compression savings}}

;<key>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<cert>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ca>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<capath>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ciphers>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

'''Examples:'''

1) Configure a database for MySQL.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<videodatabase>
<type>mysql</type>
<host>192.168.0.10</host>
<name>kodi_video</name>
<user>kodi</user>
<pass>kodi</pass>
</videodatabase>
</syntaxhighlight>

2) Configure a database for an sqlite database.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<musicdatabase>
<type>sqlite3</type>
<host>/usr/local/share/kodi/databases</host>
</musicdatabase>
</syntaxhighlight>

<section end="videodatabase" />

=== externalplayer ===
{{anchor|.3Cexternalplayer.3E}}
{{see|External players}}

== Music settings ==

=== musicextensions ===
{{anchor|.3Cmusicextensions.3E}}
<section begin="musicextensions" />
Default extensions for MUSIC:
<pre>
.nsv .m4a .flac .aac .strm .pls .rm .rma .mpa .wav .wma .ogg .mp3 .mp2 .m3u .gdm .imf .m15 .sfx
.uni .ac3 .dts .cue .aif .aiff .wpl .xspf .ape .mac .mpc .mp+ .mpp .shn .zip .wv .dsp .xsp .xwav
.waa .wvs .wam .gcm .idsp .mpdsp .mss .spt .rsd .sap .cmc .cmr .dmc .mpt .mpd .rmt .tmc .tm8
.tm2 .oga .url .pxml .tta .rss .wtv .mka .tak .opus .dff .dsf .m4b .dtshd
</pre>

It is possible to add or remove extensions for Music, using the following XML tags. Useful if you keep, say, FLAC and mp3 versions of music in the same folder. The <remove> tag can be used to remove mp3 from being listed in the library, leaving only the higher quality FLAC being displayed.

<musicextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</musicextensions>

<section end="musicextensions" />

=== cddbaddress ===
{{anchor|.3Ccddbaddress.3E}}
The address of the online CDDb database. You may set this to another freedb mirror if there is a more suitable one.

Default:
<syntaxhighlight lang=xml enclose="div>
<cddbaddress>freedb.freedb.org</cddbaddress>
</syntaxhighlight>

=== songinfoduration ===
{{anchor|.3Csonginfoduration.3E}}
This controls how long the song information will remain onscreen when the song changes during visualisations. The valid range is "1" to "Indefinite (0)", in seconds. This does not include the duration of any transition effects.

Default:
<syntaxhighlight lang=xml enclose="div">
<songinfoduration>10</songinfoduration>
</syntaxhighlight>

=== musicfilenamefilters ===
{{anchor|.3Cmusicfilenamefilters.3E}}
Contains filters to match music information (artist, title etc.) from a tag-less music filename. The first <filter> to match completely is used. Matched items include:

<pre>
%A - Artist
%T - Title
%B - Album
%N - Track number
%S - Part of set (disk number)
%D - Duration
%G - Genre
%Y - Year
%R - Rating
</pre>

Example:
<syntaxhighlight lang=xml enclose="div">
<musicfilenamefilters>
<filter>%A - %T</filter>
</musicfilenamefilters>
</syntaxhighlight>

=== musiclibrary ===
Options specific to the Music Library
<section begin="MusicLibrary" />
<syntaxhighlight lang="xml" line='line'>
<musiclibrary>
<allitemsonbottom>true</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<recentlyaddeditems>35</recentlyaddeditems> 
<albumformat>%B - %Y</albumformat> 
<prioritiseapetags>true</prioritiseapetags> 
<itemseparator> / </itemseparator> 
<artistseparators> 
<separator>;</separator>
<separator>:</separator>
<separator>|</separator>
<separator> feat. </separator>
<separator> ft. </separator>
</artistseparators>
<dateadded>1</dateadded> 


<useisodates>false</useisodates> 
</musiclibrary>
</syntaxhighlight>
{{Note|Changing the <itemseparator> or <artistseparators> will only affect newly added items. A rescan won't change the existing ones. Remove the Source(s) or delete the Music DB and rebuild. This process should be made easier from v18 and up using <promptfulltagscan>}}<section end="MusicLibrary" />

== Photos settings ==

=== pictureextensions ===
{{anchor|.3Cpictureextensions.3E}}
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Pictures window.

Default extensions for PICTURES:
<pre>
.png .jpg .jpeg .bmp .gif .ico .tif .tiff .tga .pcx .cbz .zip .rss .webp .jp2 .apng
</pre>

Examples:
<syntaxhighlight lang=xml enclose="div">
<pictureextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</pictureextensions>
</syntaxhighlight>

=== pictureexcludes ===
{{anchor|.3Cpictureexcludes.3E}}
Matches filenames or folders which should be excluded from being displayed in My Pictures using a list of Regular Expressions

<syntaxhighlight lang=xml enclose="div">
<pictureexcludes> 
<regexp>small</regexp>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</pictureexcludes>
</syntaxhighlight>

=== slideshow ===
{{anchor|.3Cslideshow.3E}}
<syntaxhighlight lang=xml enclose="div">
<slideshow>

<panamount>2.5</panamount>

<zoomamount>5.0</zoomamount>



<blackbarcompensation>20</blackbarcompensation>
</slideshow>
</syntaxhighlight>

== Network settings ==

=== ftp ===
{{anchor|.3Cftp.3DE}}
Specific settings if a ftp server is in use as a source

<syntaxhighlight lang=xml enclose="div">
<ftp>
<remotethumbs>true</remotethumbs> 
</ftp>
</syntaxhighlight>

=== samba ===
{{anchor|.3Csamba.3E}}
<syntaxhighlight lang=xml enclose="div">
<samba>
<doscodepage></doscodepage> 
<clienttimeout>10</clienttimeout> 
<statfiles>true</statfiles> 
</samba>
</syntaxhighlight>

=== hosts ===
{{anchor|.3Cfhosts.3E}}
Static dns entries which take precedence over your dns server.
<syntaxhighlight lang=xml enclose="div">
<hosts>
<entry name="HOSTNAME">IPADDRESS</entry>
</hosts>
</syntaxhighlight>

=== network ===
{{anchor|.3Cnetwork.3E}}

<syntaxhighlight lang=xml line='line'>
<network>
<curlclienttimeout>10</curlclienttimeout> 
<curllowspeedtime>20</curllowspeedtime> 
<curlretries>2</curlretries> 
<httpproxyusername></httpproxyusername> 
<httpproxypassword></httpproxypassword> 
<disableipv6>false</disableipv6> 
<disablehttp2>false</disablehttp2> 
<nfstimeout>30</nfstimeout> 
<catrustfile>filepath</catrustfile> 
<curlkeepaliveinterval>30</curlkeepaliveinterval> 
</network>
</syntaxhighlight>

{{Note|In Kodi v17, the three buffer settings are removed from the <code><network></code> tag and now placed under the new <code><cache></code> tag. See '''[[#cache]]''' for full details.}}

<curlkeepaliveinterval><ref>https://github.com/xbmc/xbmc/pull/19319</ref>

=== cache ===
{{see also|HOW-TO:Modify_the_video_cache}}
<syntaxhighlight lang=xml enclose="div">
<cache>
<memorysize>0</memorysize> 
<buffermode>0</buffermode> 
<readfactor>4.0</readfactor> 
<chunksize>65536</chunksize> 
</cache>
</syntaxhighlight>

=== airtunesport ===
{{anchor|.3Cairtunesport.3E}}<section begin="airtunesport" />
This overwrites the defalt listening port of the AirTunes server (announced via zeroconf).
<section end="airtunesport" />

=== airplayport ===
{{anchor|.3Cairplayport.3E}}<section begin="airplayport" />
This overwrites the default listening port of the AirPlay server (announced via zeroconf).
<section end="airplayport" />

== File system settings ==

=== packagefoldersize ===
<section begin="packagefoldersize" />
{{anchor|.3Cpackagefoldersize.3E}}
{{xml setting
| tag name = packagefoldersize
| option type = numerical
| option values =
| default values = 200
| platform = all
| XBMC version = 12
| description = The amount (in megabytes) of add-on zip packages saved from previous add-on installs. These packages are mainly used for the [[Add-ons|add-on]] rollback feature. Increasing the size should increase the amount of past versions saved. Defaults to 200 MB.
| example = Example: <syntaxhighlight lang=xml enclose="div"><packagefoldersize>200</packagefoldersize> </syntaxhighlight>
}}
<section end="packagefoldersize" />

=== detectasudf ===
{{anchor|.3Cdetectasudf.3E}}
Set to true if you wish to detect joint ISO9660/UDF disks as UDF.

Default: False

=== handlemounting ===
{{anchor|.3Chandlemounting.3E}}
Only used in Linux, it defines if Kodi should attempt to mount media drives (via udisks or udisks2).

Default: False. If kodi is executed with the --standalone option (e.g. as done by kodi-standalone.sh) it by default will be True.

=== pathsubstitution ===
{{anchor|.3Cpathsubstitution.3E}}
{{main|Path substitution}}

{{divbox|red||'''Note:''' Path substition for "sources" and profiles is broken, and will '''NOT''' be fixed.}}

Path substitutions are for use for redirecting file paths. These are processed in order, and are useful for substituting an absolute path on a PC with a path suitable for Kodi to handle.

Default: No path substitutions defined.

Example:
<syntaxhighlight lang=xml enclose="div">
<pathsubstitution>
<substitute>
<from>G:\dvds\</from>
<to>smb://somecomputer/g-share/dvds/</to> 
</substitute>
</pathsubstitution>
</syntaxhighlight>

== Input control settings ==

=== remotedelay ===
{{anchor|.3Cremotedelay.3E}}
The repeat delay for a LIRC remote control. A delay value between 1 and 20 before a remote button starts repeating on a long keypress (i.e. continuously sending button pushes while it's held down).

Default: 3
<syntaxhighlight lang=xml enclose="div">
<remotedelay>10</remotedelay>
</syntaxhighlight>

=== controllerdeadzone ===
{{anchor|.3Ccontrollerdeadzone.3E}}
This advanced settings has been removed.
Since v17, the [[Advancedsettings.xml#controllerdeadzone|<controllerdeadzone>]] advanced setting has been removed. Deadzones can now be configured by plugging in the controller and selecting it in Settings -> System settings -> Input -> Peripherals.

=== enablemultimediakeys ===
{{anchor|.3Cenablemultimediakeys.3E}}
This setting only has any effect on Windows versions of Kodi, and only applies to builds from 28th May 2011 onwards.
In Windows the multimedia keys generate a WM_APPCOMMAND message in addition the keypress. Kodi processes both keypresses and the WM_APPCOMMAND messages, and the end result would be that the command is executed twice. To avoid this, by default multimedia keypresses are disabled. Although it should rarely be necessary, the enablemultimediakeys setting allows you to enable the multimedia keys.

Example:
<syntaxhighlight lang=xml enclose="div">
<enablemultimediakeys>true</enablemultimediakeys>
</syntaxhighlight>

=== seeksteps ===
{{Main|Skip steps}}

This setting changes which increments are available in the settings GUI for additive seeking. Note that <code><seeksteps></code> is not used to actually choose which seek steps are enabled.

'''Default:'''
<syntaxhighlight lang=xml enclose="div">
<seeksteps>7, 15, 30, 60, 180, 300, 600, 900, 1800</seeksteps>
</syntaxhighlight>

{{editor note|the defaults need to be updated for seeksteps.}}

=== touchscreen ===
{{anchor|.3Ctouchscreen.3E}}
This setting allows you to move/align the origin of the touch screen with the origin of the display used. If touch input does not result in a correct movement of the mouse pointer, the behaviour can be corrected with an offset and a stretch/compress factor.

Example:
<syntaxhighlight lang=xml enclose="div">
<touchscreen>
<x_offset>0</x_offset> 
<y_offset>0</y_offset> 
<x_stretch_factor>1.0</x_stretch_factor> 
<y_stretch_factor>1.0</y_stretch_factor> 
</touchscreen>
</syntaxhighlight>

=== scanirserver ===
Introduced in v18 and used in MS Windows setups only.<ref>https://github.com/xbmc/xbmc/pull/13896</ref>
Used to disable the regular connection attempts to the IR Server Suite when there is no remote to connect to.

The default setting is to allow connection attempts. To disable connection attempts change value to '''false'''.
<syntaxhighlight lang=xml enclose="div">
<scanirserver>true</scanirserver>
</syntaxhighlight>

== Other interface settings ==

=== window ===
{{anchor|.3Cwindow.3E}}
{{note|This is a "hidden" guisettings.xml setting (defined by the mouse moving the window size), but it is mentioned here because it is a particularly useful override when used in advancedsettings.xml}}
This allows you to manually set the default size of Kodi's windowed mode. If you resize the window, it will return to the set size when restarting.

WIDTH and HEIGHT are the values for each dimension, in pixels.

<syntaxhighlight lang=xml enclose="div">
<window>
<width>WIDTH</width>
<height>HEIGHT</height>
</window>
</syntaxhighlight>

=== restrictcapsmask ===
{{anchor|.3Crestrictcapsmask.3E}}
Windows only. A bitmask to prevent Kodi from using detected texture capabilities of the GPU. This helps work around buggy hardware/drivers.

1: prevent the use of compressed textures (DXT1, DXT3, DXT5)
2: prevent the use of non-power-of-two dimensions for textures
4: prevent the use of compressed textures with non-power-of-two dimensions.

<syntaxhighlight lang=xml enclose="div">
<restrictcapsmask>0</restrictcapsmask>
</syntaxhighlight>

=== algorithmdirtyregions ===
{{anchor|.3Calgorithmdirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="algorithmdirtyregions" />{{note|Some GPU/hardware configurations will have some minor issues (such as a visual "flicker"). For those situations try mode 2 or use the default (mode 3, which requires no advancedsetting). Almost all ARM-based devices (such as [[Android]]) willl likely have flickering issues.}}

Enable dirty-region processing. Dirty regions are any parts of the screen that have changed since the last frame. By not re-rendering what hasn't changed the GUI can be sped up. Because all GPUs work differently, only Mode 3 is guaranteed to work for everyone without flickering issues. This mode will reduce CPU/GPU usage, but will not increase GUI speed.

{| class="prettytable"
! value !! result !! description
|-
! 0
| Off
| The entire viewport is always rendered.
|-
! 1
|Union
|All dirty regions are grouped into the smallest possible rectangle. This is typically the fastest mode for slower GPUs due to only making one pass.
|-
! 2
| {{nowrap|Cost reduction}}
| Each dirty region is presented separately, in as many passes as there are regions.
|-
! 3
| {{nowrap|Whole Screen}}
| The entire screen is rendered if there are any dirty regions. This is a safe default for drivers that clear buffer contents (manifests as blinking or vibrating images). '''Default'''
|}<section end="algorithmdirtyregions" />

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<algorithmdirtyregions>1</algorithmdirtyregions>
</gui>
</syntaxhighlight>

=== visualizedirtyregions ===
{{anchor|.3Cvisualizedirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="visualizedirtyregions" />Enable dirty-region visualization. Paints a rectangle over marked controls.

* true: on
* false: off '''(Default)'''

{{note|This is only a development mode and isn't of use to normal users.}}
<section end="visualizedirtyregions" />
Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<visualizedirtyregions>true</visualizedirtyregions>
</gui>
</syntaxhighlight>

=== smartredraw ===

{{note|This is an experimental feature and you might face issues using it. So please be aware of that.}}

This new feature was introduced in Kodi 18 and if enabled, the GUI process call (and therefore the render call) is only done if anything has changed. The result will be a faster GUI and less load if Kodi plays a video

* true: on
* false: off '''(Default)'''

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<smartredraw>true</smartredraw>
</gui>
</syntaxhighlight>

=== showexitbutton ===
{{anchor|.3Cshowexitbutton.3E}}
Setting to hide the exit button, useful for people running appliance based setups where exit would only confuse/complicate the user. Modifiable via the advancedsettings.xml by setting showexitbutton to false, default is true (show)

Example:
<syntaxhighlight lang=xml enclose="div">
<showexitbutton>true</showexitbutton>
</syntaxhighlight>

=== fullscreen ===
{{anchor|.3Cfullscreen.3E}}
Starts Kodi in full screen (check resolutions!).

<syntaxhighlight lang=xml enclose="div">
<fullscreen>false</fullscreen>
</syntaxhighlight>

=== splash ===
{{anchor|.3Csplash.3E}}
Set to false if you wish to disable the startup splash image. Defaults to true.

<syntaxhighlight lang=xml enclose="div">
<splash>true</splash>
</syntaxhighlight>

=== cputempcommand ===
{{anchor|.3Ccputempcommand.3E}}
Provide a shell command Kodi will use to get CPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia and Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sed -e 's/$[0-9]*$[0-9]\{3\}.*/\1 C/' /sys/class/thermal/thermal_zone0/temp</cputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>echo "$(sensors -u | tail -n64 | grep temp1_input | awk '{print $2 }' |awk '{printf("%d\n",$1 + 0.5);}') C"</cputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sensors|sed -ne "s/temp1: \+[-+]$[0-9]\+$.*/\1 C/p"</cputempcommand>
</syntaxhighlight>

=== gputempcommand ===
{{anchor|.3Cgputempcommand.3E}}
Provide a shell command Kodi will use to get GPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-settings -tq gpuCoreTemp) C"</gputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-smi -q -d TEMPERATURE | grep Gpu | cut -c35-36) C"</gputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/usr/bin/aticonfig --od-gettemperature | grep Temperature | cut -f 2 -d "-" | cut -f 1 -d "." | sed -e "s, ,," | sed 's/$/ C/'</gputempcommand>
</syntaxhighlight>

;<u>For Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/opt/vc/bin/vcgencmd measure_temp | sed -e "s/temp=//" -e "s/\..*'/ /"</gputempcommand>
</syntaxhighlight>

=== glrectanglehack ===
{{anchor|.3Cglrectanglehack.3E}}
Problems with ghosting or videos which are only played back in the left upper quarter? The following ATI hack may solve it.
<syntaxhighlight lang=xml enclose="div">
<glrectanglehack>yes</glrectanglehack>
</syntaxhighlight>

=== alwaysontop ===
{{anchor|.3Calwaysontop.3E}}
Added in XBMC v9.11 (Windows OS only). Keeps Kodi always on top when windowed.
<syntaxhighlight lang=xml enclose="div">
<alwaysontop>yes</alwaysontop>
</syntaxhighlight>

There is also a fake fullscreen GUI option in Kodi's settings.

=== minimizetotray ===
{{anchor|.3Cminimizetotray.3E}}
{{note|Available in Kodi v20 and above.}}

Windows only. Minimizes Kodi to the system tray. Defaults to false.
<syntaxhighlight lang=xml enclose="div">
<minimizetotray>true</minimizetotray>
</syntaxhighlight>

= Removed tags =
{{anchor|Recently removed tags}}
* {{anchor|.3Cthumbsize.3E}}'''<thumbsize>''' - replaced by <[[#imageres|imageres]]> in v12 Frodo
* {{anchor|.3Cfanartheight.3E}}'''<fanartheight>''' - replaced by <[[#fanartres|fanartres]]> in v12 Frodo
* {{anchor|.3Cdvdthumbs.3E}}'''<dvdthumbs>''' - removed in v12 Frodo
* {{anchor|.3Cbusydialogdelayms.3E}}'''<busydialogdelayms>''' - removed in v12 Frodo
* {{anchor|.3Cbginfoloadermaxthreads.3E}}'''<bginfoloadermaxthreads>''' - removed in v13 Gotham
* '''<showepginfoonselect>''' - replaced by a GUI setting in v13 Gotham
* '''<resample>''', '''<forceDirectSound>''', '''<audiophile>''', '''<audiosinkbufferdurationmsec>''', '''<allowtranscode44100>''', and '''<streamsilence>''' - These were various sub-tags for <audio> that were removed in v13 Gotham and either replaced by GUI settings or were no longer needed.
* {{anchor|.3Cenableairtunesdebuglog.3E}}'''<enableairtunesdebuglog>''' - replaced by a GUI option in v14 Helix
* '''<videoDisableHi10pMultithreading>''' - renamed to <disableswmultithreading> in v14 Helix
* '''<hideallitems>''' - For both the <code><videolibrary></code> and <code><musiclibrary></code> sections, this is replaced by a GUI option in v15 Isengard
* '''<SmallStepBackSeconds>''' - In v15 the <code>SmallStepBack</code> [[Action_IDs]] has been replaced by <code>seek(-7)</code> in default keymaps. See '''[[skip steps]]''' for details. When the original <code>SmallStepBack</code> action ID is used it defaults to the first backwards [[skip steps|additive seeking value]].
* '''<timeseekforward>/<timeseekbackward>''' - In v15 these tags are replaced by GUI options via [[skip steps|additive seeking]], which is configured in the GUI. See '''[[skip steps]]''' for details.
* {{anchor|.3Ckaraoke.3E}}'''<karaoke>''' - In v16 all of the karaoke features in Kodi were removed.
* '''<useddsfanart>''' - removed in v17 Krypton.
* '''<cachemembuffersize>''' and '''<readbufferfactor>''' - In v17 '''<cachemembuffersize>''' is renamed to '''<memorysize>''' and <code><readbufferfactor></code> is renamed to <code><readfactor></code>. In addition, all three buffer related settings in <network> are moved out of <network> and into a new <cache> parent tag.
* '''<minvideocachelevel>''', '''<minaudiocachelevel>''', and '''<cacheindvdplayer>''' have been removed in v17.
* '''<useffmpegvda>''' - Tag was only used for development testing. Removed in v17.
* '''<nofliptimeout>''' - Removed in v17
* '''<blackbarcolour>''' - Removed in v17 (maybe?)
* '''<disableswmultithreading>''' - Removed in v17 (maybe?)
* {{anchor|.3Cmeasurerefreshrate.3E}}'''<measurerefreshrate>''' - Removed in v17 or v18?
* {{anchor|.3Cmyth.3E}}'''<myth>''' - Removed sometime between v16 to v18
* {{anchor|.3Ctuxbox.3E}}'''<tuxbox>''' - Removed
* '''<backgroundupdate>''' - Removed
* '''<hideemptyseries>''' - Replaced by a GUI option.
* '''<mymovies>''' and child tag '''<categoriestogenres>''' - Removed
* '''<albumssortbyartistthenyear'''> - Removed
* '''<albumformatright>''' - Removed
* {{anchor|.3Cremoterepeat.3E}}'''<remoterepeat>''' - Removed
* {{anchor|.3Callowd3d9ex.3E}}'''<allowd3d9ex>''' and {{anchor|.3Cforced3d9ex.3E}}'''<forced3d9ex>''' - Removed sometime between v16 to v18
* '''<lingertime>''' - Replaced by a GUI setting in v18
* '''<forcevaapienabled>''' - Removed in v18
* '''<promptfulltagscan>false</promptfulltagscan>''' Removed in v18. Now automatically asked each time a scan is conducted.
* '''<controllerdeadzone>''' - Removed in v17
* '''<omxdecodestartwithvalidframe>''' - This tag is only in some Raspberry Pi specific distributions, such as OpenELEC. As of March 2015, this tag has not been merged into "vanilla" Kodi builds
* '''<musicthumbs>''' Replaced in v19 by the GUI setting '''Thumbnail image files''' found in Media -> Music
* '''<artistextraart>''' Replaced in v19 by the GUI setting '''Artist art types whitelist''' found in Media -> Music
* '''<albumextraart>''' Replaced in v19 by the GUI setting '''Album art types whitelist''' found in Media -> Music
* '''<episodeextraart>''' Replaced in v19 by the GUI setting '''Episode art types whitelist''' found in Media -> Videos
* '''<tvshowextraart>''' Replaced in v19 by the GUI setting '''TV show art types whitelist''' found in Media -> Videos
* '''<tvseasonextraart>''' Replaced in v19 by the GUI setting '''TV show art types whitelist''' found in Media -> Videos
* '''<movieextraart>''' Replaced in v19 by the GUI setting '''Movie art types whitelist''' found in Media -> Videos
* '''<moviesetextraart>''' Replaced in v19 by the GUI setting '''Movie art types whitelist''' found in Media -> Videos
* '''<musicvideoextraart>''' Replaced in v19 by the GUI setting '''Music video art types whitelist''' found in Media -> Videos
* '''<fanart>''' Removed in v19
* '''<assfixedworks>''' Removed in v20
* '''<try10bitoutput>''' Removed in v20 and replaced with [[Settings/System/Display#Use_10_bit_for_SDR|Use 10 bit for SDR]] setting <ref>https://github.com/xbmc/xbmc/pull/20014</ref>

= guisettings.xml Setting Conversion =
It is possible to convert settings found in the '''[[Settings]]''' ''(guisettings.xml)'' pages of {{kodi}} into entries for the advancedsettings.xml file.

When a setting from the guisettings.xml is added to the advancedsettings.xml file, it will override the existing guisettings.xml values and the setting will be removed from the settings pages.

Why would I need to do this?
* You set up multiple devices and then need to individually change settings and preferences on each device. Using this conversion method, you save those settings in the advancedsettings.xml file and simply add the file to each device
* You need to hide settings to prevent those settings from being modified

To convert a guisetting to advancedsettings.xml follow these steps:
# In the {{kodi}} settings pages, adjust the setting(s) to your preference.
# Back out of the settings pages to the main menu, which forces {{kodi}} to save the adjusted settings to the guisettings.xml file
# Locate the guisettings.xml file in the [[Userdata]] folder and open it
# Locate the setting(s) to be converted. The list can be overwhelming so make use of the Search feature of whichever editor you are using
# Using the following setting as an example:
<syntaxhighlight lang="xml">
<setting id="videolibrary.showemptytvshows">true</setting>
</syntaxhighlight>
: Breaking down the string:
::'''videolibrary'''- parent tag
::'''showemptytvshows'''- child tag
::'''true'''- value
: The conversion is as follows and place this in the advancedsettings.xml file
<syntaxhighlight lang="xml">
<advancedsettings version="1.0">
<videolibrary>
<showemptytvshows>true</showemptytvshows>
</videolibrary>
</advancedsettings>
</syntaxhighlight>

'''Note:''' Some parent tags may already be in use in your advancedsettings.xml file. Do not duplicate them, but add the child tag beneath the existing parent tag.

= References =
<references />

{{Updated|18}}
{{DISPLAYTITLE:advancedsettings.xml}}

[[Category:Advanced topics]]
[[Category:Manual]]
[[Category:Settings]]

PulseAudio

2023-02-11T19:25:53Z

Fritsch: Update AE_SINK to KODI_AE_SINK, we have v20 out of the door.

{{mininav|[[Audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation, in order to get 7.1 audio Multichannel Mode must be used}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync. In the case of video with TrueHD/DTS-HD 7.1 audio this must be decoded by Kodi to Multichannel PCM by disabling passthrough, then Pulseaudio can handle the 7.1 channels of audio.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". As Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always an exclusive mode. If you have another application hogging the device, e.g. Chrome or Skype, passthrough won't work. Even applications that simply monitor the device, such as SoundWireServer, will prevent passthrough from working.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate passthrough codecs, setup pavucontrol as following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, first, first identify the correct sound card ID:
'''pacmd list-cards'''

Look at the output to find the id of the card and the name/format of the profile you want to use (in this case, card ID is '''0''' and profile is '''output:hdmi-stereo''')
Once you've identified this information, set your output profile to the one for hdmi-stereo:
'''pacmd set-card-profile 0 output:hdmi-stereo'''

Then, obtain the sink ID you want to set formats on by inspecting output of:
'''pactl list sinks'''

Then set the sink format for the sink you want, as below (in this case '''0'''):
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

{{redv|'''IMPORTANT:'''| Enabling ''' Sync Playback to Display ''' will disable passthrough silently, as it makes zero sense to sync with a display clock while one cannot alter audio.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PulseAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second avoid resampling. Starting with version 11 of pulseaudio, it can reopen sinks with their native samplerate. Furthermore you need to take care, that your sink has a wide enough output format. To properly resample samperates that are not available with your sound card, e.g. 176000 or other exotic rates, we set pulseaudio to a default of 44100 khz, which is the default for every standard mp3. As alternate sample-rate we suggest 48000. That means that all non available samplerates are resampled with an exact integer division of src_rate / dst_rate.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s24le
default-sample-rate = 44100
alternate-sample-rate = 48000
;new with pulseaudio 11
avoid-resampling = true
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|Doing so may cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>pasuspender -- env KODI_AE_SINK=ALSA kodi</pre>

'''pasuspender''' is a tool that can be used to tell a local PulseAudio sound server to temporarily suspend access to the audio devices, to allow other applications access them directly. pasuspender will suspend access to the audio devices, fork a child process, and when the child process terminates, resume access again.

You can also put the previous command in a custom .desktop-file.

Be warned as this will interfere with your Desktop sounds!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

Audio devices are disappearing with pulseaudio 8.0 (Ubuntu 16.04, even later version are affected) especially while running kodi and while using ''Adjust Refreshrate to match video''. This is an issue with the module-switch-on-port-available module and will be fixed with pulseaudio 9.0, the fix sadly won't probably make it into Ubuntu 16.04. As a workaround please disable that feature by editing /etc/pulse/default.pa and commenting or removing ''load-module module-switch-on-port-available'' and reboot the system.

''' Kodi v16 '''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

''' Kodi v17 '''

Starting with the upcoming kodi v17 Krypton the above behaviour is taken care within kodi. You don't have to disable remixing in pulseaudio anymore. That means content is output without further remixing by pulseaudio server if a sane mapping is possible. Basically that means if the audio is FL, FR, FC, LFE, SL, SR and your speaker-mapping is FL, FR, FC, LFE, BL, BR we will resolve that and output 6 channels accordingly. Whenever we cannot map all input channels to the output we ask pulseaudio to do the mixing for us.

''' Volume issues '''

Issue: Changing kodi's volume will change overall system volume, especially on song change this is an irritating behaviour. The effect you hear is not done by kodi, but by a systemwide pulseaudio (mis)configuration. Some distributions sadly still ship pulseaudio with '''flat-volumes = yes''' as the default, which produces this behaviour. In fact it will cause the hardware volume (or master volume) to go up and down for every pulseaudio stream that changes its own volume. As this effect is unexpected behaviour for users, distributions started to ship pulseaudio with '''flat-volumes = no''' by default (as time of writing this is Ubuntu, Arch-Linux and others). In order to change that setting, depending on your distribution edit ''/etc/pulse/daemon.conf'' and set '''flat-volumes = no'''. After a PA server restart, the volume handling is more intuitive. If you are at it, please inform your distribution about those issues, so that they can ship a more user-friendly default with next release. At the time of writing, affected distributions: Debian.

[[Category:Audio]]

Advancedsettings.xml

2023-02-04T06:03:18Z

Fritsch: maxpassthroughoffsyncduration added

{{TOC right}}{{mininav|[[Settings]]|page=advancedsettings.xml}}
{{bigger|{{note|'''The advancedsettings.xml file does not exist by default. You have to create it first!'''}} }}

<section begin="intro" />The [[advancedsettings.xml]] file, which does not exist by default, can be created by a user in their '''[[Userdata|userdata folder]]'''.

This file is used for advanced settings and options that do not have GUI controls inside of {{kodi}}. Some settings are experimental or very rarely set, so they can only be used via the advancedsettings.xml file. The file is simply a plain text file and can be edited by various text editors, so long as the name is "advancedsettings.xml". These advanced settings can be used to tweak various things such as episode naming patterns, special network ports, special behaviors, and more.<section end="intro" />

The following page will describe the structure of the advancedsettings.xml file and the various individual settings.

{{note|
# All XML tags must be lowercase. The start and end of the advancedsettings.xml file must have the <advancedsettings> and </advancedsettings> tags.
# Kodi will only read the advancedsettings.xml file when it starts up. If you make changes while it is running then you must restart Kodi.
# For some Windows versions, Kodi has two <code>\userdata\</code> folders. The correct one to put the advancedsettings.xml file in is not the one in Program Files, but in <code>%appdata%\Kodi\userdata\.</code>}}

== Layout ==

The layout of <code>advancedsettings.xml</code> is as follows:

<syntaxhighlight lang=xml enclose="div">
<advancedsettings version="1.0">
<setting>value</setting>
...
<setting>value</setting>
</advancedsettings>
</syntaxhighlight>

where "setting" gives the name of the setting, and "value" gives its value.

A list of the available "setting" strings and their values is given below.

= List of available settings =
List of available settings that are recognised in the advancedsettings.xml file <ref>https://github.com/xbmc/xbmc/blob/master/xbmc/settings/AdvancedSettings.cpp</ref>

Recommended: Use the table of contents or the search function in your browser to locate items.

== Troubleshooting settings ==

=== loglevel ===
{{Anchor|.3Cloglevel.3E}}

<section begin="loglevel" />
Sets the logging level used to log errors and information. The "hide" attribute is optional.

<syntaxhighlight lang=xml>
<loglevel hide="attribute">options</loglevel>
</syntaxhighlight>

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Attribute
! style="width:500px;" | Action
|-
! '''true'''
| Hides the "enable debugging" setting in the Settings page. (default)
|-
! '''false'''
| Allows "enable debugging" setting to switch between '''0''' and '''2'''.
|}

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Option
! style="width:500px;" | Action
|-
! '''-1'''
| No logging, suppresses all log output
|-
! '''0'''
| Normal logging, only logging errors (default)
|-
! '''1'''
| Debug logging with freemem, fps and cpu usage (no on screen)
|-
! '''2'''
| Same as 1 (with on screen display)
|-
! '''3'''
| Same as 1 + full smb logging
|}

{| class="wikitable"
|-
! style="width:100px;" | Example
! style="width:500px;" |
|-
! Example 1:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings>
<loglevel>2</loglevel>
</advancedsettings>
</syntaxhighlight>
|-
! Example 2:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings>
<loglevel hide="true">2</loglevel>
</advancedsettings>
</syntaxhighlight>
|}

'''Note:''' The setting is persistent through shutdown and restarts.<br>
'''Note:''' If debugging is enabled in the GUI, loglevel will be set to '''2'''. This will over-ride the <code>advancedsettings.xml</code> setting. You must disable the GUI Setting before adding the entry to <code>advancedsettings.xml</code>.<br />
<section end="loglevel" />
:''{{see also|Log_file|label 1=Debug Log}}''

=== jsonrpc ===
{{Anchor|.3Cjsonrpc.3E}}
To make it easier for developers using the [[JSON-RPC_API]] API in their (third party) applications to debug during development the json output of Kodi can be prettified by setting '''compactoutput''' to '''false'''. Default json output mode is a compact print which does not contain any unnecessary whitespaces and therefore is difficult to read for humans.
Furthermore using the '''tcpport''' setting it is possible to change the default TCP port used by Kodi for JSON RPC (which is 9090) to any other valid port.

Example:
<syntaxhighlight lang=xml enclose="div">
<jsonrpc>
<compactoutput>false</compactoutput>
<tcpport>9999</tcpport>
</jsonrpc>
</syntaxhighlight>

== Audio/video playback settings ==

=== skiploopfilter ===
{{anchor|.3Cskiploopfilter.3E}}
The amount of the loop filter to skip on h.264 decoding. This can help the performance of slower machines when decoding h264 content. Values, in decreasing CPU usage (and decreasing quality)
* -16 None
* 0 Skip only empty frames (default)
* 8 Skip non-reference frames
* 16 Skip bi-dir frames
* 32 Skip all non-key frames
* 48 Skip all frames
Example:
<syntaxhighlight lang=xml enclose="div">
<skiploopfilter>8</skiploopfilter>
</syntaxhighlight>

=== video ===
{{anchor|.3Cvideo.3E}}

The <video> section also includes the following child-tags, which have their own sections:
*[[#cleandatetime]]
*[[#cleanstrings]]
*[[#excludefromscan]]
*[[#excludefromlisting]]
*[[#excludetvshowsfromscan]]

{{note|Some tags that have a "third-level" and are grouped together are highlighted in color.}}

{| class="prettytable"
! Tag !! Description
|-
|
<syntaxhighlight lang=xml>
<video>
</syntaxhighlight>
| Parent tag that all other child tags need to be placed inside of. Do not use more than one '''<code><video></code>''' tag, but instead place all other child-tags within a single '''<code><video></video></code>''' set.
|-
|
<syntaxhighlight lang=xml>
<subsdelayrange>10</subsdelayrange>
</syntaxhighlight>
| Delay range for subtitles, in seconds.
|-
|
<syntaxhighlight lang=xml>
<maxtempo>2.1</maxtempo>
</syntaxhighlight>
| Allow further increase of playback speed over the default of 1.5<br>
maxtempo must be in the range of 1.5 to 2.1 <br>
Be aware of the limitations of your platform / hardware as not all are capable of the increased maxtempo <ref>https://forum.kodi.tv/showthread.php?tid=10023&pid=2795069#pid2795069</ref>
|-
|
<syntaxhighlight lang=xml>
<audiodelayrange>10</audiodelayrange>
</syntaxhighlight>
| Delay range for audio/video sync, in seconds.
|-
|
<syntaxhighlight lang=xml>
<usetimeseeking>true</usetimeseeking>
</syntaxhighlight>
| Whether to use time based or percentage based seeking. {{small see also|Skip steps}}
|-
|
<syntaxhighlight lang=xml>
<timeseekforwardbig>600</timeseekforwardbig>
<timeseekbackwardbig>-600</timeseekbackwardbig>
</syntaxhighlight>
| Time to seek forward in seconds when doing a long seek. Defaults to 600 (10 minutes) and -600 (-10 minutes) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforward>2</percentseekforward>
<percentseekbackward>-2</percentseekbackward>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a short seek. Defaults to 2 (2%) and -2 (2%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforwardbig>10</percentseekforwardbig>
<percentseekbackwardbig>-10</percentseekbackwardbig>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a long seek. Defaults to 10 (10%) and -10 (10%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<fullscreenonmoviestart>true</fullscreenonmoviestart>
</syntaxhighlight>
| Whether to go to fullscreen or not when starting a movie. Defaults to true.
|-
|
<syntaxhighlight lang=xml>
<defaultplayer>VideoPlayer</defaultplayer>
</syntaxhighlight>
| Set the default video player: VideoPlayer or an external player. See '''[[External players]]''' for more info.
|-
|
<syntaxhighlight lang=xml>
<excludefromscan>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromscan>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be added to library. It is possible to add multiple <code><regexp></code> tags to match multiple patterns
|-
|
<syntaxhighlight lang=xml>
<excludefromlisting>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be displayed in files view.
|-
|
<syntaxhighlight lang=xml>
<playcountminimumpercent>90</playcountminimumpercent>
</syntaxhighlight>
| Minimum percentage that has to be played before it is marked as watched. Set to 101 to never auto-mark items as watched. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignoresecondsatstart>180</ignoresecondsatstart>
</syntaxhighlight>
| Number of seconds to ignore at video start after which a resume point is created. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignorepercentatend>8</ignorepercentatend>
</syntaxhighlight>
| Percentage of video to ignore at the end. If you stop watching the video here no resume point is created. Set to 101 to never save a resume point. The video is already marked as watched at 90%, see above. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<vdpauscaling>true</vdpauscaling>
</syntaxhighlight>
| Scales with vdpau instead of opengl and turns on its HQ scaler when available, enabling this might slow down rendering and cause framedrops especially on ION systems, this setting requires a vdpau feature set C GPU.
|-
|
<syntaxhighlight lang=xml>
<enablehighqualityhwscalers>true</enablehighqualityhwscalers>
</syntaxhighlight>
| Allow turning on the spline36 and lanczos3 shader (for GL builds).
|-
|
<syntaxhighlight lang=xml>
<dxvaallowhqscaling>false</dxvaallowhqscaling>
</syntaxhighlight>
| Enables high quality video upscaling for Windows.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegdeinterlacing>linblenddeint</ppffmpegdeinterlacing>
</syntaxhighlight>
| Override the deinterlacing options passed to libpostproc.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegpostprocessing>ha:128:7,va,dr</ppffmpegpostprocessing>
</syntaxhighlight>
| Override the post processing options passed to libpostproc when 'Video post-processing' is activated in GUI Videos-Settings-Playback.
|-
|
<syntaxhighlight lang=xml>
<autoscalemaxfps>30</autoscalemaxfps>
</syntaxhighlight>
| When scaling method is set to auto, bilinear is chosen when the fps is higher than this limit, the default is 30.
|-
|
<syntaxhighlight lang=xml>
<adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" | Settings for when "Adjust refreshrate to match video fps" is enabled in the video playback GUI settings.
|-
|
<syntaxhighlight lang=xml>
<override>
<fps>23.976</fps>
<refresh>60.0</refresh>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' "Adjust refreshrate to match video fps" will try to select the best refreshrate for the video fps but it doesn't always get it right, for example it might switch to an unsupported refreshrate. You can add overrides here to switch to a certain refreshrate based on video fps. It's possible to add as many overrides as you need. Overrides are processed in order, if the first one doesn't match the fps or no refreshrates match that override, it will try the next one until no overrides are left.

* '''fps''' - if the fps is between 23.966 and 23.986
* '''refresh''' - switch to the first found refreshrate that is between 59.99 and 60.01
|-
|
<syntaxhighlight lang=xml>
<override>
<fpsmin>29.96</fpsmin>
<fpsmax>30.01</fpsmax>
<refreshmin>59.0</refreshmin>
<refreshmax>61.0</refreshmax>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -'''
* '''fpsmin''' / '''fpsmin''' - You can also specify the fps range yourself.
* '''refreshmin''' / '''refreshmax''' - Same for the refreshrate
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refresh>50.0</refresh>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' If none of the overrides match, or none of the refreshrates match any of the fps matching overrides, it will choose a fallback refreshrate. Fallbacks are process in order, if the first fallback doesn't match any refreshrate, it will try the next one until no fallbacks are left.

* '''refresh''' - Switch to the first found refreshrate that is between 49.99 and 50.01.
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refreshmin>49.0</refreshmin>
<refreshmax>51.0</refreshmax>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' You can also specify the range for the fallback yourself.

If none of the overrides match the video fps, or no refreshrates match any of the fps matching overrides, and no fallbacks are specified or no refreshrates match any fallbacks, it will automatically choose the best refreshrate (same as having no overrides and fallbacks).
|-
|
<syntaxhighlight lang=xml>
</adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" |
|-
|
<syntaxhighlight lang=xml>
<checkdxvacompatibility>value</checkdxvacompatibility>
</syntaxhighlight>
| Advanced setting not present: let Kodi autodetect cards that support H.264 profile > L4.1. Set value to false to enable DXVA no matter what. Set value to true if Kodi doesn't autodetect that the graphics card doesn't support > L4.1.
|-
|
<syntaxhighlight lang=xml>
<useocclusionquery>-1</useocclusionquery>
</syntaxhighlight>
| Use an occlusion query when capturing videoframes, -1 means auto detect, 0 means disabled, 1 means enabled, the default is -1.
|-
|
<syntaxhighlight lang=xml>
<fpsdetect>1</fpsdetect>
</syntaxhighlight>
| FPS detection for video playback
* 0 = trust codec fps
* 1 = recalculate from video timestamps with uniform spacing
* 2 = recalculate from video timestamps always
|-
|
<syntaxhighlight lang=xml>
<latency>
</syntaxhighlight>
| style="background:#F0E68C;"| Start of '''latency''' tags. Display latency (video lag). Latency is given in msecs.
|-
|
<syntaxhighlight lang=xml>
<delay>0</delay>
</syntaxhighlight>
| style="background:#F0E68C;" | Global default display latency.
|-
|
<syntaxhighlight lang=xml>
<refresh></refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | Override latency for given display (not video) refresh rates. When Kodi is in windowed mode, override is ignored. Multiple overrides are allowed.

Syntax of an override entry:
<syntaxhighlight lang=xml>
<refresh>
<min>, <max> refresh rate range, OR
<rate> exact refresh rate
<delay> display latency for the given refresh rate
</refresh>
</syntaxhighlight>
|-
|
<syntaxhighlight lang=xml>
<refresh>
<min>23</min>
<max>24</max>
<delay>125</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 125 msec latency at 23-24 Hz
|-
|
<syntaxhighlight lang=xml>
<refresh>
<rate>50</rate>
<delay>50</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 50 msec latency at 50 (+/-0.01) Hz
|-
|
<syntaxhighlight lang=xml>
</latency>
</syntaxhighlight>
| style="background:#F0E68C;" |
|-
|
<syntaxhighlight lang=xml>
<stereoscopicregex3d>[-. _]3d[-. _]</stereoscopicregex3d>
<stereoscopicregexsbs>[-. _]h?sbs[-. _]</stereoscopicregexsbs>
<stereoscopicregextab>[-. _]h?tab[-. _]</stereoscopicregextab>
</syntaxhighlight>
| Filename triggers for 3D (stereoscopic) mode.
|-
|
<syntaxhighlight lang=xml>
<assfixedworks>false</assfixedworks>
</syntaxhighlight>
| Position behavior of ass subtitiles when setting "subtitle position on screen" set to "fixed". True to show at the fixed position set in video calibration. False to show at the bottom of video (default). {{note|Removed in Kodi v20.}}
|-
|
<syntaxhighlight lang=xml>
<subtitleverticalmargin>120</subtitleverticalmargin>
</syntaxhighlight>
| Allows to customise the vertical margin of text based subtitles, which will be applied to each type of subtitle position in subtitle settings. {{note|Available in Kodi v20 and above.}}
|-
|
<syntaxhighlight lang=xml>
</video>
</syntaxhighlight>
|
|}

=== audio ===
{{anchor|.3Caudio.3E}}
<syntaxhighlight lang=xml enclose="div">
<audio>

<headroom>0</headroom>

<defaultplayer>paplayer</defaultplayer>

<excludefromscan>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromscan>

<excludefromlisting>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromlisting>

<ac3downmixgain>12.0</ac3downmixgain>

<usetimeseeking>true</usetimeseeking>

<timeseekforwardbig>600</timeseekfowardbig>

<timeseekbackwardbig>-600</timeseekbackward>

<playcountminimumpercent>99</playcountminimumpercent>

<applydrc>-1.0</applydrc>

<limiterhold>0.025</limiterhold>

<limiterrelease>0.1</limiterrelease>

<maxpassthroughoffsyncduration>10</maxpassthroughoffsyncduration>
</audio>
</syntaxhighlight>

=== forcedswaptime ===
{{anchor|.3Cforcedswaptime.3E}}
Use to force a backbuffer->frontbuffer swap while vsync is enabled. Set to the time (in ms) to allow for the swap (e.g. <forcedswaptime>1</forcedswaptime> is typical).

Default: Off

=== edl ===
{{anchor|.3Cedl.3E}}
{{main|Edit_decision_list}}
Commercial break detection not as good you think it could be? Are some commercial breaks in a series of adverts not being skipped? Are some parts being skipped that are clearly not commercials? Does the end of the previous recording still show? The following advanced settings can be used to better identify full commercial break sequences, remove incorrectly flagged commercial breaks, and have playback start at the actual beginning of the recording.

<syntaxhighlight lang=xml enclose="div">
<edl>

<mergeshortcommbreaks>false</mergeshortcommbreaks>

<maxcommbreaklength>250</maxcommbreaklength>

<mincommbreaklength>90</mincommbreaklength>

<maxcommbreakgap>120</maxcommbreakgap>

<commbreakautowait>0</commbreakautowait>

<commbreakautowind>0</commbreakautowind>
</edl>
</syntaxhighlight>

== PVR & Live TV ==
{{anchor|.3Cpvr.3E}}
Settings available for PVR, EPG and Live TV. Edit Decision List settings are located in the previous section.

=== pvr ===
<syntaxhighlight lang="xml" line='line'>
<pvr>
<timecorrection>0</timecorrection> 
<infotoggleinterval>3000</infotoggleinterval> 
<channeliconsautoscan>true</channeliconsautoscan> 
<autoscaniconsuserset>false</autoscaniconsuserset> 
<numericchannelswitchtimeout>1000</numericchannelswitchtimeout> 
</pvr>
</syntaxhighlight>

==== pvrrecordings ====
In v19 and later, allows users to modify sort type and order of pvr recordings. <ref>https://github.com/xbmc/xbmc/pull/18605</ref>

;Note- These settings are child tags to the ''<pvr>'' tag in the previous section.

<syntaxhighlight lang="xml" line='line'>
<pvr>
<pvrrecordings>
<sortmethod>2</sortmethod> 
<sortorder>2</sortorder> 
</pvrrecordings>
</pvr>
</syntaxhighlight>

=== epg ===
{{anchor|.3Cpvr.3E}}
<syntaxhighlight lang="xml" line='line'>
<epg>
<updatecheckinterval>300</updatecheckinterval> 
<updateemptytagsinterval>60</updateemptytagsinterval> 
<cleanupinterval>900</cleanupinterval> 
<activetagcheckinterval>60</activetagcheckinterval> 
<retryinterruptedupdateinterval>60</retryinterruptedupdateinterval> 
<displayupdatepopup>true</displayupdatepopup> 
<displayincrementalupdatepopup>false</displayincrementalupdatepopup> 
</epg>
</syntaxhighlight>

== Video library settings ==

=== videoextensions ===
{{anchor|.3Cvideoextensions.3E}}<section begin="videoextensions" />
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Video windows.

Default extensions for VIDEOS:
<pre>
.m4v .3g2 .3gp .nsv .tp .ts .ty .strm .pls .rm .rmvb .mpd .m3u .m3u8 .ifo .mov .qt .divx .xvid
.bivx .vob .nrg .img .iso .udf .pva .wmv .asf .asx .ogm .m2v .avi .bin .dat .mpg .mpeg .mp4
.mkv .mk3d .avc .vp3 .svq3 .nuv .viv .dv .fli .flv .001 .wpl .xspf .zip .vdr .dvr-ms .xsp .mts
.m2t .m2ts .evo .ogv .sdp .avs .rec .url .pxml .vc1 .h264 .rcv .rss .mpls .mpl .webm .bdmv
.bdm .wtv .trp .f4v
</pre>
Examples:
<pre>
<videoextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</videoextensions>
</pre>
<section end="videoextensions" />

=== discstubextensions ===
{{main|Media stubs}}

<section begin="discstubextensions" />
The default filename extension for Disc Stubs is:
<syntaxhighlight lang=xml enclose="div">
.disc
</syntaxhighlight>
Using the following tags, it is possible to <tt><add></tt> additional or <tt><remove></tt> existing disc stub extensions to better suit your requirements.
<syntaxhighlight lang=xml enclose="div">
<discstubextensions>
<add>.disk|.stub</add>
<remove>.disc</remove>
</discstubextensions>
</syntaxhighlight>
<section end="discstubextensions" />

=== languagecodes ===
{{anchor|.3Clanguagecodes.3E}}
User-defined translation table for language codes used in subtitles and audio.
It can be used to add, extend or override Kodi's language codes.

'''How to add a new language code:'''

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>alt</short>
<long>Alternate</long>
</code>
</languagecodes>
</syntaxhighlight>

'''How to add a new language code with subtag (e.g. pt-BR):'''
{{note|This support is available from Kodi v20}}

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>pt-BR</short>
<long>Portuguese - Brazil</long>
</code>
</languagecodes>
</syntaxhighlight>

'''How to extend an existing language code:'''

Set the same "long" description of the existing language, for example we reuse the Portughese language for another language code:

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>pt-BR</short>
<long>Portuguese</long>
</code>
</languagecodes>
</syntaxhighlight>

In this case when in Kodi settings you set the "Portuguese" language, when in playing according to availability the track "pt" or "pt-BR" will be chosen.

'''How to override an existing language code:'''

This allow you to rename an existing language. Set to an existing language code your preferred "long" name description.

''WARNING: This can cause problems with add-ons, so do not override languages if you are not aware of the side effects.''

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>en</short>
<long>English example</long>
</code>
<code>
<short>en-GB</short>
<long>English example</long>
</code>
</languagecodes>
</syntaxhighlight>

=== moviestacking ===
{{anchor|.3Cmoviestacking.3E}}<section begin="moviestacking" />
{{main|Naming_video_files/Movies}}
This is used by the [[Naming_video_files/Movies#Split_Video_Files|file stacking]] algorithm to combine multi-part files and contains a list of regular expressions. For stacking videos that are contained in folders, such as VIDEO_TS folders, see '''[[advancedsettings.xml#folderstacking|<folderstacking>]]'''

As of v9.11, video stacking regular expressions '''must''' contain exactly four (4) capture expressions.

Default:
<syntaxhighlight lang=xml enclose="div">
<moviestacking>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[0-9]+)(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[a-d])(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ ._-]*[a-d])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="append"</tt> or <tt>append="yes"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the end.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="append">

<regexp>(.*?)([ ._-]*[0-9])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="prepend"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the beginning.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="prepend">
<regexp>(Title)(Volume)(Ignore)(Extension)</regexp>
</moviestacking>
</syntaxhighlight>

If no argument is supplied, or the argument <tt>append="no"</tt> is supplied, the default moviestacking regular expressions are overwritten by the user specified ones.
<section end="moviestacking" />

=== folderstacking ===
{{main|Naming_video_files/Movies}}
This is similar to '''[[advancedsettings.xml#moviestacking|<moviestacking>]]''', but is used for videos that are contained in folders that use the folder names to stack, such as VIDEO_TS folders (DVD rips that are not in ISO format).

Default:
<syntaxhighlight lang=xml enclose="div">
<folderstacking>

<regexp>((cd|dvd|dis[ck])[0-9]+)$</regexp>
</folderstacking>
</syntaxhighlight>

=== cleandatetime ===
{{anchor|.3Ccleandatetime.3E}}
Matches a year number in a string using a Regular Expression

Default expression:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleandatetime>(.*[^ _\,\.\[\]\-])[ _\.\[\]\-]+(19[0-9][0-9]|20[0-9][0-9])([ _\,\.\[\]\-]|[^0-9]$)?</cleandatetime>
</video>
</syntaxhighlight>
:* The string found before will be used as basis string getting cleaned by the cleanstrings expressions.
:* By default date formats like MM:YY are ignored.

=== cleanstrings ===
{{anchor|.3Ccleanstrings.3E}}
Clean unwanted characters from filenames or folders by using a list of Regular Expressions. Please note that everything right of the match (at the end of the file name) is removed, so if you would have a file named ''Super movie.mp4'' and would add <tt><regexp> </regexp></tt> (only a space), the only thing that would be left is ''Super'', which is probably not what you want.

{{Github_link|[https://github.com/xbmc/xbmc/blob/Matrix/xbmc/settings/AdvancedSettings.cpp#L188 Code in Github]}}

Default expressions:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleanstrings>
<regexp>[ _\,\.\[\]\-](aka|ac3|dts|custom|dc|remastered|divx|divx5|dsr|dsrip|dutch|dvd|dvd5|dvd9|dvdrip|dvdscr|dvdscreener|screener|dvdivx|cam|fragment|fs|hdtv|hdrip|hdtvrip|internal|limited|multisubs|ntsc|ogg|ogm|pal|pdtv|proper|repack|rerip|retail|r3|r5|bd5|se|svcd|swedish|german|read.nfo|nfofix|unrated|extended|ws|telesync|ts|telecine|tc|brrip|bdrip|480p|480i|576p|576i|720p|720i|1080p|1080i|3d|hrhd|hrhdtv|hddvd|bluray|x264|h264|xvid|xvidvd|xxx|www.www|cd[1-9]|\[.*\])([ _\,\.\[\]\-]|$)</regexp>
<regexp>(\[.*\])</regexp>
</cleanstrings>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== tvshowmatching ===
{{anchor|.3Ctvshowmatching.3E}}
Matches the season and episode numbers in file paths by using a list of Regular Expressions

{{Github_link|[https://github.com/xbmc/xbmc/blob/Matrix/xbmc/settings/AdvancedSettings.cpp#L232 Code in Github]}}

Defaults:
<syntaxhighlight lang=xml enclose="div">
<tvshowmatching>
<regexp>s([0-9]+)[ ._x-]*e([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)([^\\\\/]*)$</regexp> 
<regexp>[\._ -]()[Ee][Pp]_?([0-9]+)([^\\/]*)$</regexp> 
<regexp>([0-9]{4})[\.-]([0-9]{2})[\.-]([0-9]{2})</regexp> 
<regexp>([0-9]{2})[\.-]([0-9]{2})[\.-]([0-9]{4})</regexp> 
<regexp>[\\/\._ \[\(-]([0-9]+)x([0-9]+)([^\\/]*)$</regexp> 
<regexp>[\\/\._ -]([0-9]+)([0-9][0-9])([\._ -][^\\/]*)$</regexp> 
<regexp>[\/._ -]p(?:ar)?t[_. -]()([ivx]+)([._ -][^\/]*)$</regexp> 
</tvshowmatching>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)
:* Paths are converted to lower case before matching.
:* For multi-episode matching to work, there needs to be a third set of parentheses '()' at the end, this part is fed back into the regexp engine.
:* A [https://forum.kodi.tv/showthread.php?tid=51614 forum thread] has a discussion of pre-made regex lists to match common names. These might improve Kodi's ability to match TV show names in some situations, at the risk of additional false positives.

==== Filenames without Season ====
There are two methods to add episodes without a season in their file path. Both ways will force the season to '1' by default, so that you can use
the 'Use Absolute Ordering (Single Season)' setting from the TheTvDb.com scraper.

; Simple Method ''(XBMC v9.11 onwards and Kodi)''
: Use only one pair of parentheses
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]([0-9]+)</regexp></syntaxhighlight>
; Advanced Method ''(XBMC v10.05 onwards and Kodi)''
: Supports multi-episode files without season
: Use an empty pair of parentheses for the season
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

; Specifying Default Season ''(XBMC v12.0 onwards and Kodi)''
It is possible to set the default season for specific regular expressions by setting the 'defaultseason' attribute.
: Works with both the simple method and advanced method
: If not used, the season will be set to '1'
: Useful for setting specials to season '0'
<syntaxhighlight lang=xml enclose="div"><regexp defaultseason="0">[/\._ \-]X()([0-9]+)(-[0-9]+)?</regexp>
<regexp defaultseason="1">[/\._ \-]E()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

=== tvmultipartmatching ===
{{anchor|.3Ctvmultipartmatching.3E}}
Matches a multipart episode number based on a previously identified episode file, using a list of Regular Expressions.

Default:
<syntaxhighlight lang=xml enclose="div">
<tvmultipartmatching>^[-_ex]+([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)</tvmultipartmatching>
</syntaxhighlight>
:* Text matching is compared case-insensitive.
:* Specifying this option '''replaces''' the default value

=== excludefromscan ===
{{anchor|.3Cexcludefromscan.3E}}
Matches filenames or folders which should be excluded from a library scan (except tvshows) using a list of Regular Expressions. This can be for both Video or Audio sections of <tt>advancedsettings.xml</tt>.

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromscan>
<regexp>-trailer</regexp>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludefromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== excludefromlisting ===
{{anchor|.3Cexcludefromlisting.3E}}
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromlisting> 
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</video>
</syntaxhighlight>

=== excludetvshowsfromscan ===
{{anchor|.3Cexcludetvshowsfromscan.3E}}
Matches filenames or folders which should be excluded from a tvshow library scan using a list of Regular Expressions

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludetvshowsfromscan>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludetvshowsfromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== trailermatching ===
{{anchor|.3Ctrailermatching.3E}}
Contains Regular Expression syntax to match the locally stored trailers to movies in the library.

<syntaxhighlight lang=xml enclose="div">
<trailermatching>

<regexp>(.*?)(_Trailer)(\.[^.]+)$</regexp>
</trailermatching>
</syntaxhighlight>

=== videolibrary ===
{{anchor|.3Cvideolibrary.3E}}
Options specific to the Video Library

{{Note|Kodi v20 users don't need set "importwatched" or "importresumepoint" to true anymore as that's the default then <ref>https://github.com/xbmc/xbmc/pull/20842</ref>}}

<syntaxhighlight lang="xml" line='line'>
<videolibrary>
<allitemsonbottom>false</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<usefasthash>true</usefasthash> 
<recentlyaddeditems>35</recentlyaddeditems> 
<itemseparator> / </itemseparator> 
<exportautothumbs>false</exportautothumbs> 
<importwatchedstate>false</importwatchedstate> 
<importresumepoint>false</importresumepoint> 
<dateadded>1</dateadded> 
</videolibrary>
</syntaxhighlight>

==== Extra artwork ====

Applies to Kodi v18 only.

Configuration to expand the artwork automatically added by Kodi to media items in the library, either from local files or online scrapers.

The original basic artwork types are still hardcoded so they don't need to be configured here (and can't be removed). "poster" and "fanart" for movies, movie sets, TV shows, seasons, and music videos; "banner" for TV shows and seasons; and "thumb" for episodes.

<syntaxhighlight lang=xml enclose="div">
<videolibrary>


<tvshowextraart>
<arttype>characterart</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>landscape</arttype>
<arttype>keyart</arttype>
</tvshowextraart>

<tvseasonextraart>
<arttype>landscape</arttype>
</tvseasonextraart>

<episodeextraart>
<arttype>fanart</arttype>
</episodeextraart>

<movieextraart>
<arttype>banner</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>discart</arttype>
<arttype>landscape</arttype>
<arttype>keyart</arttype>
</movieextraart>

<moviesetextraart>
<arttype>banner</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>discart</arttype>
<arttype>landscape</arttype>
<arttype>keyart</arttype>
</moviesetextraart>

<musicvideoextraart>
<arttype>banner</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>discart</arttype>
<arttype>landscape</arttype>
</musicvideoextraart>
</videolibrary>
</syntaxhighlight>

=== videoscanner ===
{{anchor|.3Cvideoscanner.3E}}
Options specific to the Video scanner
<syntaxhighlight lang=xml enclose="div">
<videoscanner>
<ignoreerrors>true</ignoreerrors> 
</videoscanner>
</syntaxhighlight>

== Library artwork ==

{{note|Using <imageres>9999</imageres> and <fanartres>9999</fanartres> will allow caching artwork at original size.}}

=== imageres ===
{{anchor|.3Cimageres.3E}}

<section begin="imageres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached artwork]] (other than fanart / 16:9 images) should be resized to in pixels. The width is automatically calculated as being 16/9*height. The image will be resized to fit within this size. e.g. an image that is 2000x500 will be cached at size 1280x320. An image that is 500x800 will be cached at size 450x720 using the default value of 720.<section end="imageres description" />

<syntaxhighlight lang=xml enclose="div">
<imageres>720</imageres>
</syntaxhighlight>

=== fanartres ===
{{anchor|.3Cfanartres.3E}}

<section begin="fanartres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached fanart]] should be resized to in pixels. The width is automatically calculated as being 16/9*height. Only images that are exactly 16x9 and equal to or greater than this resolution will be cached at this size - all other images will be cached using <imageres>. The default value is 1080.<section end="fanartres description" />

<syntaxhighlight lang=xml enclose="div">
<fanartres>1080</fanartres>
</syntaxhighlight>

=== imagescalingalgorithm ===
Specify the image scaling algorithm for image resizing when [[Artwork/Cache#Texture optimization| caching artwork]] to the local texture cache.
<br />
<syntaxhighlight lang=xml enclose="div">
<imagescalingalgorithm>bicubic</imagescalingalgorithm>
</syntaxhighlight>

[https://github.com/xbmc/xbmc/blob/1a8753d5cd93890dc6a9f9d4b2ce8848066ea5d0/xbmc/pictures/PictureScalingAlgorithm.cpp#L32-L43 Available image scaling algorithms]

<syntaxhighlight lang=text enclose="div">
fast_bilinear
bilinear
bicubic
experimental
nearest_neighbor
averaging_area
bicublin
gaussian
sinc
lanczos
bicubic_spline
</syntaxhighlight>

=== imagequalityjpeg ===
This specifies the quality of the images when stored in jpeg format. By default kodi uses a quality of 4 which is a good compromise between size and quality. If you want to reduce the thumbnail sizes (decreasing quality) choose a higher value up to 21. If high quality (large thumbnail size) is needed, chose a smaller value, e.g. 0,1,2 or 3. (Added in v20 <ref>https://github.com/xbmc/xbmc/pull/21418</ref>)
<br />
<syntaxhighlight lang=xml enclose="div">
<imagequalityjpeg>4</imagequalityjpeg>
</syntaxhighlight>

== Video and music library settings ==

=== playlistasfolders ===
{{anchor|.3Cplaylistasfolders.3E}}
In the recent releases, playlists are treated as folders. Selecting a playlist no longer plays it, but opens it, as if it were a folder.

Set to false to revert to the previous behaviour. When you select a playlist, its content is added to the list of elements to be played.

:{{note|This setting will not affect smart playlists, they will always show as folders.}}

;Example
<syntaxhighlight lang=xml enclose="div">
<playlistasfolders>true</playlistasfolders>
</syntaxhighlight>

=== playlistretries ===
{{anchor|.3Cplaylistretries.3E}}
The number of retries attempted if a source is offline. With this control you can alter the number of consecutive failed items before a playlist fails.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlistretries>100</playlistretries>
</syntaxhighlight>

=== playlisttimeout ===
{{anchor|.3Cplaylisttimeout.3E}}
The timeout, in seconds, before item failure.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlisttimeout>20</playlisttimeout>
</syntaxhighlight>

=== sorttokens ===
Allows you to specify additional tokens that will be ignored at the start of lines during sorting.
{{note|Sort tokens are case sensitive.}}
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token>the</token>
</sorttokens>
</syntaxhighlight>

In the above example "the ", "the." and "the_" will be ignored at the start of titles or names when sorting items, in both video and music libraries. A separator can also be specified, for example
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token separators="'">L</token>
</sorttokens>
</syntaxhighlight>
In that case the value L', as in French movie name ''L'argent'', will be ignored and the item listed under "A".

=== musicdatabase/videodatabase ===
{{anchor|.3Cmusicdatabase.3E/.3Cvideodatabase.3E|musicdatabase/videodatabase|database tags music/video/tv/epg/adsp}}
{{main|MySQL}}
<section begin="videodatabase" />
Allows advanced customization of the default database settings for music, video, TV, EPG, and ADSP databases.

:{{note| '''It is HIGHLY recommended that you not attempt to place an sqlite3 database outside of kodi's path. sqlite3 contains no filesystem abstraction, so this will plain break on any non-local (as far as Kodi is concerned) paths. Use this for mysql only.'''}}

'''Parent tags:'''

* '''<videodatabase>'''
* '''<musicdatabase>'''
* '''<tvdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<epgdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<adspdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
{{MySQL warning}}

'''Child tags: '''

;<type>
: ''Required'' - Can be either "sqlite3" or "mysql" (default: sqlite3)

;<host>
:''Required'' -
* sqlite3: defines the relative path to the database file (eg. /usr/local/kodi/databases).
* mysql: defines the host of the mysql socket (eg. localhost, 192.168.0.1, etc)

;<port>
: ''Optional'' -
* sqlite3: silently ignored
* mysql: defines the port of the mysql socket (default: 3306)

;<name>
: ''Optional'' -
:by default "MyVideos"+DB number will be used.
* sqlite3: defines the name of the database file to read from, excluding the ".db" extension.
* mysql: defines the name of the database to use

;<user>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the user with privileged access to the database

;<pass>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the password for the user with privileged access to the database

;<compression>
: ''Optional'' - Defaults to false. Set to "true" to enable MySQL compression protocol. Performance benefit is going to be largely dependent on the network bandwidth, latency between database and clients and on the size of the result sets. [https://github.com/xbmc/xbmc/pull/6484]
: {{Note|Slower clients (such as the RPi and others) won't benefit from it as the zlib de-compression overhead is higher than the actual compression savings}}

;<key>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<cert>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ca>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<capath>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ciphers>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

'''Examples:'''

1) Configure a database for MySQL.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<videodatabase>
<type>mysql</type>
<host>192.168.0.10</host>
<name>kodi_video</name>
<user>kodi</user>
<pass>kodi</pass>
</videodatabase>
</syntaxhighlight>

2) Configure a database for an sqlite database.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<musicdatabase>
<type>sqlite3</type>
<host>/usr/local/share/kodi/databases</host>
</musicdatabase>
</syntaxhighlight>

<section end="videodatabase" />

=== externalplayer ===
{{anchor|.3Cexternalplayer.3E}}
{{see|External players}}

== Music settings ==

=== musicextensions ===
{{anchor|.3Cmusicextensions.3E}}
<section begin="musicextensions" />
Default extensions for MUSIC:
<pre>
.nsv .m4a .flac .aac .strm .pls .rm .rma .mpa .wav .wma .ogg .mp3 .mp2 .m3u .gdm .imf .m15 .sfx
.uni .ac3 .dts .cue .aif .aiff .wpl .xspf .ape .mac .mpc .mp+ .mpp .shn .zip .wv .dsp .xsp .xwav
.waa .wvs .wam .gcm .idsp .mpdsp .mss .spt .rsd .sap .cmc .cmr .dmc .mpt .mpd .rmt .tmc .tm8
.tm2 .oga .url .pxml .tta .rss .wtv .mka .tak .opus .dff .dsf .m4b .dtshd
</pre>

It is possible to add or remove extensions for Music, using the following XML tags. Useful if you keep, say, FLAC and mp3 versions of music in the same folder. The <remove> tag can be used to remove mp3 from being listed in the library, leaving only the higher quality FLAC being displayed.

<musicextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</musicextensions>

<section end="musicextensions" />

=== cddbaddress ===
{{anchor|.3Ccddbaddress.3E}}
The address of the online CDDb database. You may set this to another freedb mirror if there is a more suitable one.

Default:
<syntaxhighlight lang=xml enclose="div>
<cddbaddress>freedb.freedb.org</cddbaddress>
</syntaxhighlight>

=== songinfoduration ===
{{anchor|.3Csonginfoduration.3E}}
This controls how long the song information will remain onscreen when the song changes during visualisations. The valid range is "1" to "Indefinite (0)", in seconds. This does not include the duration of any transition effects.

Default:
<syntaxhighlight lang=xml enclose="div">
<songinfoduration>10</songinfoduration>
</syntaxhighlight>

=== musicfilenamefilters ===
{{anchor|.3Cmusicfilenamefilters.3E}}
Contains filters to match music information (artist, title etc.) from a tag-less music filename. The first <filter> to match completely is used. Matched items include:

<pre>
%A - Artist
%T - Title
%B - Album
%N - Track number
%S - Part of set (disk number)
%D - Duration
%G - Genre
%Y - Year
%R - Rating
</pre>

Example:
<syntaxhighlight lang=xml enclose="div">
<musicfilenamefilters>
<filter>%A - %T</filter>
</musicfilenamefilters>
</syntaxhighlight>

=== musiclibrary ===
Options specific to the Music Library
<section begin="MusicLibrary" />
<syntaxhighlight lang="xml" line='line'>
<musiclibrary>
<allitemsonbottom>true</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<recentlyaddeditems>35</recentlyaddeditems> 
<albumformat>%B - %Y</albumformat> 
<prioritiseapetags>true</prioritiseapetags> 
<itemseparator> / </itemseparator> 
<artistseparators> 
<separator>;</separator>
<separator>:</separator>
<separator>|</separator>
<separator> feat. </separator>
<separator> ft. </separator>
</artistseparators>
<dateadded>1</dateadded> 


<useisodates>false</useisodates> 
</musiclibrary>
</syntaxhighlight>
{{Note|Changing the <itemseparator> or <artistseparators> will only affect newly added items. A rescan won't change the existing ones. Remove the Source(s) or delete the Music DB and rebuild. This process should be made easier from v18 and up using <promptfulltagscan>}}<section end="MusicLibrary" />

== Photos settings ==

=== pictureextensions ===
{{anchor|.3Cpictureextensions.3E}}
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Pictures window.

Default extensions for PICTURES:
<pre>
.png .jpg .jpeg .bmp .gif .ico .tif .tiff .tga .pcx .cbz .zip .rss .webp .jp2 .apng
</pre>

Examples:
<syntaxhighlight lang=xml enclose="div">
<pictureextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</pictureextensions>
</syntaxhighlight>

=== pictureexcludes ===
{{anchor|.3Cpictureexcludes.3E}}
Matches filenames or folders which should be excluded from being displayed in My Pictures using a list of Regular Expressions

<syntaxhighlight lang=xml enclose="div">
<pictureexcludes> 
<regexp>small</regexp>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</pictureexcludes>
</syntaxhighlight>

=== slideshow ===
{{anchor|.3Cslideshow.3E}}
<syntaxhighlight lang=xml enclose="div">
<slideshow>

<panamount>2.5</panamount>

<zoomamount>5.0</zoomamount>



<blackbarcompensation>20</blackbarcompensation>
</slideshow>
</syntaxhighlight>

== Network settings ==

=== ftp ===
{{anchor|.3Cftp.3DE}}
Specific settings if a ftp server is in use as a source

<syntaxhighlight lang=xml enclose="div">
<ftp>
<remotethumbs>true</remotethumbs> 
</ftp>
</syntaxhighlight>

=== samba ===
{{anchor|.3Csamba.3E}}
<syntaxhighlight lang=xml enclose="div">
<samba>
<doscodepage></doscodepage> 
<clienttimeout>10</clienttimeout> 
<statfiles>true</statfiles> 
</samba>
</syntaxhighlight>

=== hosts ===
{{anchor|.3Cfhosts.3E}}
Static dns entries which take precedence over your dns server.
<syntaxhighlight lang=xml enclose="div">
<hosts>
<entry name="HOSTNAME">IPADDRESS</entry>
</hosts>
</syntaxhighlight>

=== network ===
{{anchor|.3Cnetwork.3E}}

<syntaxhighlight lang=xml line='line'>
<network>
<curlclienttimeout>10</curlclienttimeout> 
<curllowspeedtime>20</curllowspeedtime> 
<curlretries>2</curlretries> 
<httpproxyusername></httpproxyusername> 
<httpproxypassword></httpproxypassword> 
<disableipv6>false</disableipv6> 
<disablehttp2>false</disablehttp2> 
<nfstimeout>30</nfstimeout> 
<catrustfile>filepath</catrustfile> 
<curlkeepaliveinterval>30</curlkeepaliveinterval> 
</network>
</syntaxhighlight>

{{Note|In Kodi v17, the three buffer settings are removed from the <code><network></code> tag and now placed under the new <code><cache></code> tag. See '''[[#cache]]''' for full details.}}

<curlkeepaliveinterval><ref>https://github.com/xbmc/xbmc/pull/19319</ref>

=== cache ===
{{see also|HOW-TO:Modify_the_video_cache}}
<syntaxhighlight lang=xml enclose="div">
<cache>
<memorysize>0</memorysize> 
<buffermode>0</buffermode> 
<readfactor>4.0</readfactor> 
</cache>
</syntaxhighlight>

=== airtunesport ===
{{anchor|.3Cairtunesport.3E}}<section begin="airtunesport" />
This overwrites the defalt listening port of the AirTunes server (announced via zeroconf).
<section end="airtunesport" />

=== airplayport ===
{{anchor|.3Cairplayport.3E}}<section begin="airplayport" />
This overwrites the default listening port of the AirPlay server (announced via zeroconf).
<section end="airplayport" />

== File system settings ==

=== packagefoldersize ===
<section begin="packagefoldersize" />
{{anchor|.3Cpackagefoldersize.3E}}
{{xml setting
| tag name = packagefoldersize
| option type = numerical
| option values =
| default values = 200
| platform = all
| XBMC version = 12
| description = The amount (in megabytes) of add-on zip packages saved from previous add-on installs. These packages are mainly used for the [[Add-ons|add-on]] rollback feature. Increasing the size should increase the amount of past versions saved. Defaults to 200 MB.
| example = Example: <syntaxhighlight lang=xml enclose="div"><packagefoldersize>200</packagefoldersize> </syntaxhighlight>
}}
<section end="packagefoldersize" />

=== detectasudf ===
{{anchor|.3Cdetectasudf.3E}}
Set to true if you wish to detect joint ISO9660/UDF disks as UDF.

Default: False

=== handlemounting ===
{{anchor|.3Chandlemounting.3E}}
Only used in Linux, it defines if Kodi should attempt to mount media drives (via udisks or udisks2).

Default: False. If kodi is executed with the --standalone option (e.g. as done by kodi-standalone.sh) it by default will be True.

=== pathsubstitution ===
{{anchor|.3Cpathsubstitution.3E}}
{{main|Path substitution}}

{{divbox|red||'''Note:''' Path substition for "sources" and profiles is broken, and will '''NOT''' be fixed.}}

Path substitutions are for use for redirecting file paths. These are processed in order, and are useful for substituting an absolute path on a PC with a path suitable for Kodi to handle.

Default: No path substitutions defined.

Example:
<syntaxhighlight lang=xml enclose="div">
<pathsubstitution>
<substitute>
<from>G:\dvds\</from>
<to>smb://somecomputer/g-share/dvds/</to> 
</substitute>
</pathsubstitution>
</syntaxhighlight>

== Input control settings ==

=== remotedelay ===
{{anchor|.3Cremotedelay.3E}}
The repeat delay for a LIRC remote control. A delay value between 1 and 20 before a remote button starts repeating on a long keypress (i.e. continuously sending button pushes while it's held down).

Default: 3
<syntaxhighlight lang=xml enclose="div">
<remotedelay>10</remotedelay>
</syntaxhighlight>

=== controllerdeadzone ===
{{anchor|.3Ccontrollerdeadzone.3E}}
This advanced settings has been removed.
Since v17, the [[Advancedsettings.xml#controllerdeadzone|<controllerdeadzone>]] advanced setting has been removed. Deadzones can now be configured by plugging in the controller and selecting it in Settings -> System settings -> Input -> Peripherals.

=== enablemultimediakeys ===
{{anchor|.3Cenablemultimediakeys.3E}}
This setting only has any effect on Windows versions of Kodi, and only applies to builds from 28th May 2011 onwards.
In Windows the multimedia keys generate a WM_APPCOMMAND message in addition the keypress. Kodi processes both keypresses and the WM_APPCOMMAND messages, and the end result would be that the command is executed twice. To avoid this, by default multimedia keypresses are disabled. Although it should rarely be necessary, the enablemultimediakeys setting allows you to enable the multimedia keys.

Example:
<syntaxhighlight lang=xml enclose="div">
<enablemultimediakeys>true</enablemultimediakeys>
</syntaxhighlight>

=== seeksteps ===
{{Main|Skip steps}}

This setting changes which increments are available in the settings GUI for additive seeking. Note that <code><seeksteps></code> is not used to actually choose which seek steps are enabled.

'''Default:'''
<syntaxhighlight lang=xml enclose="div">
<seeksteps>7, 15, 30, 60, 180, 300, 600, 900, 1800</seeksteps>
</syntaxhighlight>

{{editor note|the defaults need to be updated for seeksteps.}}

=== touchscreen ===
{{anchor|.3Ctouchscreen.3E}}
This setting allows you to move/align the origin of the touch screen with the origin of the display used. If touch input does not result in a correct movement of the mouse pointer, the behaviour can be corrected with an offset and a stretch/compress factor.

Example:
<syntaxhighlight lang=xml enclose="div">
<touchscreen>
<x_offset>0</x_offset> 
<y_offset>0</y_offset> 
<x_stretch_factor>1.0</x_stretch_factor> 
<y_stretch_factor>1.0</y_stretch_factor> 
</touchscreen>
</syntaxhighlight>

=== scanirserver ===
Introduced in v18 and used in MS Windows setups only.<ref>https://github.com/xbmc/xbmc/pull/13896</ref>
Used to disable the regular connection attempts to the IR Server Suite when there is no remote to connect to.

The default setting is to allow connection attempts. To disable connection attempts change value to '''false'''.
<syntaxhighlight lang=xml enclose="div">
<scanirserver>true</scanirserver>
</syntaxhighlight>

== Other interface settings ==

=== window ===
{{anchor|.3Cwindow.3E}}
{{note|This is a "hidden" guisettings.xml setting (defined by the mouse moving the window size), but it is mentioned here because it is a particularly useful override when used in advancedsettings.xml}}
This allows you to manually set the default size of Kodi's windowed mode. If you resize the window, it will return to the set size when restarting.

WIDTH and HEIGHT are the values for each dimension, in pixels.

<syntaxhighlight lang=xml enclose="div">
<window>
<width>WIDTH</width>
<height>HEIGHT</height>
</window>
</syntaxhighlight>

=== restrictcapsmask ===
{{anchor|.3Crestrictcapsmask.3E}}
Windows only. A bitmask to prevent Kodi from using detected texture capabilities of the GPU. This helps work around buggy hardware/drivers.

1: prevent the use of compressed textures (DXT1, DXT3, DXT5)
2: prevent the use of non-power-of-two dimensions for textures
4: prevent the use of compressed textures with non-power-of-two dimensions.

<syntaxhighlight lang=xml enclose="div">
<restrictcapsmask>0</restrictcapsmask>
</syntaxhighlight>

=== algorithmdirtyregions ===
{{anchor|.3Calgorithmdirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="algorithmdirtyregions" />{{note|Some GPU/hardware configurations will have some minor issues (such as a visual "flicker"). For those situations try mode 2 or use the default (mode 3, which requires no advancedsetting). Almost all ARM-based devices (such as [[Android]]) willl likely have flickering issues.}}

Enable dirty-region processing. Dirty regions are any parts of the screen that have changed since the last frame. By not re-rendering what hasn't changed the GUI can be sped up. Because all GPUs work differently, only Mode 3 is guaranteed to work for everyone without flickering issues. This mode will reduce CPU/GPU usage, but will not increase GUI speed.

{| class="prettytable"
! value !! result !! description
|-
! 0
| Off
| The entire viewport is always rendered.
|-
! 1
|Union
|All dirty regions are grouped into the smallest possible rectangle. This is typically the fastest mode for slower GPUs due to only making one pass.
|-
! 2
| {{nowrap|Cost reduction}}
| Each dirty region is presented separately, in as many passes as there are regions.
|-
! 3
| {{nowrap|Whole Screen}}
| The entire screen is rendered if there are any dirty regions. This is a safe default for drivers that clear buffer contents (manifests as blinking or vibrating images). '''Default'''
|}<section end="algorithmdirtyregions" />

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<algorithmdirtyregions>1</algorithmdirtyregions>
</gui>
</syntaxhighlight>

=== visualizedirtyregions ===
{{anchor|.3Cvisualizedirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="visualizedirtyregions" />Enable dirty-region visualization. Paints a rectangle over marked controls.

* true: on
* false: off '''(Default)'''

{{note|This is only a development mode and isn't of use to normal users.}}
<section end="visualizedirtyregions" />
Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<visualizedirtyregions>true</visualizedirtyregions>
</gui>
</syntaxhighlight>

=== smartredraw ===

{{note|This is an experimental feature and you might face issues using it. So please be aware of that.}}

This new feature was introduced in Kodi 18 and if enabled, the GUI process call (and therefore the render call) is only done if anything has changed. The result will be a faster GUI and less load if Kodi plays a video

* true: on
* false: off '''(Default)'''

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<smartredraw>true</smartredraw>
</gui>
</syntaxhighlight>

=== showexitbutton ===
{{anchor|.3Cshowexitbutton.3E}}
Setting to hide the exit button, useful for people running appliance based setups where exit would only confuse/complicate the user. Modifiable via the advancedsettings.xml by setting showexitbutton to false, default is true (show)

Example:
<syntaxhighlight lang=xml enclose="div">
<showexitbutton>true</showexitbutton>
</syntaxhighlight>

=== fullscreen ===
{{anchor|.3Cfullscreen.3E}}
Starts Kodi in full screen (check resolutions!).

<syntaxhighlight lang=xml enclose="div">
<fullscreen>false</fullscreen>
</syntaxhighlight>

=== splash ===
{{anchor|.3Csplash.3E}}
Set to false if you wish to disable the startup splash image. Defaults to true.

<syntaxhighlight lang=xml enclose="div">
<splash>true</splash>
</syntaxhighlight>

=== cputempcommand ===
{{anchor|.3Ccputempcommand.3E}}
Provide a shell command Kodi will use to get CPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia and Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sed -e 's/$[0-9]*$[0-9]\{3\}.*/\1 C/' /sys/class/thermal/thermal_zone0/temp</cputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>echo "$(sensors -u | tail -n64 | grep temp1_input | awk '{print $2 }' |awk '{printf("%d\n",$1 + 0.5);}') C"</cputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sensors|sed -ne "s/temp1: \+[-+]$[0-9]\+$.*/\1 C/p"</cputempcommand>
</syntaxhighlight>

=== gputempcommand ===
{{anchor|.3Cgputempcommand.3E}}
Provide a shell command Kodi will use to get GPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-settings -tq gpuCoreTemp) C"</gputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-smi -q -d TEMPERATURE | grep Gpu | cut -c35-36) C"</gputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/usr/bin/aticonfig --od-gettemperature | grep Temperature | cut -f 2 -d "-" | cut -f 1 -d "." | sed -e "s, ,," | sed 's/$/ C/'</gputempcommand>
</syntaxhighlight>

;<u>For Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/opt/vc/bin/vcgencmd measure_temp | sed -e "s/temp=//" -e "s/\..*'/ /"</gputempcommand>
</syntaxhighlight>

=== glrectanglehack ===
{{anchor|.3Cglrectanglehack.3E}}
Problems with ghosting or videos which are only played back in the left upper quarter? The following ATI hack may solve it.
<syntaxhighlight lang=xml enclose="div">
<glrectanglehack>yes</glrectanglehack>
</syntaxhighlight>

=== alwaysontop ===
{{anchor|.3Calwaysontop.3E}}
Added in XBMC v9.11 (Windows OS only). Keeps Kodi always on top when windowed.
<syntaxhighlight lang=xml enclose="div">
<alwaysontop>yes</alwaysontop>
</syntaxhighlight>

There is also a fake fullscreen GUI option in Kodi's settings.

=== minimizetotray ===
{{anchor|.3Cminimizetotray.3E}}
{{note|Available in Kodi v20 and above.}}

Windows only. Minimizes Kodi to the system tray. Defaults to false.
<syntaxhighlight lang=xml enclose="div">
<minimizetotray>true</minimizetotray>
</syntaxhighlight>

= Removed tags =
{{anchor|Recently removed tags}}
* {{anchor|.3Cthumbsize.3E}}'''<thumbsize>''' - replaced by <[[#imageres|imageres]]> in v12 Frodo
* {{anchor|.3Cfanartheight.3E}}'''<fanartheight>''' - replaced by <[[#fanartres|fanartres]]> in v12 Frodo
* {{anchor|.3Cdvdthumbs.3E}}'''<dvdthumbs>''' - removed in v12 Frodo
* {{anchor|.3Cbusydialogdelayms.3E}}'''<busydialogdelayms>''' - removed in v12 Frodo
* {{anchor|.3Cbginfoloadermaxthreads.3E}}'''<bginfoloadermaxthreads>''' - removed in v13 Gotham
* '''<showepginfoonselect>''' - replaced by a GUI setting in v13 Gotham
* '''<resample>''', '''<forceDirectSound>''', '''<audiophile>''', '''<audiosinkbufferdurationmsec>''', '''<allowtranscode44100>''', and '''<streamsilence>''' - These were various sub-tags for <audio> that were removed in v13 Gotham and either replaced by GUI settings or were no longer needed.
* {{anchor|.3Cenableairtunesdebuglog.3E}}'''<enableairtunesdebuglog>''' - replaced by a GUI option in v14 Helix
* '''<videoDisableHi10pMultithreading>''' - renamed to <disableswmultithreading> in v14 Helix
* '''<hideallitems>''' - For both the <code><videolibrary></code> and <code><musiclibrary></code> sections, this is replaced by a GUI option in v15 Isengard
* '''<SmallStepBackSeconds>''' - In v15 the <code>SmallStepBack</code> [[Action_IDs]] has been replaced by <code>seek(-7)</code> in default keymaps. See '''[[skip steps]]''' for details. When the original <code>SmallStepBack</code> action ID is used it defaults to the first backwards [[skip steps|additive seeking value]].
* '''<timeseekforward>/<timeseekbackward>''' - In v15 these tags are replaced by GUI options via [[skip steps|additive seeking]], which is configured in the GUI. See '''[[skip steps]]''' for details.
* {{anchor|.3Ckaraoke.3E}}'''<karaoke>''' - In v16 all of the karaoke features in Kodi were removed.
* '''<useddsfanart>''' - removed in v17 Krypton.
* '''<cachemembuffersize>''' and '''<readbufferfactor>''' - In v17 '''<cachemembuffersize>''' is renamed to '''<memorysize>''' and <code><readbufferfactor></code> is renamed to <code><readfactor></code>. In addition, all three buffer related settings in <network> are moved out of <network> and into a new <cache> parent tag.
* '''<minvideocachelevel>''', '''<minaudiocachelevel>''', and '''<cacheindvdplayer>''' have been removed in v17.
* '''<useffmpegvda>''' - Tag was only used for development testing. Removed in v17.
* '''<nofliptimeout>''' - Removed in v17
* '''<blackbarcolour>''' - Removed in v17 (maybe?)
* '''<disableswmultithreading>''' - Removed in v17 (maybe?)
* {{anchor|.3Cmeasurerefreshrate.3E}}'''<measurerefreshrate>''' - Removed in v17 or v18?
* {{anchor|.3Cmyth.3E}}'''<myth>''' - Removed sometime between v16 to v18
* {{anchor|.3Ctuxbox.3E}}'''<tuxbox>''' - Removed
* '''<backgroundupdate>''' - Removed
* '''<hideemptyseries>''' - Replaced by a GUI option.
* '''<mymovies>''' and child tag '''<categoriestogenres>''' - Removed
* '''<albumssortbyartistthenyear'''> - Removed
* '''<albumformatright>''' - Removed
* {{anchor|.3Cremoterepeat.3E}}'''<remoterepeat>''' - Removed
* {{anchor|.3Callowd3d9ex.3E}}'''<allowd3d9ex>''' and {{anchor|.3Cforced3d9ex.3E}}'''<forced3d9ex>''' - Removed sometime between v16 to v18
* '''<lingertime>''' - Replaced by a GUI setting in v18
* '''<forcevaapienabled>''' - Removed in v18
* '''<promptfulltagscan>false</promptfulltagscan>''' Removed in v18. Now automatically asked each time a scan is conducted.
* '''<controllerdeadzone>''' - Removed in v17
* '''<omxdecodestartwithvalidframe>''' - This tag is only in some Raspberry Pi specific distributions, such as OpenELEC. As of March 2015, this tag has not been merged into "vanilla" Kodi builds
* '''<musicthumbs>''' Replaced in v19 by the GUI setting '''Thumbnail image files''' found in Media -> Music
* '''<artistextraart>''' Replaced in v19 by the GUI setting '''Artist art types whitelist''' found in Media -> Music
* '''<albumextraart>''' Replaced in v19 by the GUI setting '''Album art types whitelist''' found in Media -> Music
* '''<fanart>''' Removed in v19
* '''<assfixedworks>''' Removed in v20
* '''<try10bitoutput>''' Removed in v20 and replaced with [[Settings/System/Display#Use_10_bit_for_SDR|Use 10 bit for SDR]] setting <ref>https://github.com/xbmc/xbmc/pull/20014</ref>

= guisettings.xml Setting Conversion =
It is possible to convert settings found in the '''[[Settings]]''' ''(guisettings.xml)'' pages of {{kodi}} into entries for the advancedsettings.xml file.

When a setting from the guisettings.xml is added to the advancedsettings.xml file, it will override the existing guisettings.xml values and the setting will be removed from the settings pages.

Why would I need to do this?
* You set up multiple devices and then need to individually change settings and preferences on each device. Using this conversion method, you save those settings in the advancedsettings.xml file and simply add the file to each device
* You need to hide settings to prevent those settings from being modified

To convert a guisetting to advancedsettings.xml follow these steps:
# In the {{kodi}} settings pages, adjust the setting(s) to your preference.
# Back out of the settings pages to the main menu, which forces {{kodi}} to save the adjusted settings to the guisettings.xml file
# Locate the guisettings.xml file in the [[Userdata]] folder and open it
# Locate the setting(s) to be converted. The list can be overwhelming so make use of the Search feature of whichever editor you are using
# Using the following setting as an example:
<syntaxhighlight lang="xml">
<setting id="videolibrary.showemptytvshows">true</setting>
</syntaxhighlight>
: Breaking down the string:
::'''videolibrary'''- parent tag
::'''showemptytvshows'''- child tag
::'''true'''- value
: The conversion is as follows and place this in the advancedsettings.xml file
<syntaxhighlight lang="xml">
<advancedsettings version="1.0">
<videolibrary>
<showemptytvshows>true</showemptytvshows>
</videolibrary>
</advancedsettings>
</syntaxhighlight>

'''Note:''' Some parent tags may already be in use in your advancedsettings.xml file. Do not duplicate them, but add the child tag beneath the existing parent tag.

= References =
<references />

{{Updated|18}}
{{DISPLAYTITLE:advancedsettings.xml}}

[[Category:Advanced topics]]
[[Category:Manual]]
[[Category:Settings]]

Advancedsettings.xml

2022-05-26T04:49:23Z

Fritsch: Rename towards imagequalityjpeg

{{TOC right}}{{mininav|[[Settings]]|page=advancedsettings.xml}}
{{bigger|{{note|'''The advancedsettings.xml file does not exist by default. You have to create it first!'''}} }}

<section begin="intro" />The [[advancedsettings.xml]] file, which does not exist by default, can be created by a user in their '''[[Userdata|userdata folder]]'''.

This file is used for advanced settings and options that do not have GUI controls inside of {{kodi}}. Some settings are experimental or very rarely set, so they can only be used via the advancedsettings.xml file. The file is simply a plain text file and can be edited by various text editors, so long as the name is "advancedsettings.xml". These advanced settings can be used to tweak various things such as episode naming patterns, special network ports, special behaviors, and more.<section end="intro" />

The following page will describe the structure of the advancedsettings.xml file and the various individual settings.

{{note|
# All XML tags must be lowercase. The start and end of the advancedsettings.xml file must have the <advancedsettings> and </advancedsettings> tags.
# Kodi will only read the advancedsettings.xml file when it starts up. If you make changes while it is running then you must restart Kodi.
# For some Windows versions, Kodi has two <code>\userdata\</code> folders. The correct one to put the advancedsettings.xml file in is not the one in Program Files, but in <code>%appdata%\Kodi\userdata\.</code>}}

== Layout ==

The layout of <code>advancedsettings.xml</code> is as follows:

<syntaxhighlight lang=xml enclose="div">
<advancedsettings version="1.0">
<setting>value</setting>
...
<setting>value</setting>
</advancedsettings>
</syntaxhighlight>

where "setting" gives the name of the setting, and "value" gives its value.

A list of the available "setting" strings and their values is given below.

= List of available settings =
List of available settings that are recognised in the advancedsettings.xml file <ref>https://github.com/xbmc/xbmc/blob/master/xbmc/settings/AdvancedSettings.cpp</ref>

Recommended: Use the table of contents or the search function in your browser to locate items.

== Troubleshooting settings ==

=== loglevel ===
{{Anchor|.3Cloglevel.3E}}

<section begin="loglevel" />
Sets the logging level used to log errors and information. The "hide" attribute is optional.

<syntaxhighlight lang=xml>
<loglevel hide="attribute">options</loglevel>
</syntaxhighlight>

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Attribute
! style="width:500px;" | Action
|-
! '''true'''
| Hides the "enable debugging" setting in the Settings page. (default)
|-
! '''false'''
| Allows "enable debugging" setting to switch between '''0''' and '''2'''.
|}

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Option
! style="width:500px;" | Action
|-
! '''-1'''
| No logging, suppresses all log output
|-
! '''0'''
| Normal logging, only logging errors (default)
|-
! '''1'''
| Debug logging with freemem, fps and cpu usage (no on screen)
|-
! '''2'''
| Same as 1 (with on screen display)
|-
! '''3'''
| Same as 2 + full smb logging (no on screen display)
|}

{| class="wikitable"
|-
! style="width:100px;" | Example
! style="width:500px;" |
|-
! Example 1:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings>
<loglevel>2</loglevel>
</advancedsettings>
</syntaxhighlight>
|-
! Example 2:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings>
<loglevel hide="true">2</loglevel>
</advancedsettings>
</syntaxhighlight>
|}

'''Note:''' The setting is persistent through shutdown and restarts.<br>
'''Note:''' If debugging is enabled in the GUI, loglevel will be set to '''2'''. This will over-ride the <code>advancedsettings.xml</code> setting. You must disable the GUI Setting before adding the entry to <code>advancedsettings.xml</code>.<br />
<section end="loglevel" />
:''{{see also|Log_file|label 1=Debug Log}}''

=== jsonrpc ===
{{Anchor|.3Cjsonrpc.3E}}
To make it easier for developers using the [[JSON-RPC_API]] API in their (third party) applications to debug during development the json output of Kodi can be prettified by setting '''compactoutput''' to '''false'''. Default json output mode is a compact print which does not contain any unnecessary whitespaces and therefore is difficult to read for humans.
Furthermore using the '''tcpport''' setting it is possible to change the default TCP port used by Kodi for JSON RPC (which is 9090) to any other valid port.

Example:
<syntaxhighlight lang=xml enclose="div">
<jsonrpc>
<compactoutput>false</compactoutput>
<tcpport>9999</tcpport>
</jsonrpc>
</syntaxhighlight>

== Audio/video playback settings ==

=== skiploopfilter ===
{{anchor|.3Cskiploopfilter.3E}}
The amount of the loop filter to skip on h.264 decoding. This can help the performance of slower machines when decoding h264 content. Values, in decreasing CPU usage (and decreasing quality)
* -16 None
* 0 Skip only empty frames (default)
* 8 Skip non-reference frames
* 16 Skip bi-dir frames
* 32 Skip all non-key frames
* 48 Skip all frames
Example:
<syntaxhighlight lang=xml enclose="div">
<skiploopfilter>8</skiploopfilter>
</syntaxhighlight>

=== video ===
{{anchor|.3Cvideo.3E}}

The <video> section also includes the following child-tags, which have their own sections:
*[[#cleandatetime]]
*[[#cleanstrings]]
*[[#excludefromscan]]
*[[#excludefromlisting]]
*[[#excludetvshowsfromscan]]

{{note|Some tags that have a "third-level" and are grouped together are highlighted in color.}}

{| class="prettytable"
! Tag !! Description
|-
|
<syntaxhighlight lang=xml>
<video>
</syntaxhighlight>
| Parent tag that all other child tags need to be placed inside of. Do not use more than one '''<code><video></code>''' tag, but instead place all other child-tags within a single '''<code><video></video></code>''' set.
|-
|
<syntaxhighlight lang=xml>
<subsdelayrange>10</subsdelayrange>
</syntaxhighlight>
| Delay range for subtitles, in seconds.
|-
|
<syntaxhighlight lang=xml>
<maxtempo>2.1</maxtempo>
</syntaxhighlight>
| Allow further increase of playback speed over the default of 1.5<br>
maxtempo must be in the range of 1.5 to 2.1 <br>
Be aware of the limitations of your platform / hardware as not all are capable of the increased maxtempo <ref>https://forum.kodi.tv/showthread.php?tid=10023&pid=2795069#pid2795069</ref>
|-
|
<syntaxhighlight lang=xml>
<audiodelayrange>10</audiodelayrange>
</syntaxhighlight>
| Delay range for audio/video sync, in seconds.
|-
|
<syntaxhighlight lang=xml>
<usetimeseeking>true</usetimeseeking>
</syntaxhighlight>
| Whether to use time based or percentage based seeking. {{small see also|Skip steps}}
|-
|
<syntaxhighlight lang=xml>
<timeseekforwardbig>600</timeseekforwardbig>
<timeseekbackwardbig>-600</timeseekbackwardbig>
</syntaxhighlight>
| Time to seek forward in seconds when doing a long seek. Defaults to 600 (10 minutes) and -600 (-10 minutes) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforward>2</percentseekforward>
<percentseekbackward>-2</percentseekbackward>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a short seek. Defaults to 2 (2%) and -2 (2%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforwardbig>10</percentseekforwardbig>
<percentseekbackwardbig>-10</percentseekbackwardbig>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a long seek. Defaults to 10 (10%) and -10 (10%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<fullscreenonmoviestart>true</fullscreenonmoviestart>
</syntaxhighlight>
| Whether to go to fullscreen or not when starting a movie. Defaults to true.
|-
|
<syntaxhighlight lang=xml>
<defaultplayer>VideoPlayer</defaultplayer>
</syntaxhighlight>
| Set the default video player: VideoPlayer or an external player. See '''[[External players]]''' for more info.
|-
|
<syntaxhighlight lang=xml>
<excludefromscan>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromscan>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be added to library. It is possible to add multiple <code><regexp></code> tags to match multiple patterns
|-
|
<syntaxhighlight lang=xml>
<excludefromlisting>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be displayed in files view.
|-
|
<syntaxhighlight lang=xml>
<playcountminimumpercent>90</playcountminimumpercent>
</syntaxhighlight>
| Minimum percentage that has to be played before it is marked as watched. Set to 101 to never auto-mark items as watched. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignoresecondsatstart>180</ignoresecondsatstart>
</syntaxhighlight>
| Number of seconds to ignore at video start after which a resume point is created. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignorepercentatend>8</ignorepercentatend>
</syntaxhighlight>
| Percentage of video to ignore at the end. If you stop watching the video here no resume point is created. Set to 101 to never save a resume point. The video is already marked as watched at 90%, see above. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<vdpauscaling>true</vdpauscaling>
</syntaxhighlight>
| Scales with vdpau instead of opengl and turns on its HQ scaler when available, enabling this might slow down rendering and cause framedrops especially on ION systems, this setting requires a vdpau feature set C GPU.
|-
|
<syntaxhighlight lang=xml>
<enablehighqualityhwscalers>true</enablehighqualityhwscalers>
</syntaxhighlight>
| Allow turning on the spline36 and lanczos3 shader (for GL builds).
|-
|
<syntaxhighlight lang=xml>
<dxvaallowhqscaling>false</dxvaallowhqscaling>
</syntaxhighlight>
| Enables high quality video upscaling for Windows.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegdeinterlacing>linblenddeint</ppffmpegdeinterlacing>
</syntaxhighlight>
| Override the deinterlacing options passed to libpostproc.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegpostprocessing>ha:128:7,va,dr</ppffmpegpostprocessing>
</syntaxhighlight>
| Override the post processing options passed to libpostproc when 'Video post-processing' is activated in GUI Videos-Settings-Playback.
|-
|
<syntaxhighlight lang=xml>
<autoscalemaxfps>30</autoscalemaxfps>
</syntaxhighlight>
| When scaling method is set to auto, bilinear is chosen when the fps is higher than this limit, the default is 30.
|-
|
<syntaxhighlight lang=xml>
<adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" | Settings for when "Adjust refreshrate to match video fps" is enabled in the video playback GUI settings.
|-
|
<syntaxhighlight lang=xml>
<override>
<fps>23.976</fps>
<refresh>60.0</refresh>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' "Adjust refreshrate to match video fps" will try to select the best refreshrate for the video fps but it doesn't always get it right, for example it might switch to an unsupported refreshrate. You can add overrides here to switch to a certain refreshrate based on video fps. It's possible to add as many overrides as you need. Overrides are processed in order, if the first one doesn't match the fps or no refreshrates match that override, it will try the next one until no overrides are left.

* '''fps''' - if the fps is between 23.966 and 23.986
* '''refresh''' - switch to the first found refreshrate that is between 59.99 and 60.01
|-
|
<syntaxhighlight lang=xml>
<override>
<fpsmin>29.96</fpsmin>
<fpsmax>30.01</fpsmax>
<refreshmin>59.0</refreshmin>
<refreshmax>61.0</refreshmax>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -'''
* '''fpsmin''' / '''fpsmin''' - You can also specify the fps range yourself.
* '''refreshmin''' / '''refreshmax''' - Same for the refreshrate
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refresh>50.0</refresh>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' If none of the overrides match, or none of the refreshrates match any of the fps matching overrides, it will choose a fallback refreshrate. Fallbacks are process in order, if the first fallback doesn't match any refreshrate, it will try the next one until no fallbacks are left.

* '''refresh''' - Switch to the first found refreshrate that is between 49.99 and 50.01.
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refreshmin>49.0</refreshmin>
<refreshmax>51.0</refreshmax>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' You can also specify the range for the fallback yourself.

If none of the overrides match the video fps, or no refreshrates match any of the fps matching overrides, and no fallbacks are specified or no refreshrates match any fallbacks, it will automatically choose the best refreshrate (same as having no overrides and fallbacks).
|-
|
<syntaxhighlight lang=xml>
</adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" |
|-
|
<syntaxhighlight lang=xml>
<checkdxvacompatibility>value</checkdxvacompatibility>
</syntaxhighlight>
| Advanced setting not present: let Kodi autodetect cards that support H.264 profile > L4.1. Set value to false to enable DXVA no matter what. Set value to true if Kodi doesn't autodetect that the graphics card doesn't support > L4.1.
|-
|
<syntaxhighlight lang=xml>
<useocclusionquery>-1</useocclusionquery>
</syntaxhighlight>
| Use an occlusion query when capturing videoframes, -1 means auto detect, 0 means disabled, 1 means enabled, the default is -1.
|-
|
<syntaxhighlight lang=xml>
<fpsdetect>1</fpsdetect>
</syntaxhighlight>
| FPS detection for video playback
* 0 = trust codec fps
* 1 = recalculate from video timestamps with uniform spacing
* 2 = recalculate from video timestamps always
|-
|
<syntaxhighlight lang=xml>
<latency>
</syntaxhighlight>
| style="background:#F0E68C;"| Start of '''latency''' tags. Display latency (video lag). Latency is given in msecs.
|-
|
<syntaxhighlight lang=xml>
<delay>0</delay>
</syntaxhighlight>
| style="background:#F0E68C;" | Global default display latency.
|-
|
<syntaxhighlight lang=xml>
<refresh></refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | Override latency for given display (not video) refresh rates. When Kodi is in windowed mode, override is ignored. Multiple overrides are allowed.

Syntax of an override entry:
<syntaxhighlight lang=xml>
<refresh>
<min>, <max> refresh rate range, OR
<rate> exact refresh rate
<delay> display latency for the given refresh rate
</refresh>
</syntaxhighlight>
|-
|
<syntaxhighlight lang=xml>
<refresh>
<min>23</min>
<max>24</max>
<delay>125</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 125 msec latency at 23-24 Hz
|-
|
<syntaxhighlight lang=xml>
<refresh>
<rate>50</rate>
<delay>50</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 50 msec latency at 50 (+/-0.01) Hz
|-
|
<syntaxhighlight lang=xml>
</latency>
</syntaxhighlight>
| style="background:#F0E68C;" |
|-
|
<syntaxhighlight lang=xml>
<stereoscopicregex3d>[-. _]3d[-. _]</stereoscopicregex3d>
<stereoscopicregexsbs>[-. _]h?sbs[-. _]</stereoscopicregexsbs>
<stereoscopicregextab>[-. _]h?tab[-. _]</stereoscopicregextab>
</syntaxhighlight>
| Filename triggers for 3D (stereoscopic) mode.
|-
|
<syntaxhighlight lang=xml>
<assfixedworks>false</assfixedworks>
</syntaxhighlight>
| Position behavior of ass subtitiles when setting "subtitle position on screen" set to "fixed". True to show at the fixed position set in video calibration. False to show at the bottom of video (default). {{note|Removed in Kodi v20.}}
|-
|
<syntaxhighlight lang=xml>
<subtitleverticalmargin>120</subtitleverticalmargin>
</syntaxhighlight>
| Allows to customise the vertical margin of text based subtitles, which will be applied to each type of subtitle position in subtitle settings. {{note|Available in Kodi v20 and above.}}
|-
|
<syntaxhighlight lang=xml>
</video>
</syntaxhighlight>
|
|}

=== audio ===
{{anchor|.3Caudio.3E}}
<syntaxhighlight lang=xml enclose="div">
<audio>

<headroom>0</headroom>

<defaultplayer>paplayer</defaultplayer>

<excludefromscan>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromscan>

<excludefromlisting>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromlisting>

<ac3downmixgain>12.0</ac3downmixgain>

<usetimeseeking>true</usetimeseeking>

<timeseekforwardbig>600</timeseekfowardbig>

<timeseekbackwardbig>-600</timeseekbackward>

<playcountminimumpercent>99</playcountminimumpercent>

<applydrc>-1.0</applydrc>

<limiterhold>0.025</limiterhold>

<limiterrelease>0.1</limiterrelease>
</audio>
</syntaxhighlight>

=== forcedswaptime ===
{{anchor|.3Cforcedswaptime.3E}}
Use to force a backbuffer->frontbuffer swap while vsync is enabled. Set to the time (in ms) to allow for the swap (e.g. <forcedswaptime>1</forcedswaptime> is typical).

Default: Off

=== edl ===
{{anchor|.3Cedl.3E}}
{{main|Edit_decision_list}}
Commercial break detection not as good you think it could be? Are some commercial breaks in a series of adverts not being skipped? Are some parts being skipped that are clearly not commercials? Does the end of the previous recording still show? The following advanced settings can be used to better identify full commercial break sequences, remove incorrectly flagged commercial breaks, and have playback start at the actual beginning of the recording.

<syntaxhighlight lang=xml enclose="div">
<edl>

<mergeshortcommbreaks>false</mergeshortcommbreaks>

<maxcommbreaklength>250</maxcommbreaklength>

<mincommbreaklength>90</mincommbreaklength>

<maxcommbreakgap>120</maxcommbreakgap>

<commbreakautowait>0</commbreakautowait>

<commbreakautowind>0</commbreakautowind>
</edl>
</syntaxhighlight>

== PVR & Live TV ==
{{anchor|.3Cpvr.3E}}
Settings available for PVR, EPG and Live TV. Edit Decision List settings are located in the previous section.

=== pvr ===
<syntaxhighlight lang="xml" line='line'>
<pvr>
<timecorrection>0</timecorrection> 
<infotoggleinterval>3000</infotoggleinterval> 
<channeliconsautoscan>true</channeliconsautoscan> 
<autoscaniconsuserset>false</autoscaniconsuserset> 
<numericchannelswitchtimeout>1000</numericchannelswitchtimeout> 
</pvr>
</syntaxhighlight>

==== pvrrecordings ====
In v19 and later, allows users to modify sort type and order of pvr recordings. <ref>https://github.com/xbmc/xbmc/pull/18605</ref>

;Note- These settings are child tags to the ''<pvr>'' tag in the previous section.

<syntaxhighlight lang="xml" line='line'>
<pvr>
<pvrrecordings>
<sortmethod>2</sortmethod> 
<sortorder>2</sortorder> 
</pvrrecordings>
</pvr>
</syntaxhighlight>

=== epg ===
{{anchor|.3Cpvr.3E}}
<syntaxhighlight lang="xml" line='line'>
<epg>
<updatecheckinterval>300</updatecheckinterval> 
<updateemptytagsinterval>60</updateemptytagsinterval> 
<cleanupinterval>900</cleanupinterval> 
<activetagcheckinterval>60</activetagcheckinterval> 
<retryinterruptedupdateinterval>60</retryinterruptedupdateinterval> 
<displayupdatepopup>true</displayupdatepopup> 
<displayincrementalupdatepopup>false</displayincrementalupdatepopup> 
</epg>
</syntaxhighlight>

== Video library settings ==

=== videoextensions ===
{{anchor|.3Cvideoextensions.3E}}<section begin="videoextensions" />
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Video windows.

Default extensions for VIDEOS:
<pre>
.m4v .3g2 .3gp .nsv .tp .ts .ty .strm .pls .rm .rmvb .mpd .m3u .m3u8 .ifo .mov .qt .divx .xvid
.bivx .vob .nrg .img .iso .udf .pva .wmv .asf .asx .ogm .m2v .avi .bin .dat .mpg .mpeg .mp4
.mkv .mk3d .avc .vp3 .svq3 .nuv .viv .dv .fli .flv .001 .wpl .xspf .zip .vdr .dvr-ms .xsp .mts
.m2t .m2ts .evo .ogv .sdp .avs .rec .url .pxml .vc1 .h264 .rcv .rss .mpls .mpl .webm .bdmv
.bdm .wtv .trp .f4v
</pre>
Examples:
<pre>
<videoextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</videoextensions>
</pre>
<section end="videoextensions" />

=== discstubextensions ===
{{main|Media stubs}}

<section begin="discstubextensions" />
The default filename extension for Disc Stubs is:
<syntaxhighlight lang=xml enclose="div">
.disc
</syntaxhighlight>
Using the following tags, it is possible to <tt><add></tt> additional or <tt><remove></tt> existing disc stub extensions to better suit your requirements.
<syntaxhighlight lang=xml enclose="div">
<discstubextensions>
<add>.disk|.stub</add>
<remove>.disc</remove>
</discstubextensions>
</syntaxhighlight>
<section end="discstubextensions" />

=== languagecodes ===
{{anchor|.3Clanguagecodes.3E}}
Translation table for subtitle and audio names. Contains entries of the form

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>alt</short>
<long>Alternate</long>
</code>
</languagecodes>
</syntaxhighlight>

=== moviestacking ===
{{anchor|.3Cmoviestacking.3E}}<section begin="moviestacking" />
{{main|Naming_video_files/Movies}}
This is used by the [[Naming_video_files/Movies#Split_Video_Files|file stacking]] algorithm to combine multi-part files and contains a list of "''[[RegEx_tutorial|regular expressions]]''". For stacking videos that are contained in folders, such as VIDEO_TS folders, see '''[[advancedsettings.xml#folderstacking|<folderstacking>]]'''

As of v9.11, video stacking regular expressions '''must''' contain exactly four (4) capture expressions.

Default:
<syntaxhighlight lang=xml enclose="div">
<moviestacking>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[0-9]+)(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[a-d])(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ ._-]*[a-d])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="append"</tt> or <tt>append="yes"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the end.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="append">

<regexp>(.*?)([ ._-]*[0-9])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="prepend"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the beginning.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="prepend">
<regexp>(Title)(Volume)(Ignore)(Extension)</regexp>
</moviestacking>
</syntaxhighlight>

If no argument is supplied, or the argument <tt>append="no"</tt> is supplied, the default moviestacking regular expressions are overwritten by the user specified ones.
<section end="moviestacking" />

=== folderstacking ===
{{main|Naming_video_files/Movies}}
This is similar to '''[[advancedsettings.xml#moviestacking|<moviestacking>]]''', but is used for videos that are contained in folders that use the folder names to stack, such as VIDEO_TS folders (DVD rips that are not in ISO format).

Default:
<syntaxhighlight lang=xml enclose="div">
<folderstacking>

<regexp>((cd|dvd|dis[ck])[0-9]+)$</regexp>
</folderstacking>
</syntaxhighlight>

=== cleandatetime ===
{{anchor|.3Ccleandatetime.3E}}
Matches a year number in a string using a ''[[RegEx_tutorial|Regular Expression]]''

Default expression:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleandatetime>(.*[^ _\,\.\[\]\-])[ _\.\[\]\-]+(19[0-9][0-9]|20[0-9][0-9])([ _\,\.\[\]\-]|[^0-9]$)?</cleandatetime>
</video>
</syntaxhighlight>
:* The string found before will be used as basis string getting cleaned by the cleanstrings expressions.
:* By default date formats like MM:YY are ignored.

=== cleanstrings ===
{{anchor|.3Ccleanstrings.3E}}
Clean unwanted characters from filenames or folders by using a list of ''[[RegEx_tutorial|Regular Expressions]]''. Please note that everything right of the match (at the end of the file name) is removed, so if you would have a file named ''Super movie.mp4'' and would add <tt><regexp> </regexp></tt> (only a space), the only thing that would be left is ''Super'', which is probably not what you want.

{{Github_link|[https://github.com/xbmc/xbmc/blob/Matrix/xbmc/settings/AdvancedSettings.cpp#L188 Code in Github]}}

Default expressions:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleanstrings>
<regexp>[ _\,\.\[\]\-](aka|ac3|dts|custom|dc|remastered|divx|divx5|dsr|dsrip|dutch|dvd|dvd5|dvd9|dvdrip|dvdscr|dvdscreener|screener|dvdivx|cam|fragment|fs|hdtv|hdrip|hdtvrip|internal|limited|multisubs|ntsc|ogg|ogm|pal|pdtv|proper|repack|rerip|retail|r3|r5|bd5|se|svcd|swedish|german|read.nfo|nfofix|unrated|extended|ws|telesync|ts|telecine|tc|brrip|bdrip|480p|480i|576p|576i|720p|720i|1080p|1080i|3d|hrhd|hrhdtv|hddvd|bluray|x264|h264|xvid|xvidvd|xxx|www.www|cd[1-9]|\[.*\])([ _\,\.\[\]\-]|$)</regexp>
<regexp>(\[.*\])</regexp>
</cleanstrings>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== tvshowmatching ===
{{anchor|.3Ctvshowmatching.3E}}
Matches the season and episode numbers in file paths by using a list of ''[[RegEx_tutorial|Regular Expressions]]''

{{Github_link|[https://github.com/xbmc/xbmc/blob/Matrix/xbmc/settings/AdvancedSettings.cpp#L232 Code in Github]}}

Defaults:
<syntaxhighlight lang=xml enclose="div">
<tvshowmatching>
<regexp>s([0-9]+)[ ._x-]*e([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)([^\\\\/]*)$</regexp> 
<regexp>[\._ -]()[Ee][Pp]_?([0-9]+)([^\\/]*)$</regexp> 
<regexp>([0-9]{4})[\.-]([0-9]{2})[\.-]([0-9]{2})</regexp> 
<regexp>([0-9]{2})[\.-]([0-9]{2})[\.-]([0-9]{4})</regexp> 
<regexp>[\\/\._ \[\(-]([0-9]+)x([0-9]+)([^\\/]*)$</regexp> 
<regexp>[\\/\._ -]([0-9]+)([0-9][0-9])([\._ -][^\\/]*)$</regexp> 
<regexp>[\/._ -]p(?:ar)?t[_. -]()([ivx]+)([._ -][^\/]*)$</regexp> 
</tvshowmatching>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)
:* Paths are converted to lower case before matching.
:* For multi-episode matching to work, there needs to be a third set of parentheses '()' at the end, this part is fed back into the regexp engine.
:* A [https://forum.kodi.tv/showthread.php?tid=51614 forum thread] has a discussion of pre-made regex lists to match common names. These might improve Kodi's ability to match TV show names in some situations, at the risk of additional false positives.

==== Filenames without Season ====
There are two methods to add episodes without a season in their file path. Both ways will force the season to '1' by default, so that you can use
the 'Use Absolute Ordering (Single Season)' setting from the TheTvDb.com scraper.

; Simple Method ''(XBMC v9.11 onwards and Kodi)''
: Use only one pair of parentheses
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]([0-9]+)</regexp></syntaxhighlight>
; Advanced Method ''(XBMC v10.05 onwards and Kodi)''
: Supports multi-episode files without season
: Use an empty pair of parentheses for the season
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

; Specifying Default Season ''(XBMC v12.0 onwards and Kodi)''
It is possible to set the default season for specific regular expressions by setting the 'defaultseason' attribute.
: Works with both the simple method and advanced method
: If not used, the season will be set to '1'
: Useful for setting specials to season '0'
<syntaxhighlight lang=xml enclose="div"><regexp defaultseason="0">[/\._ \-]X()([0-9]+)(-[0-9]+)?</regexp>
<regexp defaultseason="1">[/\._ \-]E()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

=== tvmultipartmatching ===
{{anchor|.3Ctvmultipartmatching.3E}}
Matches a multipart episode number based on a previously identified episode file, using a list of ''[[RegEx_tutorial|Regular Expressions]]''.

Default:
<syntaxhighlight lang=xml enclose="div">
<tvmultipartmatching>^[-_ex]+([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)</tvmultipartmatching>
</syntaxhighlight>
:* Text matching is compared case-insensitive.
:* Specifying this option '''replaces''' the default value

=== excludefromscan ===
{{anchor|.3Cexcludefromscan.3E}}
Matches filenames or folders which should be excluded from a library scan (except tvshows) using a list of ''[[RegEx_tutorial|Regular Expressions]]''. This can be for both Video or Audio sections of <tt>advancedsettings.xml</tt>.

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromscan>
<regexp>-trailer</regexp>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludefromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== excludefromlisting ===
{{anchor|.3Cexcludefromlisting.3E}}
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromlisting> 
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</video>
</syntaxhighlight>

=== excludetvshowsfromscan ===
{{anchor|.3Cexcludetvshowsfromscan.3E}}
Matches filenames or folders which should be excluded from a tvshow library scan using a list of ''[[RegEx_tutorial|Regular Expressions]]''

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludetvshowsfromscan>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludetvshowsfromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== trailermatching ===
{{anchor|.3Ctrailermatching.3E}}
Contains "''[[RegEx_tutorial|Regular Expression]]''" syntax (commonly referred to as "''[[RegEx_tutorial|RegEx]]''" or "''[[RegEx_tutorial|RegExp]]''") to match the locally stored trailers to movies in the library.

<syntaxhighlight lang=xml enclose="div">
<trailermatching>

<regexp>(.*?)(_Trailer)(\.[^.]+)$</regexp>
</trailermatching>
</syntaxhighlight>

=== videolibrary ===
{{anchor|.3Cvideolibrary.3E}}
Options specific to the Video Library

{{Note|Kodi v20 users don't need set "importwatched" or "importresumepoint" to true anymore as that's the default then <ref>https://github.com/xbmc/xbmc/pull/20842</ref>}}

<syntaxhighlight lang="xml" line='line'>
<videolibrary>
<allitemsonbottom>false</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<usefasthash>true</usefasthash> 
<recentlyaddeditems>35</recentlyaddeditems> 
<itemseparator> / </itemseparator> 
<exportautothumbs>false</exportautothumbs> 
<importwatchedstate>false</importwatchedstate> 
<importresumepoint>false</importresumepoint> 
<dateadded>1</dateadded> 
</videolibrary>
</syntaxhighlight>

==== Extra artwork ====

Applies to Kodi v18 only.

Configuration to expand the artwork automatically added by Kodi to media items in the library, either from local files or online scrapers.

The original basic artwork types are still hardcoded so they don't need to be configured here (and can't be removed). "poster" and "fanart" for movies, movie sets, TV shows, seasons, and music videos; "banner" for TV shows and seasons; and "thumb" for episodes.

<syntaxhighlight lang=xml enclose="div">
<videolibrary>


<tvshowextraart>
<arttype>characterart</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>landscape</arttype>
<arttype>keyart</arttype>
</tvshowextraart>

<tvseasonextraart>
<arttype>landscape</arttype>
</tvseasonextraart>

<episodeextraart>
<arttype>fanart</arttype>
</episodeextraart>

<movieextraart>
<arttype>banner</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>discart</arttype>
<arttype>landscape</arttype>
<arttype>keyart</arttype>
</movieextraart>

<moviesetextraart>
<arttype>banner</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>discart</arttype>
<arttype>landscape</arttype>
<arttype>keyart</arttype>
</moviesetextraart>

<musicvideoextraart>
<arttype>banner</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>discart</arttype>
<arttype>landscape</arttype>
</musicvideoextraart>
</videolibrary>
</syntaxhighlight>

=== videoscanner ===
{{anchor|.3Cvideoscanner.3E}}
Options specific to the Video scanner
<syntaxhighlight lang=xml enclose="div">
<videoscanner>
<ignoreerrors>true</ignoreerrors> 
</videoscanner>
</syntaxhighlight>

== Library artwork ==

{{note|Using <imageres>9999</imageres> and <fanartres>9999</fanartres> will allow caching artwork at original size.}}

=== imageres ===
{{anchor|.3Cimageres.3E}}

<section begin="imageres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached artwork]] (other than fanart / 16:9 images) should be resized to in pixels. The width is automatically calculated as being 16/9*height. The image will be resized to fit within this size. e.g. an image that is 2000x500 will be cached at size 1280x320. An image that is 500x800 will be cached at size 450x720 using the default value of 720.<section end="imageres description" />

<syntaxhighlight lang=xml enclose="div">
<imageres>720</imageres>
</syntaxhighlight>

=== fanartres ===
{{anchor|.3Cfanartres.3E}}

<section begin="fanartres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached fanart]] should be resized to in pixels. The width is automatically calculated as being 16/9*height. Only images that are exactly 16x9 and equal to or greater than this resolution will be cached at this size - all other images will be cached using <imageres>. The default value is 1080.<section end="fanartres description" />

<syntaxhighlight lang=xml enclose="div">
<fanartres>1080</fanartres>
</syntaxhighlight>

=== imagescalingalgorithm ===
Specify the image scaling algorithm for image resizing when [[Artwork/Cache#Texture optimization| caching artwork]] to the local texture cache.
<br />
<syntaxhighlight lang=xml enclose="div">
<imagescalingalgorithm>bicubic</imagescalingalgorithm>
</syntaxhighlight>

[https://github.com/xbmc/xbmc/blob/1a8753d5cd93890dc6a9f9d4b2ce8848066ea5d0/xbmc/pictures/PictureScalingAlgorithm.cpp#L32-L43 Available image scaling algorithms]

<syntaxhighlight lang=text enclose="div">
fast_bilinear
bilinear
bicubic
experimental
nearest_neighbor
averaging_area
bicublin
gaussian
sinc
lanczos
bicubic_spline
</syntaxhighlight>

=== imagequalityjpeg ===
This specifies the quality of the images when stored in jpeg format. By default kodi uses a quality of 4 which is a good compromise between size and quality. If you want to reduce the thumbnail sizes (decreasing quality) choose a higher value up to 21. If high quality (large thumbnail size) is needed, chose a smaller value, e.g. 0,1,2 or 3. (Added in v20 <ref>https://github.com/xbmc/xbmc/pull/21418</ref>)
<br />
<syntaxhighlight lang=xml enclose="div">
<imagequalityjpeg>4</imagequalityjpeg>
</syntaxhighlight>

== Video and music library settings ==

=== playlistasfolders ===
{{anchor|.3Cplaylistasfolders.3E}}
In the recent releases, playlists are treated as folders. Selecting a playlist no longer plays it, but opens it, as if it were a folder.

Set to false to revert to the previous behaviour. When you select a playlist, its content is added to the list of elements to be played.

:{{note|This setting will not affect smart playlists, they will always show as folders.}}

;Example
<syntaxhighlight lang=xml enclose="div">
<playlistasfolders>true</playlistasfolders>
</syntaxhighlight>

=== playlistretries ===
{{anchor|.3Cplaylistretries.3E}}
The number of retries attempted if a source is offline. With this control you can alter the number of consecutive failed items before a playlist fails.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlistretries>100</playlistretries>
</syntaxhighlight>

=== playlisttimeout ===
{{anchor|.3Cplaylisttimeout.3E}}
The timeout, in seconds, before item failure.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlisttimeout>20</playlisttimeout>
</syntaxhighlight>

=== sorttokens ===
Allows you to specify additional tokens that will be ignored at the start of lines during sorting.
{{note|Sort tokens are case sensitive.}}
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token>the</token>
</sorttokens>
</syntaxhighlight>

In the above example "the ", "the." and "the_" will be ignored at the start of titles or names when sorting items, in both video and music libraries. A separator can also be specified, for example
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token separators="'">L</token>
</sorttokens>
</syntaxhighlight>
In that case the value L', as in French movie name ''L'argent'', will be ignored and the item listed under "A".

=== musicdatabase/videodatabase ===
{{anchor|.3Cmusicdatabase.3E/.3Cvideodatabase.3E|musicdatabase/videodatabase|database tags music/video/tv/epg/adsp}}
{{main|MySQL}}
<section begin="videodatabase" />
Allows advanced customization of the default database settings for music, video, TV, EPG, and ADSP databases.

:{{note| '''It is HIGHLY recommended that you not attempt to place an sqlite3 database outside of kodi's path. sqlite3 contains no filesystem abstraction, so this will plain break on any non-local (as far as Kodi is concerned) paths. Use this for mysql only.'''}}

'''Parent tags:'''

* '''<videodatabase>'''
* '''<musicdatabase>'''
* '''<tvdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<epgdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<adspdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
{{MySQL warning}}

'''Child tags: '''

;<type>
: ''Required'' - Can be either "sqlite3" or "mysql" (default: sqlite3)

;<host>
:''Required'' -
* sqlite3: defines the relative path to the database file (eg. /usr/local/kodi/databases).
* mysql: defines the host of the mysql socket (eg. localhost, 192.168.0.1, etc)

;<port>
: ''Optional'' -
* sqlite3: silently ignored
* mysql: defines the port of the mysql socket (default: 3306)

;<name>
: ''Optional'' -
:by default "MyVideos"+DB number will be used.
* sqlite3: defines the name of the database file to read from, excluding the ".db" extension.
* mysql: defines the name of the database to use

;<user>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the user with privileged access to the database

;<pass>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the password for the user with privileged access to the database

;<compression>
: ''Optional'' - Defaults to false. Set to "true" to enable MySQL compression protocol. Performance benefit is going to be largely dependent on the network bandwidth, latency between database and clients and on the size of the result sets. [https://github.com/xbmc/xbmc/pull/6484]
: {{Note|Slower clients (such as the RPi and others) won't benefit from it as the zlib de-compression overhead is higher than the actual compression savings}}

;<key>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<cert>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ca>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<capath>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ciphers>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

'''Examples:'''

1) Configure a database for MySQL.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<videodatabase>
<type>mysql</type>
<host>192.168.0.10</host>
<name>kodi_video</name>
<user>kodi</user>
<pass>kodi</pass>
</videodatabase>
</syntaxhighlight>

2) Configure a database for an sqlite database.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<musicdatabase>
<type>sqlite3</type>
<host>/usr/local/share/kodi/databases</host>
</musicdatabase>
</syntaxhighlight>

<section end="videodatabase" />

=== externalplayer ===
{{anchor|.3Cexternalplayer.3E}}
{{see|External players}}

== Music settings ==

=== musicextensions ===
{{anchor|.3Cmusicextensions.3E}}
<section begin="musicextensions" />
Default extensions for MUSIC:
<pre>
.nsv .m4a .flac .aac .strm .pls .rm .rma .mpa .wav .wma .ogg .mp3 .mp2 .m3u .gdm .imf .m15 .sfx
.uni .ac3 .dts .cue .aif .aiff .wpl .xspf .ape .mac .mpc .mp+ .mpp .shn .zip .wv .dsp .xsp .xwav
.waa .wvs .wam .gcm .idsp .mpdsp .mss .spt .rsd .sap .cmc .cmr .dmc .mpt .mpd .rmt .tmc .tm8
.tm2 .oga .url .pxml .tta .rss .wtv .mka .tak .opus .dff .dsf .m4b .dtshd
</pre>

It is possible to add or remove extensions for Music, using the following XML tags. Useful if you keep, say, FLAC and mp3 versions of music in the same folder. The <remove> tag can be used to remove mp3 from being listed in the library, leaving only the higher quality FLAC being displayed.

<musicextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</musicextensions>

<section end="musicextensions" />

=== cddbaddress ===
{{anchor|.3Ccddbaddress.3E}}
The address of the online CDDb database. You may set this to another freedb mirror if there is a more suitable one.

Default:
<syntaxhighlight lang=xml enclose="div>
<cddbaddress>freedb.freedb.org</cddbaddress>
</syntaxhighlight>

=== songinfoduration ===
{{anchor|.3Csonginfoduration.3E}}
This controls how long the song information will remain onscreen when the song changes during visualisations. The valid range is "1" to "Indefinite (0)", in seconds. This does not include the duration of any transition effects.

Default:
<syntaxhighlight lang=xml enclose="div">
<songinfoduration>10</songinfoduration>
</syntaxhighlight>

=== musicfilenamefilters ===
{{anchor|.3Cmusicfilenamefilters.3E}}
Contains filters to match music information (artist, title etc.) from a tag-less music filename. The first <filter> to match completely is used. Matched items include:

<pre>
%A - Artist
%T - Title
%B - Album
%N - Track number
%S - Part of set (disk number)
%D - Duration
%G - Genre
%Y - Year
%R - Rating
</pre>

Example:
<syntaxhighlight lang=xml enclose="div">
<musicfilenamefilters>
<filter>%A - %T</filter>
</musicfilenamefilters>
</syntaxhighlight>

=== musiclibrary ===
Options specific to the Music Library
<section begin="MusicLibrary" />
<syntaxhighlight lang="xml" line='line'>
<musiclibrary>
<allitemsonbottom>true</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<recentlyaddeditems>35</recentlyaddeditems> 
<albumformat>%B - %Y</albumformat> 
<prioritiseapetags>true</prioritiseapetags> 
<itemseparator> / </itemseparator> 
<artistseparators> 
<separator>;</separator>
<separator>:</separator>
<separator>|</separator>
<separator> feat. </separator>
<separator> ft. </separator>
</artistseparators>
<dateadded>1</dateadded> 


<useisodates>false</useisodates> 
</musiclibrary>
</syntaxhighlight>
{{Note|Changing the <itemseparator> or <artistseparators> will only affect newly added items. A rescan won't change the existing ones. Remove the Source(s) or delete the Music DB and rebuild. This process should be made easier from v18 and up using <promptfulltagscan>}}<section end="MusicLibrary" />

== Photos settings ==

=== pictureextensions ===
{{anchor|.3Cpictureextensions.3E}}
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Pictures window.

Default extensions for PICTURES:
<pre>
.png .jpg .jpeg .bmp .gif .ico .tif .tiff .tga .pcx .cbz .zip .rss .webp .jp2 .apng
</pre>

Examples:
<syntaxhighlight lang=xml enclose="div">
<pictureextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</pictureextensions>
</syntaxhighlight>

=== pictureexcludes ===
{{anchor|.3Cpictureexcludes.3E}}
Matches filenames or folders which should be excluded from being displayed in My Pictures using a list of ''[[RegEx_tutorial|Regular Expressions]]''

<syntaxhighlight lang=xml enclose="div">
<pictureexcludes> 
<regexp>small</regexp>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</pictureexcludes>
</syntaxhighlight>

=== slideshow ===
{{anchor|.3Cslideshow.3E}}
<syntaxhighlight lang=xml enclose="div">
<slideshow>

<panamount>2.5</panamount>

<zoomamount>5.0</zoomamount>



<blackbarcompensation>20</blackbarcompensation>
</slideshow>
</syntaxhighlight>

== Network settings ==

=== ftp ===
{{anchor|.3Cftp.3DE}}
Specific settings if a ftp server is in use as a source

<syntaxhighlight lang=xml enclose="div">
<ftp>
<remotethumbs>true</remotethumbs> 
</ftp>
</syntaxhighlight>

=== samba ===
{{anchor|.3Csamba.3E}}
<syntaxhighlight lang=xml enclose="div">
<samba>
<doscodepage></doscodepage> 
<clienttimeout>10</clienttimeout> 
<statfiles>true</statfiles> 
</samba>
</syntaxhighlight>

=== hosts ===
{{anchor|.3Cfhosts.3E}}
Static dns entries which take precedence over your dns server.
<syntaxhighlight lang=xml enclose="div">
<hosts>
<entry name="HOSTNAME">IPADDRESS</entry>
</hosts>
</syntaxhighlight>

=== network ===
{{anchor|.3Cnetwork.3E}}

<syntaxhighlight lang=xml line='line'>
<network>
<curlclienttimeout>10</curlclienttimeout> 
<curllowspeedtime>20</curllowspeedtime> 
<curlretries>2</curlretries> 
<httpproxyusername></httpproxyusername> 
<httpproxypassword></httpproxypassword> 
<disableipv6>false</disableipv6> 
<disablehttp2>false</disablehttp2> 
<nfstimeout>30</nfstimeout> 
<catrustfile>filepath</catrustfile> 
<curlkeepaliveinterval>30</curlkeepaliveinterval> 
</network>
</syntaxhighlight>

{{Note|In Kodi v17, the three buffer settings are removed from the <code><network></code> tag and now placed under the new <code><cache></code> tag. See '''[[#cache]]''' for full details.}}

<curlkeepaliveinterval><ref>https://github.com/xbmc/xbmc/pull/19319</ref>

=== cache ===
{{see also|HOW-TO:Modify_the_video_cache}}
<syntaxhighlight lang=xml enclose="div">
<cache>
<memorysize>0</memorysize> 
<buffermode>0</buffermode> 
<readfactor>4.0</readfactor> 
</cache>
</syntaxhighlight>

=== airtunesport ===
{{anchor|.3Cairtunesport.3E}}<section begin="airtunesport" />
This overwrites the defalt listening port of the AirTunes server (announced via zeroconf).
<section end="airtunesport" />

=== airplayport ===
{{anchor|.3Cairplayport.3E}}<section begin="airplayport" />
This overwrites the default listening port of the AirPlay server (announced via zeroconf).
<section end="airplayport" />

== File system settings ==

=== packagefoldersize ===
<section begin="packagefoldersize" />
{{anchor|.3Cpackagefoldersize.3E}}
{{xml setting
| tag name = packagefoldersize
| option type = numerical
| option values =
| default values = 200
| platform = all
| XBMC version = 12
| description = The amount (in megabytes) of add-on zip packages saved from previous add-on installs. These packages are mainly used for the [[Add-ons|add-on]] rollback feature. Increasing the size should increase the amount of past versions saved. Defaults to 200 MB.
| example = Example: <syntaxhighlight lang=xml enclose="div"><packagefoldersize>200</packagefoldersize> </syntaxhighlight>
}}
<section end="packagefoldersize" />

=== detectasudf ===
{{anchor|.3Cdetectasudf.3E}}
Set to true if you wish to detect joint ISO9660/UDF disks as UDF.

Default: False

=== handlemounting ===
{{anchor|.3Chandlemounting.3E}}
Only used in Linux, it defines if Kodi should attempt to mount media drives (via udisks or udisks2).

Default: False. If kodi is executed with the --standalone option (e.g. as done by kodi-standalone.sh) it by default will be True.

=== pathsubstitution ===
{{anchor|.3Cpathsubstitution.3E}}
{{main|Path substitution}}

{{divbox|red||'''Note:''' Path substition for "sources" and profiles is broken, and will '''NOT''' be fixed.}}

Path substitutions are for use for redirecting file paths. These are processed in order, and are useful for substituting an absolute path on a PC with a path suitable for Kodi to handle.

Default: No path substitutions defined.

Example:
<syntaxhighlight lang=xml enclose="div">
<pathsubstitution>
<substitute>
<from>G:\dvds\</from>
<to>smb://somecomputer/g-share/dvds/</to> 
</substitute>
</pathsubstitution>
</syntaxhighlight>

== Input control settings ==

=== remotedelay ===
{{anchor|.3Cremotedelay.3E}}
The repeat delay for a LIRC remote control. A delay value between 1 and 20 before a remote button starts repeating on a long keypress (i.e. continuously sending button pushes while it's held down).

Default: 3
<syntaxhighlight lang=xml enclose="div">
<remotedelay>10</remotedelay>
</syntaxhighlight>

=== controllerdeadzone ===
{{anchor|.3Ccontrollerdeadzone.3E}}
This advanced settings has been removed.
Since v17, the [[Advancedsettings.xml#controllerdeadzone|<controllerdeadzone>]] advanced setting has been removed. Deadzones can now be configured by plugging in the controller and selecting it in Settings -> System settings -> Input -> Peripherals.

=== enablemultimediakeys ===
{{anchor|.3Cenablemultimediakeys.3E}}
This setting only has any effect on Windows versions of Kodi, and only applies to builds from 28th May 2011 onwards.
In Windows the multimedia keys generate a WM_APPCOMMAND message in addition the keypress. Kodi processes both keypresses and the WM_APPCOMMAND messages, and the end result would be that the command is executed twice. To avoid this, by default multimedia keypresses are disabled. Although it should rarely be necessary, the enablemultimediakeys setting allows you to enable the multimedia keys.

Example:
<syntaxhighlight lang=xml enclose="div">
<enablemultimediakeys>true</enablemultimediakeys>
</syntaxhighlight>

=== seeksteps ===
{{Main|Skip steps}}

This setting changes which increments are available in the settings GUI for additive seeking. Note that <code><seeksteps></code> is not used to actually choose which seek steps are enabled.

'''Default:'''
<syntaxhighlight lang=xml enclose="div">
<seeksteps>7, 15, 30, 60, 180, 300, 600, 900, 1800</seeksteps>
</syntaxhighlight>

{{editor note|the defaults need to be updated for seeksteps.}}

=== touchscreen ===
{{anchor|.3Ctouchscreen.3E}}
This setting allows you to move/align the origin of the touch screen with the origin of the display used. If touch input does not result in a correct movement of the mouse pointer, the behaviour can be corrected with an offset and a stretch/compress factor.

Example:
<syntaxhighlight lang=xml enclose="div">
<touchscreen>
<x_offset>0</x_offset> 
<y_offset>0</y_offset> 
<x_stretch_factor>1.0</x_stretch_factor> 
<y_stretch_factor>1.0</y_stretch_factor> 
</touchscreen>
</syntaxhighlight>

=== scanirserver ===
Introduced in v18 and used in MS Windows setups only.<ref>https://github.com/xbmc/xbmc/pull/13896</ref>
Used to disable the regular connection attempts to the IR Server Suite when there is no remote to connect to.

The default setting is to allow connection attempts. To disable connection attempts change value to '''false'''.
<syntaxhighlight lang=xml enclose="div">
<scanirserver>true</scanirserver>
</syntaxhighlight>

== Other interface settings ==

=== window ===
{{anchor|.3Cwindow.3E}}
{{note|This is a "hidden" guisettings.xml setting (defined by the mouse moving the window size), but it is mentioned here because it is a particularly useful override when used in advancedsettings.xml}}
This allows you to manually set the default size of Kodi's windowed mode. If you resize the window, it will return to the set size when restarting.

WIDTH and HEIGHT are the values for each dimension, in pixels.

<syntaxhighlight lang=xml enclose="div">
<window>
<width>WIDTH</width>
<height>HEIGHT</height>
</window>
</syntaxhighlight>

=== restrictcapsmask ===
{{anchor|.3Crestrictcapsmask.3E}}
Windows only. A bitmask to prevent Kodi from using detected texture capabilities of the GPU. This helps work around buggy hardware/drivers.

1: prevent the use of compressed textures (DXT1, DXT3, DXT5)
2: prevent the use of non-power-of-two dimensions for textures
4: prevent the use of compressed textures with non-power-of-two dimensions.

<syntaxhighlight lang=xml enclose="div">
<restrictcapsmask>0</restrictcapsmask>
</syntaxhighlight>

=== algorithmdirtyregions ===
{{anchor|.3Calgorithmdirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="algorithmdirtyregions" />{{note|Some GPU/hardware configurations will have some minor issues (such as a visual "flicker"). For those situations try mode 2 or use the default (mode 3, which requires no advancedsetting). Almost all ARM-based devices (such as [[Android]]) willl likely have flickering issues.}}

Enable dirty-region processing. Dirty regions are any parts of the screen that have changed since the last frame. By not re-rendering what hasn't changed the GUI can be sped up. Because all GPUs work differently, only Mode 3 is guaranteed to work for everyone without flickering issues. This mode will reduce CPU/GPU usage, but will not increase GUI speed.

{| class="prettytable"
! value !! result !! description
|-
! 0
| Off
| The entire viewport is always rendered.
|-
! 1
|Union
|All dirty regions are grouped into the smallest possible rectangle. This is typically the fastest mode for slower GPUs due to only making one pass.
|-
! 2
| {{nowrap|Cost reduction}}
| Each dirty region is presented separately, in as many passes as there are regions.
|-
! 3
| {{nowrap|Whole Screen}}
| The entire screen is rendered if there are any dirty regions. This is a safe default for drivers that clear buffer contents (manifests as blinking or vibrating images). '''Default'''
|}<section end="algorithmdirtyregions" />

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<algorithmdirtyregions>1</algorithmdirtyregions>
</gui>
</syntaxhighlight>

=== visualizedirtyregions ===
{{anchor|.3Cvisualizedirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="visualizedirtyregions" />Enable dirty-region visualization. Paints a rectangle over marked controls.

* true: on
* false: off '''(Default)'''

{{note|This is only a development mode and isn't of use to normal users.}}
<section end="visualizedirtyregions" />
Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<visualizedirtyregions>true</visualizedirtyregions>
</gui>
</syntaxhighlight>

=== smartredraw ===

{{note|This is an experimental feature and you might face issues using it. So please be aware of that.}}

This new feature was introduced in Kodi 18 and if enabled, the GUI process call (and therefore the render call) is only done if anything has changed. The result will be a faster GUI and less load if Kodi plays a video

* true: on
* false: off '''(Default)'''

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<smartredraw>true</smartredraw>
</gui>
</syntaxhighlight>

=== showexitbutton ===
{{anchor|.3Cshowexitbutton.3E}}
Setting to hide the exit button, useful for people running appliance based setups where exit would only confuse/complicate the user. Modifiable via the advancedsettings.xml by setting showexitbutton to false, default is true (show)

Example:
<syntaxhighlight lang=xml enclose="div">
<showexitbutton>true</showexitbutton>
</syntaxhighlight>

=== fullscreen ===
{{anchor|.3Cfullscreen.3E}}
Starts Kodi in full screen (check resolutions!).

<syntaxhighlight lang=xml enclose="div">
<fullscreen>false</fullscreen>
</syntaxhighlight>

=== splash ===
{{anchor|.3Csplash.3E}}
Set to false if you wish to disable the startup splash image. Defaults to true.

<syntaxhighlight lang=xml enclose="div">
<splash>true</splash>
</syntaxhighlight>

=== cputempcommand ===
{{anchor|.3Ccputempcommand.3E}}
Provide a shell command Kodi will use to get CPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia and Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sed -e 's/$[0-9]*$[0-9]\{3\}.*/\1 C/' /sys/class/thermal/thermal_zone0/temp</cputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>echo "$(sensors -u | tail -n64 | grep temp1_input | awk '{print $2 }' |awk '{printf("%d\n",$1 + 0.5);}') C"</cputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sensors|sed -ne "s/temp1: \+[-+]$[0-9]\+$.*/\1 C/p"</cputempcommand>
</syntaxhighlight>

=== gputempcommand ===
{{anchor|.3Cgputempcommand.3E}}
Provide a shell command Kodi will use to get GPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-settings -tq gpuCoreTemp) C"</gputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-smi -q -d TEMPERATURE | grep Gpu | cut -c35-36) C"</gputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/usr/bin/aticonfig --od-gettemperature | grep Temperature | cut -f 2 -d "-" | cut -f 1 -d "." | sed -e "s, ,," | sed 's/$/ C/'</gputempcommand>
</syntaxhighlight>

;<u>For Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/opt/vc/bin/vcgencmd measure_temp | sed -e "s/temp=//" -e "s/\..*'/ /"</gputempcommand>
</syntaxhighlight>

=== glrectanglehack ===
{{anchor|.3Cglrectanglehack.3E}}
Problems with ghosting or videos which are only played back in the left upper quarter? The following ATI hack may solve it.
<syntaxhighlight lang=xml enclose="div">
<glrectanglehack>yes</glrectanglehack>
</syntaxhighlight>

=== alwaysontop ===
{{anchor|.3Calwaysontop.3E}}
Added in XBMC v9.11 (Windows OS only). Keeps Kodi always on top when windowed.
<syntaxhighlight lang=xml enclose="div">
<alwaysontop>yes</alwaysontop>
</syntaxhighlight>

There is also a fake fullscreen GUI option in Kodi's settings.

=== minimizetotray ===
{{anchor|.3Cminimizetotray.3E}}
{{note|Available in Kodi v20 and above.}}

Windows only. Minimizes Kodi to the system tray. Defaults to false.
<syntaxhighlight lang=xml enclose="div">
<minimizetotray>true</minimizetotray>
</syntaxhighlight>

= Removed tags =
{{anchor|Recently removed tags}}
* {{anchor|.3Cthumbsize.3E}}'''<thumbsize>''' - replaced by <[[#imageres|imageres]]> in v12 Frodo
* {{anchor|.3Cfanartheight.3E}}'''<fanartheight>''' - replaced by <[[#fanartres|fanartres]]> in v12 Frodo
* {{anchor|.3Cdvdthumbs.3E}}'''<dvdthumbs>''' - removed in v12 Frodo
* {{anchor|.3Cbusydialogdelayms.3E}}'''<busydialogdelayms>''' - removed in v12 Frodo
* {{anchor|.3Cbginfoloadermaxthreads.3E}}'''<bginfoloadermaxthreads>''' - removed in v13 Gotham
* '''<showepginfoonselect>''' - replaced by a GUI setting in v13 Gotham
* '''<resample>''', '''<forceDirectSound>''', '''<audiophile>''', '''<audiosinkbufferdurationmsec>''', '''<allowtranscode44100>''', and '''<streamsilence>''' - These were various sub-tags for <audio> that were removed in v13 Gotham and either replaced by GUI settings or were no longer needed.
* {{anchor|.3Cenableairtunesdebuglog.3E}}'''<enableairtunesdebuglog>''' - replaced by a GUI option in v14 Helix
* '''<videoDisableHi10pMultithreading>''' - renamed to <disableswmultithreading> in v14 Helix
* '''<hideallitems>''' - For both the <code><videolibrary></code> and <code><musiclibrary></code> sections, this is replaced by a GUI option in v15 Isengard
* '''<SmallStepBackSeconds>''' - In v15 the <code>SmallStepBack</code> [[Action_IDs]] has been replaced by <code>seek(-7)</code> in default keymaps. See '''[[skip steps]]''' for details. When the original <code>SmallStepBack</code> action ID is used it defaults to the first backwards [[skip steps|additive seeking value]].
* '''<timeseekforward>/<timeseekbackward>''' - In v15 these tags are replaced by GUI options via [[skip steps|additive seeking]], which is configured in the GUI. See '''[[skip steps]]''' for details.
* {{anchor|.3Ckaraoke.3E}}'''<karaoke>''' - In v16 all of the karaoke features in Kodi were removed.
* '''<useddsfanart>''' - removed in v17 Krypton.
* '''<cachemembuffersize>''' and '''<readbufferfactor>''' - In v17 '''<cachemembuffersize>''' is renamed to '''<memorysize>''' and <code><readbufferfactor></code> is renamed to <code><readfactor></code>. In addition, all three buffer related settings in <network> are moved out of <network> and into a new <cache> parent tag.
* '''<minvideocachelevel>''', '''<minaudiocachelevel>''', and '''<cacheindvdplayer>''' have been removed in v17.
* '''<useffmpegvda>''' - Tag was only used for development testing. Removed in v17.
* '''<nofliptimeout>''' - Removed in v17
* '''<blackbarcolour>''' - Removed in v17 (maybe?)
* '''<disableswmultithreading>''' - Removed in v17 (maybe?)
* {{anchor|.3Cmeasurerefreshrate.3E}}'''<measurerefreshrate>''' - Removed in v17 or v18?
* {{anchor|.3Cmyth.3E}}'''<myth>''' - Removed sometime between v16 to v18
* {{anchor|.3Ctuxbox.3E}}'''<tuxbox>''' - Removed
* '''<backgroundupdate>''' - Removed
* '''<hideemptyseries>''' - Replaced by a GUI option.
* '''<mymovies>''' and child tag '''<categoriestogenres>''' - Removed
* '''<albumssortbyartistthenyear'''> - Removed
* '''<albumformatright>''' - Removed
* {{anchor|.3Cremoterepeat.3E}}'''<remoterepeat>''' - Removed
* {{anchor|.3Callowd3d9ex.3E}}'''<allowd3d9ex>''' and {{anchor|.3Cforced3d9ex.3E}}'''<forced3d9ex>''' - Removed sometime between v16 to v18
* '''<lingertime>''' - Replaced by a GUI setting in v18
* '''<forcevaapienabled>''' - Removed in v18
* '''<promptfulltagscan>false</promptfulltagscan>''' Removed in v18. Now automatically asked each time a scan is conducted.
* '''<controllerdeadzone>''' - Removed in v17
* '''<omxdecodestartwithvalidframe>''' - This tag is only in some Raspberry Pi specific distributions, such as OpenELEC. As of March 2015, this tag has not been merged into "vanilla" Kodi builds
* '''<musicthumbs>''' Replaced in v19 by the GUI setting '''Thumbnail image files''' found in Media -> Music
* '''<artistextraart>''' Replaced in v19 by the GUI setting '''Artist art types whitelist''' found in Media -> Music
* '''<albumextraart>''' Replaced in v19 by the GUI setting '''Album art types whitelist''' found in Media -> Music
* '''<fanart>''' Removed in v19
* '''<assfixedworks>''' Removed in v20

= guisettings.xml Setting Conversion =
It is possible to convert settings found in the '''[[Settings]]''' ''(guisettings.xml)'' pages of {{kodi}} into entries for the advancedsettings.xml file.

When a setting from the guisettings.xml is added to the advancedsettings.xml file, it will override the existing guisettings.xml values and the setting will be removed from the settings pages.

Why would I need to do this?
* You set up multiple devices and then need to individually change settings and preferences on each device. Using this conversion method, you save those settings in the advancedsettings.xml file and simply add the file to each device
* You need to hide settings to prevent those settings from being modified

To convert a guisetting to advancedsettings.xml follow these steps:
# In the {{kodi}} settings pages, adjust the setting(s) to your preference.
# Back out of the settings pages to the main menu, which forces {{kodi}} to save the adjusted settings to the guisettings.xml file
# Locate the guisettings.xml file in the [[Userdata]] folder and open it
# Locate the setting(s) to be converted. The list can be overwhelming so make use of the Search feature of whichever editor you are using
# Using the following setting as an example:
<syntaxhighlight lang="xml">
<setting id="videolibrary.showemptytvshows">true</setting>
</syntaxhighlight>
: Breaking down the string:
::'''videolibrary'''- parent tag
::'''showemptytvshows'''- child tag
::'''true'''- value
: The conversion is as follows and place this in the advancedsettings.xml file
<syntaxhighlight lang="xml">
<advancedsettings version="1.0">
<videolibrary>
<showemptytvshows>true</showemptytvshows>
</videolibrary>
</advancedsettings>
</syntaxhighlight>

'''Note:''' Some parent tags may already be in use in your advancedsettings.xml file. Do not duplicate them, but add the child tag beneath the existing parent tag.

= References =
<references />

{{Updated|18}}
{{DISPLAYTITLE:advancedsettings.xml}}

[[Category:Advanced topics]]
[[Category:Manual]]
[[Category:Settings]]

Advancedsettings.xml

2022-05-25T17:27:28Z

Fritsch: Add documentation for thumbqualityjpeg

{{TOC right}}{{mininav|[[Settings]]|page=advancedsettings.xml}}
{{bigger|{{note|'''The advancedsettings.xml file does not exist by default. You have to create it first!'''}} }}

<section begin="intro" />The [[advancedsettings.xml]] file, which does not exist by default, can be created by a user in their '''[[Userdata|userdata folder]]'''.

This file is used for advanced settings and options that do not have GUI controls inside of {{kodi}}. Some settings are experimental or very rarely set, so they can only be used via the advancedsettings.xml file. The file is simply a plain text file and can be edited by various text editors, so long as the name is "advancedsettings.xml". These advanced settings can be used to tweak various things such as episode naming patterns, special network ports, special behaviors, and more.<section end="intro" />

The following page will describe the structure of the advancedsettings.xml file and the various individual settings.

{{note|
# All XML tags must be lowercase. The start and end of the advancedsettings.xml file must have the <advancedsettings> and </advancedsettings> tags.
# Kodi will only read the advancedsettings.xml file when it starts up. If you make changes while it is running then you must restart Kodi.
# For some Windows versions, Kodi has two <code>\userdata\</code> folders. The correct one to put the advancedsettings.xml file in is not the one in Program Files, but in <code>%appdata%\Kodi\userdata\.</code>}}

== Layout ==

The layout of <code>advancedsettings.xml</code> is as follows:

<syntaxhighlight lang=xml enclose="div">
<advancedsettings version="1.0">
<setting>value</setting>
...
<setting>value</setting>
</advancedsettings>
</syntaxhighlight>

where "setting" gives the name of the setting, and "value" gives its value.

A list of the available "setting" strings and their values is given below.

= List of available settings =
List of available settings that are recognised in the advancedsettings.xml file <ref>https://github.com/xbmc/xbmc/blob/master/xbmc/settings/AdvancedSettings.cpp</ref>

Recommended: Use the table of contents or the search function in your browser to locate items.

== Troubleshooting settings ==

=== loglevel ===
{{Anchor|.3Cloglevel.3E}}

<section begin="loglevel" />
Sets the logging level used to log errors and information. The "hide" attribute is optional.

<syntaxhighlight lang=xml>
<loglevel hide="attribute">options</loglevel>
</syntaxhighlight>

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Attribute
! style="width:500px;" | Action
|-
! '''true'''
| Hides the "enable debugging" setting in the Settings page. (default)
|-
! '''false'''
| Allows "enable debugging" setting to switch between '''0''' and '''2'''.
|}

{| class="mw-collapsible mw-collapsed wikitable"
|-
! style="width:100px;" | Option
! style="width:500px;" | Action
|-
! '''-1'''
| No logging, suppresses all log output
|-
! '''0'''
| Normal logging, only logging errors (default)
|-
! '''1'''
| Debug logging with freemem, fps and cpu usage (no on screen)
|-
! '''2'''
| Same as 1 (with on screen display)
|-
! '''3'''
| Same as 2 + full smb logging (no on screen display)
|}

{| class="wikitable"
|-
! style="width:100px;" | Example
! style="width:500px;" |
|-
! Example 1:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings>
<loglevel>2</loglevel>
</advancedsettings>
</syntaxhighlight>
|-
! Example 2:
|<syntaxhighlight lang=xml enclose="div">
<advancedsettings>
<loglevel hide="true">2</loglevel>
</advancedsettings>
</syntaxhighlight>
|}

'''Note:''' The setting is persistent through shutdown and restarts.<br>
'''Note:''' If debugging is enabled in the GUI, loglevel will be set to '''2'''. This will over-ride the <code>advancedsettings.xml</code> setting. You must disable the GUI Setting before adding the entry to <code>advancedsettings.xml</code>.<br />
<section end="loglevel" />
:''{{see also|Log_file|label 1=Debug Log}}''

=== jsonrpc ===
{{Anchor|.3Cjsonrpc.3E}}
To make it easier for developers using the [[JSON-RPC_API]] API in their (third party) applications to debug during development the json output of Kodi can be prettified by setting '''compactoutput''' to '''false'''. Default json output mode is a compact print which does not contain any unnecessary whitespaces and therefore is difficult to read for humans.
Furthermore using the '''tcpport''' setting it is possible to change the default TCP port used by Kodi for JSON RPC (which is 9090) to any other valid port.

Example:
<syntaxhighlight lang=xml enclose="div">
<jsonrpc>
<compactoutput>false</compactoutput>
<tcpport>9999</tcpport>
</jsonrpc>
</syntaxhighlight>

== Audio/video playback settings ==

=== skiploopfilter ===
{{anchor|.3Cskiploopfilter.3E}}
The amount of the loop filter to skip on h.264 decoding. This can help the performance of slower machines when decoding h264 content. Values, in decreasing CPU usage (and decreasing quality)
* -16 None
* 0 Skip only empty frames (default)
* 8 Skip non-reference frames
* 16 Skip bi-dir frames
* 32 Skip all non-key frames
* 48 Skip all frames
Example:
<syntaxhighlight lang=xml enclose="div">
<skiploopfilter>8</skiploopfilter>
</syntaxhighlight>

=== video ===
{{anchor|.3Cvideo.3E}}

The <video> section also includes the following child-tags, which have their own sections:
*[[#cleandatetime]]
*[[#cleanstrings]]
*[[#excludefromscan]]
*[[#excludefromlisting]]
*[[#excludetvshowsfromscan]]

{{note|Some tags that have a "third-level" and are grouped together are highlighted in color.}}

{| class="prettytable"
! Tag !! Description
|-
|
<syntaxhighlight lang=xml>
<video>
</syntaxhighlight>
| Parent tag that all other child tags need to be placed inside of. Do not use more than one '''<code><video></code>''' tag, but instead place all other child-tags within a single '''<code><video></video></code>''' set.
|-
|
<syntaxhighlight lang=xml>
<subsdelayrange>10</subsdelayrange>
</syntaxhighlight>
| Delay range for subtitles, in seconds.
|-
|
<syntaxhighlight lang=xml>
<maxtempo>2.1</maxtempo>
</syntaxhighlight>
| Allow further increase of playback speed over the default of 1.5<br>
maxtempo must be in the range of 1.5 to 2.1 <br>
Be aware of the limitations of your platform / hardware as not all are capable of the increased maxtempo <ref>https://forum.kodi.tv/showthread.php?tid=10023&pid=2795069#pid2795069</ref>
|-
|
<syntaxhighlight lang=xml>
<audiodelayrange>10</audiodelayrange>
</syntaxhighlight>
| Delay range for audio/video sync, in seconds.
|-
|
<syntaxhighlight lang=xml>
<usetimeseeking>true</usetimeseeking>
</syntaxhighlight>
| Whether to use time based or percentage based seeking. {{small see also|Skip steps}}
|-
|
<syntaxhighlight lang=xml>
<timeseekforwardbig>600</timeseekforwardbig>
<timeseekbackwardbig>-600</timeseekbackwardbig>
</syntaxhighlight>
| Time to seek forward in seconds when doing a long seek. Defaults to 600 (10 minutes) and -600 (-10 minutes) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforward>2</percentseekforward>
<percentseekbackward>-2</percentseekbackward>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a short seek. Defaults to 2 (2%) and -2 (2%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<percentseekforwardbig>10</percentseekforwardbig>
<percentseekbackwardbig>-10</percentseekbackwardbig>
</syntaxhighlight>
| Amount to seek forward as a percentage, when doing a long seek. Defaults to 10 (10%) and -10 (10%) respectively. ''{{small|See also: [[Skip steps]] }}''
|-
|
<syntaxhighlight lang=xml>
<fullscreenonmoviestart>true</fullscreenonmoviestart>
</syntaxhighlight>
| Whether to go to fullscreen or not when starting a movie. Defaults to true.
|-
|
<syntaxhighlight lang=xml>
<defaultplayer>VideoPlayer</defaultplayer>
</syntaxhighlight>
| Set the default video player: VideoPlayer or an external player. See '''[[External players]]''' for more info.
|-
|
<syntaxhighlight lang=xml>
<excludefromscan>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromscan>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be added to library. It is possible to add multiple <code><regexp></code> tags to match multiple patterns
|-
|
<syntaxhighlight lang=xml>
<excludefromlisting>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</syntaxhighlight>
| Regular expressions that if evaluated to true won't be displayed in files view.
|-
|
<syntaxhighlight lang=xml>
<playcountminimumpercent>90</playcountminimumpercent>
</syntaxhighlight>
| Minimum percentage that has to be played before it is marked as watched. Set to 101 to never auto-mark items as watched. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignoresecondsatstart>180</ignoresecondsatstart>
</syntaxhighlight>
| Number of seconds to ignore at video start after which a resume point is created. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<ignorepercentatend>8</ignorepercentatend>
</syntaxhighlight>
| Percentage of video to ignore at the end. If you stop watching the video here no resume point is created. Set to 101 to never save a resume point. The video is already marked as watched at 90%, see above. ''{{small|See also: [[HOW-TO:Modify automatic watch and resume points]] }}''
|-
|
<syntaxhighlight lang=xml>
<vdpauscaling>true</vdpauscaling>
</syntaxhighlight>
| Scales with vdpau instead of opengl and turns on its HQ scaler when available, enabling this might slow down rendering and cause framedrops especially on ION systems, this setting requires a vdpau feature set C GPU.
|-
|
<syntaxhighlight lang=xml>
<enablehighqualityhwscalers>true</enablehighqualityhwscalers>
</syntaxhighlight>
| Allow turning on the spline36 and lanczos3 shader (for GL builds).
|-
|
<syntaxhighlight lang=xml>
<dxvaallowhqscaling>false</dxvaallowhqscaling>
</syntaxhighlight>
| Enables high quality video upscaling for Windows.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegdeinterlacing>linblenddeint</ppffmpegdeinterlacing>
</syntaxhighlight>
| Override the deinterlacing options passed to libpostproc.
|-
|
<syntaxhighlight lang=xml>
<ppffmpegpostprocessing>ha:128:7,va,dr</ppffmpegpostprocessing>
</syntaxhighlight>
| Override the post processing options passed to libpostproc when 'Video post-processing' is activated in GUI Videos-Settings-Playback.
|-
|
<syntaxhighlight lang=xml>
<autoscalemaxfps>30</autoscalemaxfps>
</syntaxhighlight>
| When scaling method is set to auto, bilinear is chosen when the fps is higher than this limit, the default is 30.
|-
|
<syntaxhighlight lang=xml>
<adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" | Settings for when "Adjust refreshrate to match video fps" is enabled in the video playback GUI settings.
|-
|
<syntaxhighlight lang=xml>
<override>
<fps>23.976</fps>
<refresh>60.0</refresh>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' "Adjust refreshrate to match video fps" will try to select the best refreshrate for the video fps but it doesn't always get it right, for example it might switch to an unsupported refreshrate. You can add overrides here to switch to a certain refreshrate based on video fps. It's possible to add as many overrides as you need. Overrides are processed in order, if the first one doesn't match the fps or no refreshrates match that override, it will try the next one until no overrides are left.

* '''fps''' - if the fps is between 23.966 and 23.986
* '''refresh''' - switch to the first found refreshrate that is between 59.99 and 60.01
|-
|
<syntaxhighlight lang=xml>
<override>
<fpsmin>29.96</fpsmin>
<fpsmax>30.01</fpsmax>
<refreshmin>59.0</refreshmin>
<refreshmax>61.0</refreshmax>
</override>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -'''
* '''fpsmin''' / '''fpsmin''' - You can also specify the fps range yourself.
* '''refreshmin''' / '''refreshmax''' - Same for the refreshrate
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refresh>50.0</refresh>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' If none of the overrides match, or none of the refreshrates match any of the fps matching overrides, it will choose a fallback refreshrate. Fallbacks are process in order, if the first fallback doesn't match any refreshrate, it will try the next one until no fallbacks are left.

* '''refresh''' - Switch to the first found refreshrate that is between 49.99 and 50.01.
|-
|
<syntaxhighlight lang=xml>
<fallback>
<refreshmin>49.0</refreshmin>
<refreshmax>51.0</refreshmax>
</fallback>
</syntaxhighlight>
| style="background:#CADCFB;" | '''Example -''' You can also specify the range for the fallback yourself.

If none of the overrides match the video fps, or no refreshrates match any of the fps matching overrides, and no fallbacks are specified or no refreshrates match any fallbacks, it will automatically choose the best refreshrate (same as having no overrides and fallbacks).
|-
|
<syntaxhighlight lang=xml>
</adjustrefreshrate>
</syntaxhighlight>
| style="background:#CADCFB;" |
|-
|
<syntaxhighlight lang=xml>
<checkdxvacompatibility>value</checkdxvacompatibility>
</syntaxhighlight>
| Advanced setting not present: let Kodi autodetect cards that support H.264 profile > L4.1. Set value to false to enable DXVA no matter what. Set value to true if Kodi doesn't autodetect that the graphics card doesn't support > L4.1.
|-
|
<syntaxhighlight lang=xml>
<useocclusionquery>-1</useocclusionquery>
</syntaxhighlight>
| Use an occlusion query when capturing videoframes, -1 means auto detect, 0 means disabled, 1 means enabled, the default is -1.
|-
|
<syntaxhighlight lang=xml>
<fpsdetect>1</fpsdetect>
</syntaxhighlight>
| FPS detection for video playback
* 0 = trust codec fps
* 1 = recalculate from video timestamps with uniform spacing
* 2 = recalculate from video timestamps always
|-
|
<syntaxhighlight lang=xml>
<latency>
</syntaxhighlight>
| style="background:#F0E68C;"| Start of '''latency''' tags. Display latency (video lag). Latency is given in msecs.
|-
|
<syntaxhighlight lang=xml>
<delay>0</delay>
</syntaxhighlight>
| style="background:#F0E68C;" | Global default display latency.
|-
|
<syntaxhighlight lang=xml>
<refresh></refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | Override latency for given display (not video) refresh rates. When Kodi is in windowed mode, override is ignored. Multiple overrides are allowed.

Syntax of an override entry:
<syntaxhighlight lang=xml>
<refresh>
<min>, <max> refresh rate range, OR
<rate> exact refresh rate
<delay> display latency for the given refresh rate
</refresh>
</syntaxhighlight>
|-
|
<syntaxhighlight lang=xml>
<refresh>
<min>23</min>
<max>24</max>
<delay>125</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 125 msec latency at 23-24 Hz
|-
|
<syntaxhighlight lang=xml>
<refresh>
<rate>50</rate>
<delay>50</delay>
</refresh>
</syntaxhighlight>
| style="background:#F0E68C;" | '''Example:''' display has 50 msec latency at 50 (+/-0.01) Hz
|-
|
<syntaxhighlight lang=xml>
</latency>
</syntaxhighlight>
| style="background:#F0E68C;" |
|-
|
<syntaxhighlight lang=xml>
<stereoscopicregex3d>[-. _]3d[-. _]</stereoscopicregex3d>
<stereoscopicregexsbs>[-. _]h?sbs[-. _]</stereoscopicregexsbs>
<stereoscopicregextab>[-. _]h?tab[-. _]</stereoscopicregextab>
</syntaxhighlight>
| Filename triggers for 3D (stereoscopic) mode.
|-
|
<syntaxhighlight lang=xml>
<assfixedworks>false</assfixedworks>
</syntaxhighlight>
| Position behavior of ass subtitiles when setting "subtitle position on screen" set to "fixed". True to show at the fixed position set in video calibration. False to show at the bottom of video (default). {{note|Removed in Kodi v20.}}
|-
|
<syntaxhighlight lang=xml>
<subtitleverticalmargin>120</subtitleverticalmargin>
</syntaxhighlight>
| Allows to customise the vertical margin of text based subtitles, which will be applied to each type of subtitle position in subtitle settings. {{note|Available in Kodi v20 and above.}}
|-
|
<syntaxhighlight lang=xml>
</video>
</syntaxhighlight>
|
|}

=== audio ===
{{anchor|.3Caudio.3E}}
<syntaxhighlight lang=xml enclose="div">
<audio>

<headroom>0</headroom>

<defaultplayer>paplayer</defaultplayer>

<excludefromscan>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromscan>

<excludefromlisting>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromlisting>

<ac3downmixgain>12.0</ac3downmixgain>

<usetimeseeking>true</usetimeseeking>

<timeseekforwardbig>600</timeseekfowardbig>

<timeseekbackwardbig>-600</timeseekbackward>

<playcountminimumpercent>99</playcountminimumpercent>

<applydrc>-1.0</applydrc>

<limiterhold>0.025</limiterhold>

<limiterrelease>0.1</limiterrelease>
</audio>
</syntaxhighlight>

=== forcedswaptime ===
{{anchor|.3Cforcedswaptime.3E}}
Use to force a backbuffer->frontbuffer swap while vsync is enabled. Set to the time (in ms) to allow for the swap (e.g. <forcedswaptime>1</forcedswaptime> is typical).

Default: Off

=== edl ===
{{anchor|.3Cedl.3E}}
{{main|Edit_decision_list}}
Commercial break detection not as good you think it could be? Are some commercial breaks in a series of adverts not being skipped? Are some parts being skipped that are clearly not commercials? Does the end of the previous recording still show? The following advanced settings can be used to better identify full commercial break sequences, remove incorrectly flagged commercial breaks, and have playback start at the actual beginning of the recording.

<syntaxhighlight lang=xml enclose="div">
<edl>

<mergeshortcommbreaks>false</mergeshortcommbreaks>

<maxcommbreaklength>250</maxcommbreaklength>

<mincommbreaklength>90</mincommbreaklength>

<maxcommbreakgap>120</maxcommbreakgap>

<commbreakautowait>0</commbreakautowait>

<commbreakautowind>0</commbreakautowind>
</edl>
</syntaxhighlight>

== PVR & Live TV ==
{{anchor|.3Cpvr.3E}}
Settings available for PVR, EPG and Live TV. Edit Decision List settings are located in the previous section.

=== pvr ===
<syntaxhighlight lang="xml" line='line'>
<pvr>
<timecorrection>0</timecorrection> 
<infotoggleinterval>3000</infotoggleinterval> 
<channeliconsautoscan>true</channeliconsautoscan> 
<autoscaniconsuserset>false</autoscaniconsuserset> 
<numericchannelswitchtimeout>1000</numericchannelswitchtimeout> 
</pvr>
</syntaxhighlight>

==== pvrrecordings ====
In v19 and later, allows users to modify sort type and order of pvr recordings. <ref>https://github.com/xbmc/xbmc/pull/18605</ref>

;Note- These settings are child tags to the ''<pvr>'' tag in the previous section.

<syntaxhighlight lang="xml" line='line'>
<pvr>
<pvrrecordings>
<sortmethod>2</sortmethod> 
<sortorder>2</sortorder> 
</pvrrecordings>
</pvr>
</syntaxhighlight>

=== epg ===
{{anchor|.3Cpvr.3E}}
<syntaxhighlight lang="xml" line='line'>
<epg>
<updatecheckinterval>300</updatecheckinterval> 
<updateemptytagsinterval>60</updateemptytagsinterval> 
<cleanupinterval>900</cleanupinterval> 
<activetagcheckinterval>60</activetagcheckinterval> 
<retryinterruptedupdateinterval>60</retryinterruptedupdateinterval> 
<displayupdatepopup>true</displayupdatepopup> 
<displayincrementalupdatepopup>false</displayincrementalupdatepopup> 
</epg>
</syntaxhighlight>

== Video library settings ==

=== videoextensions ===
{{anchor|.3Cvideoextensions.3E}}<section begin="videoextensions" />
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Video windows.

Default extensions for VIDEOS:
<pre>
.m4v .3g2 .3gp .nsv .tp .ts .ty .strm .pls .rm .rmvb .mpd .m3u .m3u8 .ifo .mov .qt .divx .xvid
.bivx .vob .nrg .img .iso .udf .pva .wmv .asf .asx .ogm .m2v .avi .bin .dat .mpg .mpeg .mp4
.mkv .mk3d .avc .vp3 .svq3 .nuv .viv .dv .fli .flv .001 .wpl .xspf .zip .vdr .dvr-ms .xsp .mts
.m2t .m2ts .evo .ogv .sdp .avs .rec .url .pxml .vc1 .h264 .rcv .rss .mpls .mpl .webm .bdmv
.bdm .wtv .trp .f4v
</pre>
Examples:
<pre>
<videoextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</videoextensions>
</pre>
<section end="videoextensions" />

=== discstubextensions ===
{{main|Media stubs}}

<section begin="discstubextensions" />
The default filename extension for Disc Stubs is:
<syntaxhighlight lang=xml enclose="div">
.disc
</syntaxhighlight>
Using the following tags, it is possible to <tt><add></tt> additional or <tt><remove></tt> existing disc stub extensions to better suit your requirements.
<syntaxhighlight lang=xml enclose="div">
<discstubextensions>
<add>.disk|.stub</add>
<remove>.disc</remove>
</discstubextensions>
</syntaxhighlight>
<section end="discstubextensions" />

=== languagecodes ===
{{anchor|.3Clanguagecodes.3E}}
Translation table for subtitle and audio names. Contains entries of the form

<syntaxhighlight lang=xml enclose="div">
<languagecodes>
<code>
<short>alt</short>
<long>Alternate</long>
</code>
</languagecodes>
</syntaxhighlight>

=== moviestacking ===
{{anchor|.3Cmoviestacking.3E}}<section begin="moviestacking" />
{{main|Naming_video_files/Movies}}
This is used by the [[Naming_video_files/Movies#Split_Video_Files|file stacking]] algorithm to combine multi-part files and contains a list of "''[[RegEx_tutorial|regular expressions]]''". For stacking videos that are contained in folders, such as VIDEO_TS folders, see '''[[advancedsettings.xml#folderstacking|<folderstacking>]]'''

As of v9.11, video stacking regular expressions '''must''' contain exactly four (4) capture expressions.

Default:
<syntaxhighlight lang=xml enclose="div">
<moviestacking>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[0-9]+)(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck])[ _.-]*[a-d])(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ ._-]*[a-d])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="append"</tt> or <tt>append="yes"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the end.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="append">

<regexp>(.*?)([ ._-]*[0-9])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="prepend"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the beginning.

Example:
<syntaxhighlight lang=xml enclose="div">
<moviestacking action="prepend">
<regexp>(Title)(Volume)(Ignore)(Extension)</regexp>
</moviestacking>
</syntaxhighlight>

If no argument is supplied, or the argument <tt>append="no"</tt> is supplied, the default moviestacking regular expressions are overwritten by the user specified ones.
<section end="moviestacking" />

=== folderstacking ===
{{main|Naming_video_files/Movies}}
This is similar to '''[[advancedsettings.xml#moviestacking|<moviestacking>]]''', but is used for videos that are contained in folders that use the folder names to stack, such as VIDEO_TS folders (DVD rips that are not in ISO format).

Default:
<syntaxhighlight lang=xml enclose="div">
<folderstacking>

<regexp>((cd|dvd|dis[ck])[0-9]+)$</regexp>
</folderstacking>
</syntaxhighlight>

=== cleandatetime ===
{{anchor|.3Ccleandatetime.3E}}
Matches a year number in a string using a ''[[RegEx_tutorial|Regular Expression]]''

Default expression:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleandatetime>(.*[^ _\,\.\[\]\-])[ _\.\[\]\-]+(19[0-9][0-9]|20[0-9][0-9])([ _\,\.\[\]\-]|[^0-9]$)?</cleandatetime>
</video>
</syntaxhighlight>
:* The string found before will be used as basis string getting cleaned by the cleanstrings expressions.
:* By default date formats like MM:YY are ignored.

=== cleanstrings ===
{{anchor|.3Ccleanstrings.3E}}
Clean unwanted characters from filenames or folders by using a list of ''[[RegEx_tutorial|Regular Expressions]]''. Please note that everything right of the match (at the end of the file name) is removed, so if you would have a file named ''Super movie.mp4'' and would add <tt><regexp> </regexp></tt> (only a space), the only thing that would be left is ''Super'', which is probably not what you want.

{{Github_link|[https://github.com/xbmc/xbmc/blob/Matrix/xbmc/settings/AdvancedSettings.cpp#L188 Code in Github]}}

Default expressions:
<syntaxhighlight lang=xml enclose="div">
<video>
<cleanstrings>
<regexp>[ _\,\.\[\]\-](aka|ac3|dts|custom|dc|remastered|divx|divx5|dsr|dsrip|dutch|dvd|dvd5|dvd9|dvdrip|dvdscr|dvdscreener|screener|dvdivx|cam|fragment|fs|hdtv|hdrip|hdtvrip|internal|limited|multisubs|ntsc|ogg|ogm|pal|pdtv|proper|repack|rerip|retail|r3|r5|bd5|se|svcd|swedish|german|read.nfo|nfofix|unrated|extended|ws|telesync|ts|telecine|tc|brrip|bdrip|480p|480i|576p|576i|720p|720i|1080p|1080i|3d|hrhd|hrhdtv|hddvd|bluray|x264|h264|xvid|xvidvd|xxx|www.www|cd[1-9]|\[.*\])([ _\,\.\[\]\-]|$)</regexp>
<regexp>(\[.*\])</regexp>
</cleanstrings>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== tvshowmatching ===
{{anchor|.3Ctvshowmatching.3E}}
Matches the season and episode numbers in file paths by using a list of ''[[RegEx_tutorial|Regular Expressions]]''

{{Github_link|[https://github.com/xbmc/xbmc/blob/Matrix/xbmc/settings/AdvancedSettings.cpp#L232 Code in Github]}}

Defaults:
<syntaxhighlight lang=xml enclose="div">
<tvshowmatching>
<regexp>s([0-9]+)[ ._x-]*e([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)([^\\\\/]*)$</regexp> 
<regexp>[\._ -]()[Ee][Pp]_?([0-9]+)([^\\/]*)$</regexp> 
<regexp>([0-9]{4})[\.-]([0-9]{2})[\.-]([0-9]{2})</regexp> 
<regexp>([0-9]{2})[\.-]([0-9]{2})[\.-]([0-9]{4})</regexp> 
<regexp>[\\/\._ \[\(-]([0-9]+)x([0-9]+)([^\\/]*)$</regexp> 
<regexp>[\\/\._ -]([0-9]+)([0-9][0-9])([\._ -][^\\/]*)$</regexp> 
<regexp>[\/._ -]p(?:ar)?t[_. -]()([ivx]+)([._ -][^\/]*)$</regexp> 
</tvshowmatching>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)
:* Paths are converted to lower case before matching.
:* For multi-episode matching to work, there needs to be a third set of parentheses '()' at the end, this part is fed back into the regexp engine.
:* A [https://forum.kodi.tv/showthread.php?tid=51614 forum thread] has a discussion of pre-made regex lists to match common names. These might improve Kodi's ability to match TV show names in some situations, at the risk of additional false positives.

==== Filenames without Season ====
There are two methods to add episodes without a season in their file path. Both ways will force the season to '1' by default, so that you can use
the 'Use Absolute Ordering (Single Season)' setting from the TheTvDb.com scraper.

; Simple Method ''(XBMC v9.11 onwards and Kodi)''
: Use only one pair of parentheses
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]([0-9]+)</regexp></syntaxhighlight>
; Advanced Method ''(XBMC v10.05 onwards and Kodi)''
: Supports multi-episode files without season
: Use an empty pair of parentheses for the season
<syntaxhighlight lang=xml enclose="div"><regexp>[/\._ \-]()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

; Specifying Default Season ''(XBMC v12.0 onwards and Kodi)''
It is possible to set the default season for specific regular expressions by setting the 'defaultseason' attribute.
: Works with both the simple method and advanced method
: If not used, the season will be set to '1'
: Useful for setting specials to season '0'
<syntaxhighlight lang=xml enclose="div"><regexp defaultseason="0">[/\._ \-]X()([0-9]+)(-[0-9]+)?</regexp>
<regexp defaultseason="1">[/\._ \-]E()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

=== tvmultipartmatching ===
{{anchor|.3Ctvmultipartmatching.3E}}
Matches a multipart episode number based on a previously identified episode file, using a list of ''[[RegEx_tutorial|Regular Expressions]]''.

Default:
<syntaxhighlight lang=xml enclose="div">
<tvmultipartmatching>^[-_ex]+([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)</tvmultipartmatching>
</syntaxhighlight>
:* Text matching is compared case-insensitive.
:* Specifying this option '''replaces''' the default value

=== excludefromscan ===
{{anchor|.3Cexcludefromscan.3E}}
Matches filenames or folders which should be excluded from a library scan (except tvshows) using a list of ''[[RegEx_tutorial|Regular Expressions]]''. This can be for both Video or Audio sections of <tt>advancedsettings.xml</tt>.

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromscan>
<regexp>-trailer</regexp>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludefromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== excludefromlisting ===
{{anchor|.3Cexcludefromlisting.3E}}
<syntaxhighlight lang=xml enclose="div">
<video>
<excludefromlisting> 
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</video>
</syntaxhighlight>

=== excludetvshowsfromscan ===
{{anchor|.3Cexcludetvshowsfromscan.3E}}
Matches filenames or folders which should be excluded from a tvshow library scan using a list of ''[[RegEx_tutorial|Regular Expressions]]''

Defaults:
<syntaxhighlight lang=xml enclose="div">
<video>
<excludetvshowsfromscan>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludetvshowsfromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== trailermatching ===
{{anchor|.3Ctrailermatching.3E}}
Contains "''[[RegEx_tutorial|Regular Expression]]''" syntax (commonly referred to as "''[[RegEx_tutorial|RegEx]]''" or "''[[RegEx_tutorial|RegExp]]''") to match the locally stored trailers to movies in the library.

<syntaxhighlight lang=xml enclose="div">
<trailermatching>

<regexp>(.*?)(_Trailer)(\.[^.]+)$</regexp>
</trailermatching>
</syntaxhighlight>

=== videolibrary ===
{{anchor|.3Cvideolibrary.3E}}
Options specific to the Video Library

{{Note|Kodi v20 users don't need set "importwatched" or "importresumepoint" to true anymore as that's the default then <ref>https://github.com/xbmc/xbmc/pull/20842</ref>}}

<syntaxhighlight lang="xml" line='line'>
<videolibrary>
<allitemsonbottom>false</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<usefasthash>true</usefasthash> 
<recentlyaddeditems>35</recentlyaddeditems> 
<itemseparator> / </itemseparator> 
<exportautothumbs>false</exportautothumbs> 
<importwatchedstate>false</importwatchedstate> 
<importresumepoint>false</importresumepoint> 
<dateadded>1</dateadded> 
</videolibrary>
</syntaxhighlight>

==== Extra artwork ====

Applies to Kodi v18 only.

Configuration to expand the artwork automatically added by Kodi to media items in the library, either from local files or online scrapers.

The original basic artwork types are still hardcoded so they don't need to be configured here (and can't be removed). "poster" and "fanart" for movies, movie sets, TV shows, seasons, and music videos; "banner" for TV shows and seasons; and "thumb" for episodes.

<syntaxhighlight lang=xml enclose="div">
<videolibrary>


<tvshowextraart>
<arttype>characterart</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>landscape</arttype>
<arttype>keyart</arttype>
</tvshowextraart>

<tvseasonextraart>
<arttype>landscape</arttype>
</tvseasonextraart>

<episodeextraart>
<arttype>fanart</arttype>
</episodeextraart>

<movieextraart>
<arttype>banner</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>discart</arttype>
<arttype>landscape</arttype>
<arttype>keyart</arttype>
</movieextraart>

<moviesetextraart>
<arttype>banner</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>discart</arttype>
<arttype>landscape</arttype>
<arttype>keyart</arttype>
</moviesetextraart>

<musicvideoextraart>
<arttype>banner</arttype>
<arttype>clearart</arttype>
<arttype>clearlogo</arttype>
<arttype>discart</arttype>
<arttype>landscape</arttype>
</musicvideoextraart>
</videolibrary>
</syntaxhighlight>

=== videoscanner ===
{{anchor|.3Cvideoscanner.3E}}
Options specific to the Video scanner
<syntaxhighlight lang=xml enclose="div">
<videoscanner>
<ignoreerrors>true</ignoreerrors> 
</videoscanner>
</syntaxhighlight>

== Library artwork ==

{{note|Using <imageres>9999</imageres> and <fanartres>9999</fanartres> will allow caching artwork at original size.}}

=== imageres ===
{{anchor|.3Cimageres.3E}}

<section begin="imageres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached artwork]] (other than fanart / 16:9 images) should be resized to in pixels. The width is automatically calculated as being 16/9*height. The image will be resized to fit within this size. e.g. an image that is 2000x500 will be cached at size 1280x320. An image that is 500x800 will be cached at size 450x720 using the default value of 720.<section end="imageres description" />

<syntaxhighlight lang=xml enclose="div">
<imageres>720</imageres>
</syntaxhighlight>

=== fanartres ===
{{anchor|.3Cfanartres.3E}}

<section begin="fanartres description" />Specify the maximum resolution that [[Artwork/Cache#Texture optimization| cached fanart]] should be resized to in pixels. The width is automatically calculated as being 16/9*height. Only images that are exactly 16x9 and equal to or greater than this resolution will be cached at this size - all other images will be cached using <imageres>. The default value is 1080.<section end="fanartres description" />

<syntaxhighlight lang=xml enclose="div">
<fanartres>1080</fanartres>
</syntaxhighlight>

=== imagescalingalgorithm ===
Specify the image scaling algorithm for image resizing when [[Artwork/Cache#Texture optimization| caching artwork]] to the local texture cache.
<br />
<syntaxhighlight lang=xml enclose="div">
<imagescalingalgorithm>bicubic</imagescalingalgorithm>
</syntaxhighlight>

[https://github.com/xbmc/xbmc/blob/1a8753d5cd93890dc6a9f9d4b2ce8848066ea5d0/xbmc/pictures/PictureScalingAlgorithm.cpp#L32-L43 Available image scaling algorithms]

<syntaxhighlight lang=text enclose="div">
fast_bilinear
bilinear
bicubic
experimental
nearest_neighbor
averaging_area
bicublin
gaussian
sinc
lanczos
bicubic_spline
</syntaxhighlight>

=== thumbqualityjpeg ===
This specifies the quality of the thumbnails when stored in jpeg format. By default kodi uses a quality of 4 which is a good compromise between size and quality. If you want to reduce the thumbnail sizes (decreasing quality) choose a higher value up to 21. If high quality (large thumbnail size) is needed, chose a smaller value, e.g. 0,1,2 or 3.
<br />
<syntaxhighlight lang=xml enclose="div">
<thumbqualityjpeg>4</thumbqualityjpeg>
</syntaxhighlight>

== Video and music library settings ==

=== playlistasfolders ===
{{anchor|.3Cplaylistasfolders.3E}}
In the recent releases, playlists are treated as folders. Selecting a playlist no longer plays it, but opens it, as if it were a folder.

Set to false to revert to the previous behaviour. When you select a playlist, its content is added to the list of elements to be played.

:{{note|This setting will not affect smart playlists, they will always show as folders.}}

;Example
<syntaxhighlight lang=xml enclose="div">
<playlistasfolders>true</playlistasfolders>
</syntaxhighlight>

=== playlistretries ===
{{anchor|.3Cplaylistretries.3E}}
The number of retries attempted if a source is offline. With this control you can alter the number of consecutive failed items before a playlist fails.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlistretries>100</playlistretries>
</syntaxhighlight>

=== playlisttimeout ===
{{anchor|.3Cplaylisttimeout.3E}}
The timeout, in seconds, before item failure.

Default:
<syntaxhighlight lang=xml enclose="div">
<playlisttimeout>20</playlisttimeout>
</syntaxhighlight>

=== sorttokens ===
Allows you to specify additional tokens that will be ignored at the start of lines during sorting.
{{note|Sort tokens are case sensitive.}}
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token>the</token>
</sorttokens>
</syntaxhighlight>

In the above example "the ", "the." and "the_" will be ignored at the start of titles or names when sorting items, in both video and music libraries. A separator can also be specified, for example
<syntaxhighlight lang=xml enclose="div">
<sorttokens>
<token separators="'">L</token>
</sorttokens>
</syntaxhighlight>
In that case the value L', as in French movie name ''L'argent'', will be ignored and the item listed under "A".

=== musicdatabase/videodatabase ===
{{anchor|.3Cmusicdatabase.3E/.3Cvideodatabase.3E|musicdatabase/videodatabase|database tags music/video/tv/epg/adsp}}
{{main|MySQL}}
<section begin="videodatabase" />
Allows advanced customization of the default database settings for music, video, TV, EPG, and ADSP databases.

:{{note| '''It is HIGHLY recommended that you not attempt to place an sqlite3 database outside of kodi's path. sqlite3 contains no filesystem abstraction, so this will plain break on any non-local (as far as Kodi is concerned) paths. Use this for mysql only.'''}}

'''Parent tags:'''

* '''<videodatabase>'''
* '''<musicdatabase>'''
* '''<tvdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<epgdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
* '''<adspdatabase>''' - Highly experimental/unstable and no practical benefit for most users. '''Avoid using.'''
{{MySQL warning}}

'''Child tags: '''

;<type>
: ''Required'' - Can be either "sqlite3" or "mysql" (default: sqlite3)

;<host>
:''Required'' -
* sqlite3: defines the relative path to the database file (eg. /usr/local/kodi/databases).
* mysql: defines the host of the mysql socket (eg. localhost, 192.168.0.1, etc)

;<port>
: ''Optional'' -
* sqlite3: silently ignored
* mysql: defines the port of the mysql socket (default: 3306)

;<name>
: ''Optional'' -
:by default "MyVideos"+DB number will be used.
* sqlite3: defines the name of the database file to read from, excluding the ".db" extension.
* mysql: defines the name of the database to use

;<user>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the user with privileged access to the database

;<pass>
: ''Required for MySQL'' -
* sqlite3: silently ignored
* mysql: defines the password for the user with privileged access to the database

;<compression>
: ''Optional'' - Defaults to false. Set to "true" to enable MySQL compression protocol. Performance benefit is going to be largely dependent on the network bandwidth, latency between database and clients and on the size of the result sets. [https://github.com/xbmc/xbmc/pull/6484]
: {{Note|Slower clients (such as the RPi and others) won't benefit from it as the zlib de-compression overhead is higher than the actual compression savings}}

;<key>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<cert>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ca>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<capath>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

;<ciphers>
: ''Optional'' - SSL setting for MySQL [https://github.com/xbmc/xbmc/pull/2566]

'''Examples:'''

1) Configure a database for MySQL.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<videodatabase>
<type>mysql</type>
<host>192.168.0.10</host>
<name>kodi_video</name>
<user>kodi</user>
<pass>kodi</pass>
</videodatabase>
</syntaxhighlight>

2) Configure a database for an sqlite database.
:{{note| ''The '''<videodatabase>''', '''<musicdatabase>''', '''<tvdatabase>''', '''<epgdatabase>''', and '''<adspdatabase>''' tags are interchangeable here.''}}
<syntaxhighlight lang=xml enclose="div">
<musicdatabase>
<type>sqlite3</type>
<host>/usr/local/share/kodi/databases</host>
</musicdatabase>
</syntaxhighlight>

<section end="videodatabase" />

=== externalplayer ===
{{anchor|.3Cexternalplayer.3E}}
{{see|External players}}

== Music settings ==

=== musicextensions ===
{{anchor|.3Cmusicextensions.3E}}
<section begin="musicextensions" />
Default extensions for MUSIC:
<pre>
.nsv .m4a .flac .aac .strm .pls .rm .rma .mpa .wav .wma .ogg .mp3 .mp2 .m3u .gdm .imf .m15 .sfx
.uni .ac3 .dts .cue .aif .aiff .wpl .xspf .ape .mac .mpc .mp+ .mpp .shn .zip .wv .dsp .xsp .xwav
.waa .wvs .wam .gcm .idsp .mpdsp .mss .spt .rsd .sap .cmc .cmr .dmc .mpt .mpd .rmt .tmc .tm8
.tm2 .oga .url .pxml .tta .rss .wtv .mka .tak .opus .dff .dsf .m4b .dtshd
</pre>

It is possible to add or remove extensions for Music, using the following XML tags. Useful if you keep, say, FLAC and mp3 versions of music in the same folder. The <remove> tag can be used to remove mp3 from being listed in the library, leaving only the higher quality FLAC being displayed.

<musicextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</musicextensions>

<section end="musicextensions" />

=== cddbaddress ===
{{anchor|.3Ccddbaddress.3E}}
The address of the online CDDb database. You may set this to another freedb mirror if there is a more suitable one.

Default:
<syntaxhighlight lang=xml enclose="div>
<cddbaddress>freedb.freedb.org</cddbaddress>
</syntaxhighlight>

=== songinfoduration ===
{{anchor|.3Csonginfoduration.3E}}
This controls how long the song information will remain onscreen when the song changes during visualisations. The valid range is "1" to "Indefinite (0)", in seconds. This does not include the duration of any transition effects.

Default:
<syntaxhighlight lang=xml enclose="div">
<songinfoduration>10</songinfoduration>
</syntaxhighlight>

=== musicfilenamefilters ===
{{anchor|.3Cmusicfilenamefilters.3E}}
Contains filters to match music information (artist, title etc.) from a tag-less music filename. The first <filter> to match completely is used. Matched items include:

<pre>
%A - Artist
%T - Title
%B - Album
%N - Track number
%S - Part of set (disk number)
%D - Duration
%G - Genre
%Y - Year
%R - Rating
</pre>

Example:
<syntaxhighlight lang=xml enclose="div">
<musicfilenamefilters>
<filter>%A - %T</filter>
</musicfilenamefilters>
</syntaxhighlight>

=== musiclibrary ===
Options specific to the Music Library
<section begin="MusicLibrary" />
<syntaxhighlight lang="xml" line='line'>
<musiclibrary>
<allitemsonbottom>true</allitemsonbottom> 
<cleanonupdate>false</cleanonupdate> 
<recentlyaddeditems>35</recentlyaddeditems> 
<albumformat>%B - %Y</albumformat> 
<prioritiseapetags>true</prioritiseapetags> 
<itemseparator> / </itemseparator> 
<artistseparators> 
<separator>;</separator>
<separator>:</separator>
<separator>|</separator>
<separator> feat. </separator>
<separator> ft. </separator>
</artistseparators>
<dateadded>1</dateadded> 


<useisodates>false</useisodates> 
</musiclibrary>
</syntaxhighlight>
{{Note|Changing the <itemseparator> or <artistseparators> will only affect newly added items. A rescan won't change the existing ones. Remove the Source(s) or delete the Music DB and rebuild. This process should be made easier from v18 and up using <promptfulltagscan>}}<section end="MusicLibrary" />

== Photos settings ==

=== pictureextensions ===
{{anchor|.3Cpictureextensions.3E}}
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Pictures window.

Default extensions for PICTURES:
<pre>
.png .jpg .jpeg .bmp .gif .ico .tif .tiff .tga .pcx .cbz .zip .rss .webp .jp2 .apng
</pre>

Examples:
<syntaxhighlight lang=xml enclose="div">
<pictureextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</pictureextensions>
</syntaxhighlight>

=== pictureexcludes ===
{{anchor|.3Cpictureexcludes.3E}}
Matches filenames or folders which should be excluded from being displayed in My Pictures using a list of ''[[RegEx_tutorial|Regular Expressions]]''

<syntaxhighlight lang=xml enclose="div">
<pictureexcludes> 
<regexp>small</regexp>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</pictureexcludes>
</syntaxhighlight>

=== slideshow ===
{{anchor|.3Cslideshow.3E}}
<syntaxhighlight lang=xml enclose="div">
<slideshow>

<panamount>2.5</panamount>

<zoomamount>5.0</zoomamount>



<blackbarcompensation>20</blackbarcompensation>
</slideshow>
</syntaxhighlight>

== Network settings ==

=== ftp ===
{{anchor|.3Cftp.3DE}}
Specific settings if a ftp server is in use as a source

<syntaxhighlight lang=xml enclose="div">
<ftp>
<remotethumbs>true</remotethumbs> 
</ftp>
</syntaxhighlight>

=== samba ===
{{anchor|.3Csamba.3E}}
<syntaxhighlight lang=xml enclose="div">
<samba>
<doscodepage></doscodepage> 
<clienttimeout>10</clienttimeout> 
<statfiles>true</statfiles> 
</samba>
</syntaxhighlight>

=== hosts ===
{{anchor|.3Cfhosts.3E}}
Static dns entries which take precedence over your dns server.
<syntaxhighlight lang=xml enclose="div">
<hosts>
<entry name="HOSTNAME">IPADDRESS</entry>
</hosts>
</syntaxhighlight>

=== network ===
{{anchor|.3Cnetwork.3E}}

<syntaxhighlight lang=xml line='line'>
<network>
<curlclienttimeout>10</curlclienttimeout> 
<curllowspeedtime>20</curllowspeedtime> 
<curlretries>2</curlretries> 
<httpproxyusername></httpproxyusername> 
<httpproxypassword></httpproxypassword> 
<disableipv6>false</disableipv6> 
<disablehttp2>false</disablehttp2> 
<nfstimeout>30</nfstimeout> 
<catrustfile>filepath</catrustfile> 
<curlkeepaliveinterval>30</curlkeepaliveinterval> 
</network>
</syntaxhighlight>

{{Note|In Kodi v17, the three buffer settings are removed from the <code><network></code> tag and now placed under the new <code><cache></code> tag. See '''[[#cache]]''' for full details.}}

<curlkeepaliveinterval><ref>https://github.com/xbmc/xbmc/pull/19319</ref>

=== cache ===
{{see also|HOW-TO:Modify_the_video_cache}}
<syntaxhighlight lang=xml enclose="div">
<cache>
<memorysize>0</memorysize> 
<buffermode>0</buffermode> 
<readfactor>4.0</readfactor> 
</cache>
</syntaxhighlight>

=== airtunesport ===
{{anchor|.3Cairtunesport.3E}}<section begin="airtunesport" />
This overwrites the defalt listening port of the AirTunes server (announced via zeroconf).
<section end="airtunesport" />

=== airplayport ===
{{anchor|.3Cairplayport.3E}}<section begin="airplayport" />
This overwrites the default listening port of the AirPlay server (announced via zeroconf).
<section end="airplayport" />

== File system settings ==

=== packagefoldersize ===
<section begin="packagefoldersize" />
{{anchor|.3Cpackagefoldersize.3E}}
{{xml setting
| tag name = packagefoldersize
| option type = numerical
| option values =
| default values = 200
| platform = all
| XBMC version = 12
| description = The amount (in megabytes) of add-on zip packages saved from previous add-on installs. These packages are mainly used for the [[Add-ons|add-on]] rollback feature. Increasing the size should increase the amount of past versions saved. Defaults to 200 MB.
| example = Example: <syntaxhighlight lang=xml enclose="div"><packagefoldersize>200</packagefoldersize> </syntaxhighlight>
}}
<section end="packagefoldersize" />

=== detectasudf ===
{{anchor|.3Cdetectasudf.3E}}
Set to true if you wish to detect joint ISO9660/UDF disks as UDF.

Default: False

=== handlemounting ===
{{anchor|.3Chandlemounting.3E}}
Only used in Linux, it defines if Kodi should attempt to mount media drives (via udisks or udisks2).

Default: False. If kodi is executed with the --standalone option (e.g. as done by kodi-standalone.sh) it by default will be True.

=== pathsubstitution ===
{{anchor|.3Cpathsubstitution.3E}}
{{main|Path substitution}}

{{divbox|red||'''Note:''' Path substition for "sources" and profiles is broken, and will '''NOT''' be fixed.}}

Path substitutions are for use for redirecting file paths. These are processed in order, and are useful for substituting an absolute path on a PC with a path suitable for Kodi to handle.

Default: No path substitutions defined.

Example:
<syntaxhighlight lang=xml enclose="div">
<pathsubstitution>
<substitute>
<from>G:\dvds\</from>
<to>smb://somecomputer/g-share/dvds/</to> 
</substitute>
</pathsubstitution>
</syntaxhighlight>

== Input control settings ==

=== remotedelay ===
{{anchor|.3Cremotedelay.3E}}
The repeat delay for a LIRC remote control. A delay value between 1 and 20 before a remote button starts repeating on a long keypress (i.e. continuously sending button pushes while it's held down).

Default: 3
<syntaxhighlight lang=xml enclose="div">
<remotedelay>10</remotedelay>
</syntaxhighlight>

=== controllerdeadzone ===
{{anchor|.3Ccontrollerdeadzone.3E}}
This advanced settings has been removed.
Since v17, the [[Advancedsettings.xml#controllerdeadzone|<controllerdeadzone>]] advanced setting has been removed. Deadzones can now be configured by plugging in the controller and selecting it in Settings -> System settings -> Input -> Peripherals.

=== enablemultimediakeys ===
{{anchor|.3Cenablemultimediakeys.3E}}
This setting only has any effect on Windows versions of Kodi, and only applies to builds from 28th May 2011 onwards.
In Windows the multimedia keys generate a WM_APPCOMMAND message in addition the keypress. Kodi processes both keypresses and the WM_APPCOMMAND messages, and the end result would be that the command is executed twice. To avoid this, by default multimedia keypresses are disabled. Although it should rarely be necessary, the enablemultimediakeys setting allows you to enable the multimedia keys.

Example:
<syntaxhighlight lang=xml enclose="div">
<enablemultimediakeys>true</enablemultimediakeys>
</syntaxhighlight>

=== seeksteps ===
{{Main|Skip steps}}

This setting changes which increments are available in the settings GUI for additive seeking. Note that <code><seeksteps></code> is not used to actually choose which seek steps are enabled.

'''Default:'''
<syntaxhighlight lang=xml enclose="div">
<seeksteps>7, 15, 30, 60, 180, 300, 600, 900, 1800</seeksteps>
</syntaxhighlight>

{{editor note|the defaults need to be updated for seeksteps.}}

=== touchscreen ===
{{anchor|.3Ctouchscreen.3E}}
This setting allows you to move/align the origin of the touch screen with the origin of the display used. If touch input does not result in a correct movement of the mouse pointer, the behaviour can be corrected with an offset and a stretch/compress factor.

Example:
<syntaxhighlight lang=xml enclose="div">
<touchscreen>
<x_offset>0</x_offset> 
<y_offset>0</y_offset> 
<x_stretch_factor>1.0</x_stretch_factor> 
<y_stretch_factor>1.0</y_stretch_factor> 
</touchscreen>
</syntaxhighlight>

=== scanirserver ===
Introduced in v18 and used in MS Windows setups only.<ref>https://github.com/xbmc/xbmc/pull/13896</ref>
Used to disable the regular connection attempts to the IR Server Suite when there is no remote to connect to.

The default setting is to allow connection attempts. To disable connection attempts change value to '''false'''.
<syntaxhighlight lang=xml enclose="div">
<scanirserver>true</scanirserver>
</syntaxhighlight>

== Other interface settings ==

=== window ===
{{anchor|.3Cwindow.3E}}
{{note|This is a "hidden" guisettings.xml setting (defined by the mouse moving the window size), but it is mentioned here because it is a particularly useful override when used in advancedsettings.xml}}
This allows you to manually set the default size of Kodi's windowed mode. If you resize the window, it will return to the set size when restarting.

WIDTH and HEIGHT are the values for each dimension, in pixels.

<syntaxhighlight lang=xml enclose="div">
<window>
<width>WIDTH</width>
<height>HEIGHT</height>
</window>
</syntaxhighlight>

=== restrictcapsmask ===
{{anchor|.3Crestrictcapsmask.3E}}
Windows only. A bitmask to prevent Kodi from using detected texture capabilities of the GPU. This helps work around buggy hardware/drivers.

1: prevent the use of compressed textures (DXT1, DXT3, DXT5)
2: prevent the use of non-power-of-two dimensions for textures
4: prevent the use of compressed textures with non-power-of-two dimensions.

<syntaxhighlight lang=xml enclose="div">
<restrictcapsmask>0</restrictcapsmask>
</syntaxhighlight>

=== algorithmdirtyregions ===
{{anchor|.3Calgorithmdirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="algorithmdirtyregions" />{{note|Some GPU/hardware configurations will have some minor issues (such as a visual "flicker"). For those situations try mode 2 or use the default (mode 3, which requires no advancedsetting). Almost all ARM-based devices (such as [[Android]]) willl likely have flickering issues.}}

Enable dirty-region processing. Dirty regions are any parts of the screen that have changed since the last frame. By not re-rendering what hasn't changed the GUI can be sped up. Because all GPUs work differently, only Mode 3 is guaranteed to work for everyone without flickering issues. This mode will reduce CPU/GPU usage, but will not increase GUI speed.

{| class="prettytable"
! value !! result !! description
|-
! 0
| Off
| The entire viewport is always rendered.
|-
! 1
|Union
|All dirty regions are grouped into the smallest possible rectangle. This is typically the fastest mode for slower GPUs due to only making one pass.
|-
! 2
| {{nowrap|Cost reduction}}
| Each dirty region is presented separately, in as many passes as there are regions.
|-
! 3
| {{nowrap|Whole Screen}}
| The entire screen is rendered if there are any dirty regions. This is a safe default for drivers that clear buffer contents (manifests as blinking or vibrating images). '''Default'''
|}<section end="algorithmdirtyregions" />

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<algorithmdirtyregions>1</algorithmdirtyregions>
</gui>
</syntaxhighlight>

=== visualizedirtyregions ===
{{anchor|.3Cvisualizedirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="visualizedirtyregions" />Enable dirty-region visualization. Paints a rectangle over marked controls.

* true: on
* false: off '''(Default)'''

{{note|This is only a development mode and isn't of use to normal users.}}
<section end="visualizedirtyregions" />
Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<visualizedirtyregions>true</visualizedirtyregions>
</gui>
</syntaxhighlight>

=== smartredraw ===

{{note|This is an experimental feature and you might face issues using it. So please be aware of that.}}

This new feature was introduced in Kodi 18 and if enabled, the GUI process call (and therefore the render call) is only done if anything has changed. The result will be a faster GUI and less load if Kodi plays a video

* true: on
* false: off '''(Default)'''

Example:
<syntaxhighlight lang=xml enclose="div">
<gui>
<smartredraw>true</smartredraw>
</gui>
</syntaxhighlight>

=== showexitbutton ===
{{anchor|.3Cshowexitbutton.3E}}
Setting to hide the exit button, useful for people running appliance based setups where exit would only confuse/complicate the user. Modifiable via the advancedsettings.xml by setting showexitbutton to false, default is true (show)

Example:
<syntaxhighlight lang=xml enclose="div">
<showexitbutton>true</showexitbutton>
</syntaxhighlight>

=== fullscreen ===
{{anchor|.3Cfullscreen.3E}}
Starts Kodi in full screen (check resolutions!).

<syntaxhighlight lang=xml enclose="div">
<fullscreen>false</fullscreen>
</syntaxhighlight>

=== splash ===
{{anchor|.3Csplash.3E}}
Set to false if you wish to disable the startup splash image. Defaults to true.

<syntaxhighlight lang=xml enclose="div">
<splash>true</splash>
</syntaxhighlight>

=== cputempcommand ===
{{anchor|.3Ccputempcommand.3E}}
Provide a shell command Kodi will use to get CPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia and Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sed -e 's/$[0-9]*$[0-9]\{3\}.*/\1 C/' /sys/class/thermal/thermal_zone0/temp</cputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>echo "$(sensors -u | tail -n64 | grep temp1_input | awk '{print $2 }' |awk '{printf("%d\n",$1 + 0.5);}') C"</cputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<cputempcommand>sensors|sed -ne "s/temp1: \+[-+]$[0-9]\+$.*/\1 C/p"</cputempcommand>
</syntaxhighlight>

=== gputempcommand ===
{{anchor|.3Cgputempcommand.3E}}
Provide a shell command Kodi will use to get GPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-settings -tq gpuCoreTemp) C"</gputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>echo "$(nvidia-smi -q -d TEMPERATURE | grep Gpu | cut -c35-36) C"</gputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/usr/bin/aticonfig --od-gettemperature | grep Temperature | cut -f 2 -d "-" | cut -f 1 -d "." | sed -e "s, ,," | sed 's/$/ C/'</gputempcommand>
</syntaxhighlight>

;<u>For Raspberry Pi</u>
<syntaxhighlight lang=xml enclose="div">
<gputempcommand>/opt/vc/bin/vcgencmd measure_temp | sed -e "s/temp=//" -e "s/\..*'/ /"</gputempcommand>
</syntaxhighlight>

=== glrectanglehack ===
{{anchor|.3Cglrectanglehack.3E}}
Problems with ghosting or videos which are only played back in the left upper quarter? The following ATI hack may solve it.
<syntaxhighlight lang=xml enclose="div">
<glrectanglehack>yes</glrectanglehack>
</syntaxhighlight>

=== alwaysontop ===
{{anchor|.3Calwaysontop.3E}}
Added in XBMC v9.11 (Windows OS only). Keeps Kodi always on top when windowed.
<syntaxhighlight lang=xml enclose="div">
<alwaysontop>yes</alwaysontop>
</syntaxhighlight>

There is also a fake fullscreen GUI option in Kodi's settings.

=== minimizetotray ===
{{anchor|.3Cminimizetotray.3E}}
{{note|Available in Kodi v20 and above.}}

Windows only. Minimizes Kodi to the system tray. Defaults to false.
<syntaxhighlight lang=xml enclose="div">
<minimizetotray>true</minimizetotray>
</syntaxhighlight>

= Removed tags =
{{anchor|Recently removed tags}}
* {{anchor|.3Cthumbsize.3E}}'''<thumbsize>''' - replaced by <[[#imageres|imageres]]> in v12 Frodo
* {{anchor|.3Cfanartheight.3E}}'''<fanartheight>''' - replaced by <[[#fanartres|fanartres]]> in v12 Frodo
* {{anchor|.3Cdvdthumbs.3E}}'''<dvdthumbs>''' - removed in v12 Frodo
* {{anchor|.3Cbusydialogdelayms.3E}}'''<busydialogdelayms>''' - removed in v12 Frodo
* {{anchor|.3Cbginfoloadermaxthreads.3E}}'''<bginfoloadermaxthreads>''' - removed in v13 Gotham
* '''<showepginfoonselect>''' - replaced by a GUI setting in v13 Gotham
* '''<resample>''', '''<forceDirectSound>''', '''<audiophile>''', '''<audiosinkbufferdurationmsec>''', '''<allowtranscode44100>''', and '''<streamsilence>''' - These were various sub-tags for <audio> that were removed in v13 Gotham and either replaced by GUI settings or were no longer needed.
* {{anchor|.3Cenableairtunesdebuglog.3E}}'''<enableairtunesdebuglog>''' - replaced by a GUI option in v14 Helix
* '''<videoDisableHi10pMultithreading>''' - renamed to <disableswmultithreading> in v14 Helix
* '''<hideallitems>''' - For both the <code><videolibrary></code> and <code><musiclibrary></code> sections, this is replaced by a GUI option in v15 Isengard
* '''<SmallStepBackSeconds>''' - In v15 the <code>SmallStepBack</code> [[Action_IDs]] has been replaced by <code>seek(-7)</code> in default keymaps. See '''[[skip steps]]''' for details. When the original <code>SmallStepBack</code> action ID is used it defaults to the first backwards [[skip steps|additive seeking value]].
* '''<timeseekforward>/<timeseekbackward>''' - In v15 these tags are replaced by GUI options via [[skip steps|additive seeking]], which is configured in the GUI. See '''[[skip steps]]''' for details.
* {{anchor|.3Ckaraoke.3E}}'''<karaoke>''' - In v16 all of the karaoke features in Kodi were removed.
* '''<useddsfanart>''' - removed in v17 Krypton.
* '''<cachemembuffersize>''' and '''<readbufferfactor>''' - In v17 '''<cachemembuffersize>''' is renamed to '''<memorysize>''' and <code><readbufferfactor></code> is renamed to <code><readfactor></code>. In addition, all three buffer related settings in <network> are moved out of <network> and into a new <cache> parent tag.
* '''<minvideocachelevel>''', '''<minaudiocachelevel>''', and '''<cacheindvdplayer>''' have been removed in v17.
* '''<useffmpegvda>''' - Tag was only used for development testing. Removed in v17.
* '''<nofliptimeout>''' - Removed in v17
* '''<blackbarcolour>''' - Removed in v17 (maybe?)
* '''<disableswmultithreading>''' - Removed in v17 (maybe?)
* {{anchor|.3Cmeasurerefreshrate.3E}}'''<measurerefreshrate>''' - Removed in v17 or v18?
* {{anchor|.3Cmyth.3E}}'''<myth>''' - Removed sometime between v16 to v18
* {{anchor|.3Ctuxbox.3E}}'''<tuxbox>''' - Removed
* '''<backgroundupdate>''' - Removed
* '''<hideemptyseries>''' - Replaced by a GUI option.
* '''<mymovies>''' and child tag '''<categoriestogenres>''' - Removed
* '''<albumssortbyartistthenyear'''> - Removed
* '''<albumformatright>''' - Removed
* {{anchor|.3Cremoterepeat.3E}}'''<remoterepeat>''' - Removed
* {{anchor|.3Callowd3d9ex.3E}}'''<allowd3d9ex>''' and {{anchor|.3Cforced3d9ex.3E}}'''<forced3d9ex>''' - Removed sometime between v16 to v18
* '''<lingertime>''' - Replaced by a GUI setting in v18
* '''<forcevaapienabled>''' - Removed in v18
* '''<promptfulltagscan>false</promptfulltagscan>''' Removed in v18. Now automatically asked each time a scan is conducted.
* '''<controllerdeadzone>''' - Removed in v17
* '''<omxdecodestartwithvalidframe>''' - This tag is only in some Raspberry Pi specific distributions, such as OpenELEC. As of March 2015, this tag has not been merged into "vanilla" Kodi builds
* '''<musicthumbs>''' Replaced in v19 by the GUI setting '''Thumbnail image files''' found in Media -> Music
* '''<artistextraart>''' Replaced in v19 by the GUI setting '''Artist art types whitelist''' found in Media -> Music
* '''<albumextraart>''' Replaced in v19 by the GUI setting '''Album art types whitelist''' found in Media -> Music
* '''<fanart>''' Removed in v19
* '''<assfixedworks>''' Removed in v20

= guisettings.xml Setting Conversion =
It is possible to convert settings found in the '''[[Settings]]''' ''(guisettings.xml)'' pages of {{kodi}} into entries for the advancedsettings.xml file.

When a setting from the guisettings.xml is added to the advancedsettings.xml file, it will override the existing guisettings.xml values and the setting will be removed from the settings pages.

Why would I need to do this?
* You set up multiple devices and then need to individually change settings and preferences on each device. Using this conversion method, you save those settings in the advancedsettings.xml file and simply add the file to each device
* You need to hide settings to prevent those settings from being modified

To convert a guisetting to advancedsettings.xml follow these steps:
# In the {{kodi}} settings pages, adjust the setting(s) to your preference.
# Back out of the settings pages to the main menu, which forces {{kodi}} to save the adjusted settings to the guisettings.xml file
# Locate the guisettings.xml file in the [[Userdata]] folder and open it
# Locate the setting(s) to be converted. The list can be overwhelming so make use of the Search feature of whichever editor you are using
# Using the following setting as an example:
<syntaxhighlight lang="xml">
<setting id="videolibrary.showemptytvshows">true</setting>
</syntaxhighlight>
: Breaking down the string:
::'''videolibrary'''- parent tag
::'''showemptytvshows'''- child tag
::'''true'''- value
: The conversion is as follows and place this in the advancedsettings.xml file
<syntaxhighlight lang="xml">
<advancedsettings version="1.0">
<videolibrary>
<showemptytvshows>true</showemptytvshows>
</videolibrary>
</advancedsettings>
</syntaxhighlight>

'''Note:''' Some parent tags may already be in use in your advancedsettings.xml file. Do not duplicate them, but add the child tag beneath the existing parent tag.

= References =
<references />

{{Updated|18}}
{{DISPLAYTITLE:advancedsettings.xml}}

[[Category:Advanced topics]]
[[Category:Manual]]
[[Category:Settings]]

PulseAudio

2019-10-01T13:00:14Z

Fritsch: /* Audiophile Pulse User */

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation, in order to get 7.1 audio Multichannel Mode must be used}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync. In the case of video with TrueHD/DTS-HD 7.1 audio this must be decoded by Kodi to Multichannel PCM by disabling passthrough, then Pulseaudio can handle the 7.1 channels of audio.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". As Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always an exclusive mode. If you have another application hogging the device, e.g. Chrome or Skype, passthrough won't work. Even applications that simply monitor the device, such as SoundWireServer, will prevent passthrough from working.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate passthrough codecs, setup pavucontrol as following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, first, first identify the correct sound card ID:
'''pacmd list-cards'''

Look at the output to find the id of the card and the name/format of the profile you want to use (in this case, card ID is '''0''' and profile is '''output:hdmi-stereo''')
Once you've identified this information, set your output profile to the one for hdmi-stereo:
'''pacmd set-card-profile 0 output:hdmi-stereo'''

Then, obtain the sink ID you want to set formats on by inspecting output of:
'''pactl list sinks'''

Then set the sink format for the sink you want, as below (in this case '''0'''):
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

{{redv|'''IMPORTANT:'''| Enabling ''' Sync Playback to Display ''' will disable passthrough silently, as it makes zero sense to sync with a display clock while one cannot alter audio.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PulseAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second avoid resampling. Starting with version 11 of pulseaudio, it can reopen sinks with their native samplerate. Furthermore you need to take care, that your sink has a wide enough output format. To properly resample samperates that are not available with your sound card, e.g. 176000 or other exotic rates, we set pulseaudio to a default of 44100 khz, which is the default for every standard mp3. As alternate sample-rate we suggest 48000. That means that all non available samplerates are resampled with an exact integer division of src_rate / dst_rate.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s24le
default-sample-rate = 44100
alternate-sample-rate = 48000
;new with pulseaudio 11
avoid-resampling = true
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|Doing so may cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>pasuspender -- env AE_SINK=ALSA kodi</pre> (starting with v18 this option was renamed to '''KODI_AE_SINK=ALSA''')

'''pasuspender''' is a tool that can be used to tell a local PulseAudio sound server to temporarily suspend access to the audio devices, to allow other applications access them directly. pasuspender will suspend access to the audio devices, fork a child process, and when the child process terminates, resume access again.

You can also put the previous command in a custom .desktop-file.

Be warned as this will interfere with your Desktop sounds!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

Audio devices are disappearing with pulseaudio 8.0 (Ubuntu 16.04, even later version are affected) especially while running kodi and while using ''Adjust Refreshrate to match video''. This is an issue with the module-switch-on-port-available module and will be fixed with pulseaudio 9.0, the fix sadly won't probably make it into Ubuntu 16.04. As a workaround please disable that feature by editing /etc/pulse/default.pa and commenting or removing ''load-module module-switch-on-port-available'' and reboot the system.

''' Kodi v16 '''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

''' Kodi v17 '''

Starting with the upcoming kodi v17 Krypton the above behaviour is taken care within kodi. You don't have to disable remixing in pulseaudio anymore. That means content is output without further remixing by pulseaudio server if a sane mapping is possible. Basically that means if the audio is FL, FR, FC, LFE, SL, SR and your speaker-mapping is FL, FR, FC, LFE, BL, BR we will resolve that and output 6 channels accordingly. Whenever we cannot map all input channels to the output we ask pulseaudio to do the mixing for us.

''' Volume issues '''

Issue: Changing kodi's volume will change overall system volume, especially on song change this is an irritating behaviour. The effect you hear is not done by kodi, but by a systemwide pulseaudio (mis)configuration. Some distributions sadly still ship pulseaudio with '''flat-volumes = yes''' as the default, which produces this behaviour. In fact it will cause the hardware volume (or master volume) to go up and down for every pulseaudio stream that changes its own volume. As this effect is unexpected behaviour for users, distributions started to ship pulseaudio with '''flat-volumes = no''' by default (as time of writing this is Ubuntu, Arch-Linux and others). In order to change that setting, depending on your distribution edit ''/etc/pulse/daemon.conf'' and set '''flat-volumes = no'''. After a PA server restart, the volume handling is more intuitive. If you are at it, please inform your distribution about those issues, so that they can ship a more user-friendly default with next release. At the time of writing, affected distributions: Debian.

== HOW-TO ==

====[[PulseAudio/HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu|HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu]]====

== References ==
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2019-10-01T12:59:50Z

Fritsch: /* Audiophile Pulse User */

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation, in order to get 7.1 audio Multichannel Mode must be used}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync. In the case of video with TrueHD/DTS-HD 7.1 audio this must be decoded by Kodi to Multichannel PCM by disabling passthrough, then Pulseaudio can handle the 7.1 channels of audio.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". As Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always an exclusive mode. If you have another application hogging the device, e.g. Chrome or Skype, passthrough won't work. Even applications that simply monitor the device, such as SoundWireServer, will prevent passthrough from working.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate passthrough codecs, setup pavucontrol as following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, first, first identify the correct sound card ID:
'''pacmd list-cards'''

Look at the output to find the id of the card and the name/format of the profile you want to use (in this case, card ID is '''0''' and profile is '''output:hdmi-stereo''')
Once you've identified this information, set your output profile to the one for hdmi-stereo:
'''pacmd set-card-profile 0 output:hdmi-stereo'''

Then, obtain the sink ID you want to set formats on by inspecting output of:
'''pactl list sinks'''

Then set the sink format for the sink you want, as below (in this case '''0'''):
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

{{redv|'''IMPORTANT:'''| Enabling ''' Sync Playback to Display ''' will disable passthrough silently, as it makes zero sense to sync with a display clock while one cannot alter audio.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PulseAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second avoid resampling. Starting with version 11 of pulseaudio, it can reopen sinks with their native samplerate. Furthermore you need to take care, that your sink has a wide enough output format. To properly resample samperates that are not available with your sound card, e.g. 176000 or other exotic rates, we set pulseaudio to a default of 44100 khz, which is the default for every standard mp3. As alternate sample-rate we suggest 48000. That means that all non available samplerates are resampled with an exact integer division of src_rate / dst_rate.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s24le
default-sample-rate = 44100
alternate-sample-rate = 48000
'''avoid-resampling = true''' ; new with pulseaudio 11
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|Doing so may cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>pasuspender -- env AE_SINK=ALSA kodi</pre> (starting with v18 this option was renamed to '''KODI_AE_SINK=ALSA''')

'''pasuspender''' is a tool that can be used to tell a local PulseAudio sound server to temporarily suspend access to the audio devices, to allow other applications access them directly. pasuspender will suspend access to the audio devices, fork a child process, and when the child process terminates, resume access again.

You can also put the previous command in a custom .desktop-file.

Be warned as this will interfere with your Desktop sounds!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

Audio devices are disappearing with pulseaudio 8.0 (Ubuntu 16.04, even later version are affected) especially while running kodi and while using ''Adjust Refreshrate to match video''. This is an issue with the module-switch-on-port-available module and will be fixed with pulseaudio 9.0, the fix sadly won't probably make it into Ubuntu 16.04. As a workaround please disable that feature by editing /etc/pulse/default.pa and commenting or removing ''load-module module-switch-on-port-available'' and reboot the system.

''' Kodi v16 '''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

''' Kodi v17 '''

Starting with the upcoming kodi v17 Krypton the above behaviour is taken care within kodi. You don't have to disable remixing in pulseaudio anymore. That means content is output without further remixing by pulseaudio server if a sane mapping is possible. Basically that means if the audio is FL, FR, FC, LFE, SL, SR and your speaker-mapping is FL, FR, FC, LFE, BL, BR we will resolve that and output 6 channels accordingly. Whenever we cannot map all input channels to the output we ask pulseaudio to do the mixing for us.

''' Volume issues '''

Issue: Changing kodi's volume will change overall system volume, especially on song change this is an irritating behaviour. The effect you hear is not done by kodi, but by a systemwide pulseaudio (mis)configuration. Some distributions sadly still ship pulseaudio with '''flat-volumes = yes''' as the default, which produces this behaviour. In fact it will cause the hardware volume (or master volume) to go up and down for every pulseaudio stream that changes its own volume. As this effect is unexpected behaviour for users, distributions started to ship pulseaudio with '''flat-volumes = no''' by default (as time of writing this is Ubuntu, Arch-Linux and others). In order to change that setting, depending on your distribution edit ''/etc/pulse/daemon.conf'' and set '''flat-volumes = no'''. After a PA server restart, the volume handling is more intuitive. If you are at it, please inform your distribution about those issues, so that they can ship a more user-friendly default with next release. At the time of writing, affected distributions: Debian.

== HOW-TO ==

====[[PulseAudio/HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu|HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu]]====

== References ==
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

Kodi v18 (Leia) changelog

2018-12-11T19:34:43Z

Fritsch: /* AudioEngine */

{{mininav|[[Releases]] {{l2| [[Leia]] }} }}

{{notice|Kodi's journey via non-alpha/beta v18 (Leia) releases is currently underway. As such, these new features/functions and API changes is a placeholder containing changes to the current Kodi mainline (the git master tree repository on GitHub). This is listing changes committed to the master branch after Krypton branching. The many features/functions and API additions, alterations or removal are only subject to change during the Alpha stages. The Beta stage is all about stability and bug fixing. }}
{{incomplete}}
{{future|18}}

{{see also|Kodi v18 (Leia) FAQ|Leia API changes|Releases}}

This is the Kodi Wiki version of a condensed changelog for the future Kodi v18.x version (codename: "Leia") releases with a summary of the most important core features and functions as well as other notable changes to key areas of the application software or its user interface. Please note that this condensed changelog version is not meant bug-fixes, nor minor refactoring or cosmetic changes.

== Changelog ==

=== Gaming (Games interface and Game Clients)===
Note! Also see "Input System (Input Manager and Input APIs" section for Input System related to game controllers
* Added a "[[Games]]" window to GUI (games are managed using a basic file browser as a game library does not exist yet)
* Added a RetroPlayer player core supporting [[Game_Add-ons|game clients addons]] as well as emulator cores via [[libretro]] API<ref name="RetroPlayer">RetroPlayer http://forum.kodi.tv/showthread.php?tid=164725</ref><ref>http://github.com/xbmc/xbmc/pull/11022</ref>
* Added extentions to Kodi's Addons AP to support Game Client Addons, supporting Kodi's VFS (Virtual File System), etc.<ref name="RetroPlayer"/>
* Added support for Game Client Addons as new type of addons with just-in-time emulator installation<ref name="RetroPlayer"/>
* Added a Games window and Game OSD (On-Screen-Display) entries to the GUI<ref name="RetroPlayer"/><ref>https://github.com/xbmc/xbmc/pull/12367</ref>
* Added a gaming and game configuration interface for Game settings to the GUI<ref name="RetroPlayer"/>
* Added support for Game Info Tags (game info tag) and exposed properties to Python list items<ref name="RetroPlayer"/>
* Added a savestate (savestate) manager to Kodi for games<ref>http://github.com/xbmc/xbmc/pull/11034</ref>
* Added initial support for basic gameplay persistence (auto-save & auto-load)<ref>https://github.com/xbmc/xbmc/pull/12434</ref>
* Added support for in-game (save RAM) saves<ref>http://github.com/xbmc/xbmc/pull/11380</ref>
* Added support for Keyboard players via Joystick Emulation<ref name="RetroPlayer"/>
* Added Game API acbstraction for game controller multitaps (a.k.a. hubs) including topology GUI display<ref>https://github.com/xbmc/xbmc/pull/13499</ref>
* Added Game API acbstraction to support gamepad/joystick remapping for games (per game-addon)
* Added Game API acbstraction to support keyboard remapping for games (per game-addon)<ref>https://github.com/xbmc/xbmc/pull/13374</ref>
* Added Game API acbstraction to support mouse remapping for games (per game-addon)<ref>https://github.com/xbmc/xbmc/pull/13482</ref>
* Added support for libretro API and game cores (emulators and games) that support it as binary addons
* Added [[Game_Add-ons|game clients addons]] for many popular third-party game console emulators and native open source games *
** ''* [[Game_Add-ons|Game clients addons]] for Kodi is changing quickly so checkout the [[Game_Add-ons|game clients addons]] article for a current list''
* ?

=== Live TV and PVR (Personal Video Recorder) ===
* Added support for RDS (Radio Data System) for radio channels if the PVR backend client support RDS
* Added new settings for 'Startup action' and add 'Play TV/Radio <ref>https://github.com/xbmc/xbmc/pull/12548</ref>
* Added support for global direct channel number input & global unique channel numbers<ref>https://github.com/xbmc/xbmc/pull/13135</ref><ref>https://github.com/xbmc/xbmc/pull/11434</ref>
** Added support for no delay on switch to previous channel with key 0 when using direct channel number input<ref>https://github.com/xbmc/xbmc/pull/13232</ref>
* Added context menu support for Estuary (skin) PVR home screen widgets <ref>https://github.com/xbmc/xbmc/pull/10870</ref>
* Added percent played progress bar to PVR info panel (for recordings) in Estuary (skin)<ref>https://github.com/xbmc/xbmc/pull/13338</ref>
* Added Info support to recently played channel widget to Estuary (skin) home screen <ref>https://github.com/xbmc/xbmc/pull/12254</ref>
* Added episode name to Live TV, recordings OSD sub label, and cleanup seekbar for Live TV in Estuary (skin) <ref>https://github.com/xbmc/xbmc/pull/12306</ref>
* Added Season/Episode info in Guide window and dialog in Estuary (skin)<ref>https://github.com/xbmc/xbmc/pull/13300</ref>
* Added support for next and previous buttons in OSD Timeshift window<ref>https://github.com/xbmc/xbmc/pull/14387</ref>
* Added feature to prefill recordings folder with timer title in the timer settings dialog<ref>https://github.com/xbmc/xbmc/pull/11679</ref>
* Added support for radio channel groups to the channelgroup manager<ref>https://github.com/xbmc/xbmc/pull/11877</ref>
* Added support for a 'Smart selection' of EPG events feature to the guide window<ref>https://github.com/xbmc/xbmc/pull/11782</ref>
* Added 'Go to date' context menu item to the guide window<ref>https://github.com/xbmc/xbmc/pull/13282</ref>
* Added support for channel groups selector to the guide window<ref>https://github.com/xbmc/xbmc/pull/13364</ref>
* Added possibility to switch between horizontal and vertical epg grid view to the guide window <ref>https://github.com/xbmc/xbmc/pull/11958</ref>
* Added support to sort content by channel number/channel name/last played, support sort order to the Guide window<ref>https://github.com/xbmc/xbmc/pull/14231</ref>
* Added support next/previous chapter in PVR recordings<ref>https://github.com/xbmc/xbmc/pull/13164</ref>
* Improved PVR seekbar and info dialog in Estuary (skin) <ref>https://github.com/xbmc/xbmc/pull/13158</ref>
* Improved PVR info panel, info dialog, and recordings window in Estuary (skin)<ref>https://github.com/xbmc/xbmc/pull/12416</ref><ref>https://github.com/xbmc/xbmc/pull/13255</ref>
* Improved support for enabling multiple PVR client addons<ref>https://github.com/xbmc/xbmc/pull/12959</ref>
* Improved support for for subchannel numbers support (ATSC)<ref>https://github.com/xbmc/xbmc/pull/13069</ref>
* Improved OSD Timeshift GUI<ref>https://github.com/xbmc/xbmc/pull/14316</ref><ref>https://github.com/xbmc/xbmc/pull/14386</ref>
* Improved the guide window for better consistency and readability <ref>https://github.com/xbmc/xbmc/pull/13402</ref>
* Changed GUI actions to eliminate duplicate and dead code (major GUI refactoring for PVR and LiveTV)
* Changed implementation of EPG search filter (EPG search dialog) completely<ref>https://github.com/xbmc/xbmc/pull/11570</ref><ref>https://github.com/xbmc/xbmc/pull/12001</ref>
* Changed Guide Window removing obsolete views "channel", "now" and "next"<ref>https://github.com/xbmc/xbmc/pull/10838</ref>
* Changed "play minimized" settings handling <ref>https://github.com/xbmc/xbmc/pull/11203</ref>
* Changed 'epg.lingertime' to an official setting, remove the respective advanced setting<ref>https://github.com/xbmc/xbmc/pull/12740</ref>
* Changed shared channel selection into an optional setting<ref>https://github.com/xbmc/xbmc/pull/13237</ref>
* Removed obsolete and unused setting 'pvrplayback.scantime' <ref>https://github.com/xbmc/xbmc/pull/12800</ref>
* Removed channel guide button from EPG event info dialog, add 'channel guide' to context menu<ref>https://github.com/xbmc/xbmc/pull/12526</ref>
* Removed setting 'hide connection lost warning' <ref>https://github.com/xbmc/xbmc/pull/11500</ref>
* Removed non-working recording settings defaults <ref>https://github.com/xbmc/xbmc/pull/11746</ref>
* Recordings window: Content view filter <ref>https://github.com/xbmc/xbmc/pull/11704</ref>
* PVR-Addon API changes <ref>https://github.com/xbmc/xbmc/pull/12028</ref><ref>https://github.com/xbmc/xbmc/pull/12303</ref><ref>https://github.com/xbmc/xbmc/pull/12552</ref><ref>https://github.com/xbmc/xbmc/pull/12609</ref><ref>https://github.com/xbmc/xbmc/pull/12660</ref><ref>https://github.com/xbmc/xbmc/pull/12689</ref><ref>https://github.com/xbmc/xbmc/pull/12755</ref><ref>https://github.com/xbmc/xbmc/pull/13228</ref><ref>https://github.com/xbmc/xbmc/pull/13720</ref><ref>https://github.com/xbmc/xbmc/pull/14002</ref><ref>https://github.com/xbmc/xbmc/pull/14086</ref>
* Added, updated, and improved PVR backend clients addons for popular third-party external [[PVR backend]] platforms:
** New: [[Add-on:Zattoo PVR Client|Zattoo PVR Client]] PVR Addon backend client maintained and available from Kodi's community
** New: [[Add-on:Teleboy PVR Client|Teleboy PVR Client]] PVR Addon backend client maintained and available from Kodi's community
** New: [[Add-on:Sledovanitv.cz PVR Client|Sledovanitv.cz PVR Client]] PVR Addon backend client maintained and available from Kodi's community
** [[Add-on:PVR Demo Client|PVR Demo Client]] dummy addon with fake (method stub) [[PVR backend]] for [[PVR]] skinning and regression testing
** [[Add-on:IPTV Simple Client|IPTV Simple Client]] PVR Addon backend client maintained and available from Kodi's community
** [[Add-on:FilmOn PVR Client|FilmOn]] PVR Addon backend client maintained and available from Kodi's community
** [[Add-on:Stalker Client|Stalker Middleware]] PVR Addon backend client maintained and available from Kodi's community
** [[Add-on:HDHomeRun PVR|HDHomeRun]] PVR Addon backend client maintained and available from Kodi's community
** [[Add-on:Digital Devices Octopus NET Client|Digital Devices Octopus NET Client]] PVR Addon backend client maintained and made available by [http://digitaldevices.de/home/ Digital Devices]
** [[Add-on:VU+ / Enigma2 Client|Enigma2 (Dreambox / Vu+ / DBox2)]] PVR Addon backend client maintained and available from Kodi's community
** [[Add-on:VBox TV Gateway PVR Client|VBox TV Gateway]] PVR Addon backend client maintained and available from Kodi's community
** [[Add-on:Njoy N7 PVR Client|Njoy Digital (N7)]] PVR Addon backend client maintained and available from Kodi's community
** [[Add-on:PCTV Systems Client|PCTV Systems (Broadway)]] PVR Addon backend client maintained and available from Kodi's community
** [[Add-on:Tvheadend HTSP Client|Tvheadend HTSP Client]] PVR Addon backend client maintained and available from Kodi's community
** [[Add-on:VDR VNSI Client|VDR VNSI Client]] PVR Addon backend client maintained and available from Kodi's community
** [[Add-on:MythTV PVR Client|MythTV PVR Client]] Addon backend client maintained and available from the Kodi's community
** [[Add-on:NextPVR PVR Client|NextPVR (former GB-PVR)]] PVR Addon backend client maintained and available from Kodi's community
** [[Add-on:Argus TV Client|Argus TV (former ForTheRecord)]] PVR Addon backend client maintained and available from Kodi's community
** [[Add-on:DVBLink PVR Client|DVBLink PVR Client]] Addon backend client maintained and available from Kodi's community
** [[Add-on:DVBViewer Client|DVBViewer Client]] PVR Addon backend client maintained and available from Kodi's community
** [[Add-on:MediaPortal PVR Client|MediaPortal PVR Client]] Addon backend client maintained and available from Kodi's community
** [[Add-on:PVR.WMC|WMC (Windows Media Center)]] PVR Addon backend client maintained and available from Kodi's community
* ?

=== Add-ons Framework, API, and Manager ===
For full changelogs of all Addons APIs, see [[Leia API changes]], [https://forum.kodi.tv/showthread.php?tid=324598 JSON-RPC], and [http://forum.kodi.tv/forumdisplay.php?fid=26 Add-ons] Development Forums
* Implemented a Python 3 interpreter inside Kodi (plus enforcing Python 2 & 3 compatibility in Leia addon repository)<ref>https://kodi.tv/article/attention-addon-developers-migration-python-3</ref>
* Implemented online binary addon repository from which Kodi can now automatically installs/updates binary addon<ref>https://kodi.tv/article/kodi-v18-binary-add-ons-repository</ref><ref>https://github.com/xbmc/repo-binary-addons</ref>
* Major refactoring of Kodi's core handling and GUI management of binary addons<ref>http://github.com/xbmc/xbmc/pulls?q=label%3A%22Binary+Addons%22+is%3Aclosed</ref>
* Added framework to support VFS (Virtual File System) as binary addons<ref>http://github.com/xbmc/xbmc/pull/8966</ref>
* Added framework support for binary addons for video decoder codecs<ref name="Addon video codec implementation">https://github.com/xbmc/xbmc/pull/12340</ref>
* Added framework support for binary addons for image (picture) decoder codecs
* Added extentions to Kodi's Addons API to support binary addons for video decoder codecs<ref name="Addon video codec implementation"/>
* Added extentions to Kodi's Addons API to support binary addons for image decoder codecs
* Added support for Python addons to use PyCryptoDome crypto module for decryption<ref>https://github.com/xbmc/xbmc/pull/11477</ref>
* Added option to pass HTTP cookies with AVOption to Kodi's Video Player<ref>https://github.com/xbmc/xbmc/pull/12257</ref>
* Added support to allow addons to edit all used controls on their processed window<ref>https://github.com/xbmc/xbmc/pull/12259</ref>
* Added support to allow Python addons to set the videoinfotag path<ref>http://github.com/xbmc/xbmc/pull/11012</ref>
* Added support to allow Python addons to get/set the dbid of a (music) listitem<ref>http://github.com/xbmc/xbmc/pull/10858</ref>
* Added support for mediatype to musicinfotag tag retrieving via Python API<ref>http://github.com/xbmc/xbmc/pull/11110</ref>
* Added support "int/float slider" to Kodi's Python API<ref>http://github.com/xbmc/xbmc/pull/11230</ref>
* Added support "setContent for mediawindows" to Kodi's Python API<ref>http://github.com/xbmc/xbmc/pull/11258</ref>
* Added help for load of shared library and allow the use of their own addon temp folder<ref>https://github.com/xbmc/xbmc/pull/12379</ref>
* Added support to inspect add-on dependencies prior to installation<ref>https://github.com/xbmc/xbmc/pull/12242</ref>
* Added ability to remove add-on settings upon uninstall<ref>https://github.com/xbmc/xbmc/pull/11499</ref>
* Changed to new addon gui interface for list items to use on addon window<ref>https://github.com/xbmc/xbmc/pull/12214</ref>
* Changed service addons to use event handlers instead of synchronous addon hooks<ref>https://github.com/xbmc/xbmc/pull/12370</ref>

=== Input System (Input Manager and Input APIs) ===
* Improved the input manager and input API system for keyboards, mouses, and game controllers<ref name="Controller input system">PR #8807 Controller input system http://github.com/xbmc/xbmc/pull/8807</ref>
* Updated "Peripheral Addons" for game controllers, gamepads, joysticks, and input peripherals profiles (in Kodi-game repo<ref>http://github.com/kodi-game/ kodi-game repo on GitHub</ref>):
** [http://github.com/xbmc/peripheral.joystick Joystick Controller Addon]
** [http://github.com/kodi-game/peripheral.xarcade X-Arcade (XGaming Tankstick) support for Kodi Addon]
** [http://github.com/kodi-game/peripheral.steamcontroller Steam Controller (gamepad) Addon]
** [http://github.com/kodi-game/kodi-game-controllers/tree/master/addons/game.controller.default Default Game Controller Addon (reference game controller addon based on Xbox 360 gamepad)]
*** [https://github.com/kodi-game/controller-topology-project/tree/master/addons PlayStation Game Controller Addon]
*** [https://github.com/kodi-game/controller-topology-project/tree/master/addons Nintendo NES Game Controller Addon]
*** [https://github.com/kodi-game/controller-topology-project/tree/master/addons Nintendo SNES Game Controller Addon]
*** [https://github.com/kodi-game/controller-topology-project/tree/master/addons Nintendo N64 Game Controller Addon]
*** [https://github.com/kodi-game/controller-topology-project/tree/master/addons Nintendo GBA Game Controller Addon]
*** [https://github.com/kodi-game/controller-topology-project/tree/master/addons Sega Genesis Game Controller Addon]
*** [https://github.com/kodi-game/controller-topology-project/tree/master/addons Sega Dreamcast Game Controller Addon]
* ?

=== GUI Engine (Skinning Engine) ===
For full changelog on changes to the skinning engine, see [[Leia API changes]] and the [http://forum.kodi.tv/showthread.php?tid=298565 Skin Development Forum]
* Added windows to support Games and Game OSD in the new default skins (Estuary and Estouchy)
* Added player process info dialog to Kodi's default skin (Estuary)<ref>https://github.com/xbmc/xbmc/pull/11718</ref>
* Added support for addons to use banner and ClearLogo<ref>https://github.com/xbmc/xbmc/pull/12244</ref>
* Added support for skins/gui to allow implicit container referencing for non-media windows<ref>http://github.com/xbmc/xbmc/pull/10883</ref>
* Added support for addons to add "Enable/Disable" to context menu<ref>http://github.com/xbmc/xbmc/pull/11124</ref>
* Added support for remember last used keyboard layout in GUI<ref>http://github.com/xbmc/xbmc/pull/11242</ref>
* Added support for ISO 639-2/T language code retrieval (required by libbluray)<ref>https://github.com/xbmc/xbmc/pull/12258</ref>
* Added window that display Kodi privacy policy in GUI settings under system info<ref>https://github.com/xbmc/xbmc/pull/10785</ref>
* Added support to map a key to browse for subtitle in video fullscreen window<ref>https://github.com/xbmc/xbmc/pull/11649</ref>
* Improved Kodi's GUI engine with optimizations for message handling and SmartRedraw<ref>https://github.com/xbmc/xbmc/pull/12213</ref>
* Improved Kodi's GUI engine support for scaling container layouts<ref>http://github.com/xbmc/xbmc/pull/11229</ref>
* Improved Kodi's GUI engine by allowing %-values for origin, camera and animation attribs<ref>http://github.com/xbmc/xbmc/pull/11233</ref>
* Changed so that context menu reloading loads async to aviod GUI lockup on wait<ref>https://github.com/xbmc/xbmc/pull/11841</ref>
* Updated guilib ABI (for libgui) to version 5.13.0<ref>http://github.com/xbmc/xbmc/pull/11306</ref>
* Updated keyboard layout for some languages and added support Croatian, Slovenian, and Thai (Kedmanee)
* Updated image resource addons (as example weather icons, weather fanart, studio logos, and genre icons)
* ?

=== Platform Independent Playback ===
* Added support for "InputStream" (input stream) addons to pass CryptoSession flags field<ref>https://github.com/xbmc/xbmc/pull/12428</ref>
* Added support for BD-J / Blu-ray Disc Java menu support (requires system Java runtime enviroment)<ref>https://github.com/xbmc/xbmc/pull/12339</ref><ref>https://github.com/xbmc/xbmc/pull/12310</ref>
* Added support for Blu-ray Disc detection and use provided meta data for Blu-ray Disc names<ref>https://github.com/xbmc/xbmc/pull/12488</ref>
* Added support for video buffers to be used by decoders and renderers<ref name="VideoPlayer updates for Leia">https://github.com/xbmc/xbmc/pull/12212</ref>
** Added support for platforms to register custom buffers, like example dma<ref name="VideoPlayer updates for Leia"/>
* Added a VC1-Packet bitstream parser implementation for improved VC-1 playback<ref>http://github.com/xbmc/xbmc/pull/11417</ref>
* Added and updated many (binary) audio decoder and encoder addons for Kodi
* Added a few (binary) video decoder addons for Kodi<ref name="Addon video codec implementation"/>
* Added a "RAW" (libraw based) image decoder addon to Kodi<ref>https://github.com/xbmc/xbmc/pull/11671</ref>
* Improved MMAL playback of H.264 MVC (Blu-ray 3D) stereoscopic video with framepacking decoding on Raspberry Pi
* Improved Stereoscopic 3D playback of 3D videos (as well as better 2D playback of 3D videos)
* Improved and enhanced Blu-ray support (including updated libbluray dependecies from the VideoLAN project<ref>https://github.com/xbmc/xbmc/pull/12305</ref><ref>http://git.videolan.org/?p=libbluray.git;a=blob;f=ChangeLog</ref>
* Improved support for "InputStream" (input stream) addons as system addons
* Updated "InputStream" (input stream) client addons for common network streaming protocols and popular services:
** [http://github.com/xbmc/xbmc/tree/master/addons/kodi.inputstream InputStream Addon (default reference InputStream Addon by Team Kodi]
** [http://github.com/mapfau/inputstream.test Test InputStream Addon (Test InputStream Addon for Kodi's new inputstream interface]
** [http://github.com/peak3d/inputstream.adaptive Adaptive InputStream Addon (InputStream Client addon for several manifest types)]
** [http://github.com/xbmc/repo-binary-addons/tree/master/inputstream.rtmp RTMP InputStream Addon (InputStream Client for RTMP streams using librtmp)]
** [http://github.com/peak3d/inputstream.mpd MPD (MPEG-DASH) InputStream Addon]
** [http://github.com/peak3d/inputstream.smoothstream SmoothStream InputStream Addon for MS-SSTR (SmoothStreamingMedia) Smooth Streaming Protocol]
** [http://github.com/mapfau/inputstream.nxmsl NXMSL InputStream Addon for Netflix style manifests over MSL]
* Updated FFmpeg multimedia codec and demux libraries to stable branch release version [http://www.ffmpeg.org/download.html#release_4.0.2 FFmpeg 4.0 (4.0.2)]<ref>http://git.videolan.org/?p=ffmpeg.git;a=blob_plain;f=Changelog;hb=release/4.0.2 FFmpeg 4.0.2 release changelog</ref><ref>https://github.com/xbmc/xbmc/pull/14212</ref>
* Removed certain audio codecs from core and made them into audio decoder and audio encoder binary add-ons
* Removed certain video codecs from core and made them into video decoder binary add-ons<ref name="Addon video codec implementation"/>
* Removed certain image codecs from core and made them into image decoder binary add-ons
* ?

=== General Library ===
* Added support to use the Favourites function in context menus<ref>https://github.com/xbmc/xbmc/pull/11967</ref>
* Added support for context menus to favourites home screen widget<ref>https://github.com/xbmc/xbmc/pull/11929</ref>
* Added support to "Sort By Date Added" in Music Video title node<ref>https://github.com/xbmc/xbmc/pull/12495</ref>

=== Music Library ===
* Added an option to rescan the music file tags for existing items in the library <ref>https://github.com/xbmc/xbmc/pull/11557</ref>
* Added processing of WRITER tag for ID3 v2, Vorbis and APE formats <ref>https://github.com/xbmc/xbmc/pull/11735</ref>
* Added processing of ARTISTSORT (TSOP), ALBUMARTISTSORT (TS02) and COMPOSERSORT (TSOC) tags to provide a sort name for artists. <ref>https://github.com/xbmc/xbmc/pull/11738</ref>
* Added a new dialog for selection of both artist and album scraper addons, and their settings.<ref>https://github.com/xbmc/xbmc/pull/12987</ref><ref>https://github.com/xbmc/xbmc/pull/12943</ref>
* Added additional artist data that Musicbrainz provides: type (person, group, orchestra, choir etc.), gender, and disambiguation comments that help to differentiate artists with the same name <ref>https://github.com/xbmc/xbmc/pull/12963</ref>
* Added an Artist Information Folder - a single location for artist artwork and nfo. This solves numerous issues related to artwork, artist data import and general folder and file structure <ref>https://github.com/xbmc/xbmc/pull/12891</ref>
* Added support for Extended Artwork, making the local art that is picked up automatically on scan configurable. <ref>https://github.com/xbmc/xbmc/pull/13352</ref><ref>https://github.com/xbmc/xbmc/pull/13848</ref><ref>https://github.com/xbmc/xbmc/pull/13491</ref><ref>https://github.com/xbmc/xbmc/pull/13101</ref><ref>https://github.com/xbmc/xbmc/pull/13871</ref>
* Added an option to prefer scraped album covers to embedded images <ref>https://github.com/xbmc/xbmc/pull/13812</ref>
* Added a filter to sort music items by media source <ref>https://github.com/xbmc/xbmc/pull/14012</ref><ref>https://github.com/xbmc/xbmc/pull/14082</ref>
* Improved use of BAND and ENSEMBLE (Vorbis and APE) tags. <ref>https://github.com/xbmc/xbmc/pull/11735</ref>
* Improved handling of duplicate MusicBrainzTrackID within the same album<ref>https://github.com/xbmc/xbmc/pull/12079</ref>
* Improved handling of Cue Sheets<ref>https://github.com/xbmc/xbmc/pull/12082</ref>
* Improved online scraping of additional artist and album information making better use of Musicbrainz IDs<ref>https://github.com/xbmc/xbmc/pull/12120</ref><ref>https://github.com/xbmc/xbmc/pull/12597</ref>
* Improved on clean installs, change default song sort order to Track Number <ref>https://github.com/xbmc/xbmc/pull/12834</ref>
* Improved FileItem::IsSamePath for albums and artists to prevent false matches<ref>https://github.com/xbmc/xbmc/pull/13585</ref>
* Improved album genre inconsistencies<ref>https://github.com/xbmc/xbmc/pull/13042</ref>
* Improved performance by avoiding unnecessary db access by GUI when app processing GUI_MSG_UPDATE_ITEM messages<ref>https://github.com/xbmc/xbmc/pull/13640</ref>
* Improved support for fetching local art for multi-folder albums (disc sets) <ref>https://github.com/xbmc/xbmc/pull/13769</ref>
* Changed Artist/Album Information Dialog <ref>https://github.com/xbmc/xbmc/pull/13672</ref>
* Changed Song Information Dialog <ref>https://github.com/xbmc/xbmc/pull/13533</ref>

=== Web Scrapers ===
* Added support for Python (script) based web scrapers for Kodi<ref>http://github.com/xbmc/xbmc/pull/9984</ref>
* Refactored and updated many XML based scrapers in Kodi for music, movies, tv shows, and music videos
* Updated music, movies, tv shows, and music video scrapers for Kodi
* ?

=== AudioEngine ===
* Added a new Sndio sink for [[AudioEngine#ActiveAE|ActiveAE]] for BSD, other BSD Unix based systems, and Linux<ref>https://github.com/xbmc/xbmc/pull/11962</ref>
* Improved the default cross-platform event driven active state machine pattern [[AudioEngine#ActiveAE|ActiveAE]] (Kodi's [[AudioEngine]])
* Improved ALSA sink for [[AudioEngine#ActiveAE|ActiveAE]] for Linux Desktop and generic Linux based Embedded Systems
* Improved PulseAudio sink for [[AudioEngine#ActiveAE|ActiveAE]] for Linux Desktop
* Improved OSS (Open Sound System) sink for [[AudioEngine#ActiveAE|ActiveAE]] for BSD, like FreeBSD and similar BSD Unix based systems
* Improved AUDIOTRACK sink for [[AudioEngine#ActiveAE|ActiveAE]] for [[Amlogic]]
* Improved Pi Audio sink for [[AudioEngine#ActiveAE|ActiveAE]] for [[Raspberry Pi]]
* Improved DirectSound sink for [[AudioEngine#ActiveAE|ActiveAE]] for Windows
* Improved WASAPI sink for [[AudioEngine#ActiveAE|ActiveAE]] for Windows
* Improved CoreAudio sink for [[AudioEngine#ActiveAE|ActiveAE]] for (Mac) OS X and iOS
* Improved Darwin sink for [[AudioEngine#ActiveAE|ActiveAE]] for (Mac) OS X and iOS
* Renamed AE_SINK to KODI_AE_SINK
* PulseAudio Sink now honors users' server settings, starting with PA version 11.0 means: it does not do overwrite servers' mixing policy. Check: remixing-use-all-sink-channels server setting.

=== Other ===
* Added a new unified setting for "Startup action" and added "Play TV/Radio"<ref>https://github.com/xbmc/xbmc/pull/12548</ref>
* Added support to build Kodi with support for Bluetooth<ref>http://github.com/xbmc/xbmc/pull/11137</ref>
* Added possibility for CMake build system to add additional libraries on install<ref>https://github.com/xbmc/xbmc/pull/12423</ref>
* Added and updated many audio visualization and screensaver addons for Kodi<ref>https://github.com/xbmc/repo-binary-addons</ref>
* Improved Kodi's JSON-RPC API
* Improved code stability, performance. and security, as well as general code clean-up in many core areas
* Improved compiling/building and code documentation (following doxygen coding guidelines)
* Changed to use spdlog for Kodi logging as well as improved and further optimized logging (including debug logs)<ref>https://github.com/xbmc/xbmc/pull/11833</ref>
* Changed XML format of setting values for Kodi's settings configuration<ref>https://github.com/xbmc/xbmc/pull/12277</ref>
* Updated and improved mappings for new and existing remote controls
* Updated default web interface (webinterface is called "Chorus2" and is currently at version 2.4.4)<ref>https://github.com/xbmc/xbmc/pull/11872</ref>
* Updated critical dependency libraries such as openssl, gnutls, and CMake (used to compile Kodi and its binary addons)
* Removed last dependencies of SDL (Simple DirectMedia Layer) which was hardware abstraction for input devices<ref>https://github.com/xbmc/xbmc/pull/12272</ref><ref>https://github.com/xbmc/xbmc/pull/11881</ref>
* Removed all glew (libglew library) dependencies in Kodi's code<ref>http://github.com/xbmc/xbmc/pull/11128</ref>
* ?

=== Android Specific ===
* Moved to Android API 26 and SDK 26 with NDK 18 as minimum (meaning at least Android 5.0 is still required)
* Added support for speech-to-text in Kodi OSD keyboard on Android TV (triggered by voice button on remote)
* Added support for Android to move the Kodi app to SD card<ref>https://github.com/xbmc/xbmc/pull/12168</ref>
* Added support for Android TV Leanback search and recommendations meta data from Kodi<ref>|https://github.com/xbmc/xbmc/pull/11901</ref>
** Default setting for Android TV Leanback suggestion to random unwatched movies and music albums<ref>https://github.com/xbmc/xbmc/pull/11963</ref>
* Changed Rendertype from GUILayer to VideoLayer for Android MediaCodecSurface<ref>https://github.com/xbmc/xbmc/pull/12097</ref>
* Changed to use NDK native C interface for Android MediaCodec (for performance gains)<ref>https://github.com/xbmc/xbmc/pull/11931</ref>
* Changed to support ZeroConf via native Android API (and deprecates mDNSresponder)<ref>http://github.com/xbmc/xbmc/pull/11393</ref>
* Changed to support network information via native Android API (and deprecates POSIX)<ref>https://github.com/xbmc/xbmc/pull/12243</ref>
* Changed handling of Kodi's Java interfaces via JNI for better consistency<ref>https://github.com/xbmc/xbmc/pull/12292</ref>
* ?

=== BSD Specific ===
* Improved Kodi support for [http://en.wikipedia.org/wiki/Berkeley_Software_Distribution BSD (operating system)] on FreeBSD, PC-BSD, and other similar BSD platforms
* Improved VAAPI (Video Acceleration API) support (requires VAAPI compatible hardware and drivers)
* Improved VDPAU (NVIDIA) Hardware Video Acceleration (requires VDPAU compatible hardware and drivers)
* ?

=== Linux Specific ===
* Added support for a generic DRM/KMS implementation using GBM to create surfaces and V4L2 for video acceleration<ref>https://github.com/xbmc/xbmc/pull/11955</ref>
* Added support for Mir windowing system (Mir 1.0) for Kodi<ref>http://github.com/xbmc/xbmc/pull/10898</ref> and added support for VAAPI on Mir using DRM<ref>http://github.com/xbmc/xbmc/pull/11040</ref>
* Added support for the middle mouse button on embedded platforms<ref>https://github.com/xbmc/xbmc/pull/11956</ref>
* Added support more yuv420p bitwidths for direct rendering on Linux<ref>https://github.com/xbmc/xbmc/pull/12479</ref>
* Added support for using VAAPI hardware video decoding with OpenGL ES<ref>https://github.com/xbmc/xbmc/pull/12113</ref>
* Added support for build Kodi with imx support using CMake<ref>http://github.com/xbmc/xbmc/pull/11288</ref>
* Moved the CMake build system to the top of the code tree (moved to root)<ref>http://github.com/xbmc/xbmc/pull/10446</ref>
* Improved support for UltraHD decoding / 4K resolution output when hardware supports it
* Improved ARM processor architecture (using [[Raspberry Pi]] as reference device)
* Improved OpenGL ES and EGL support (using [[Raspberry Pi]] as reference device)
* Improved VAAPI (Video Acceleration API) support (requires VAAPI compatible hardware and drivers)
* Improved VDPAU (NVIDIA) Hardware Video Acceleration (requires VDPAU compatible hardware and drivers)
* Improved XvBA (AMD/ATI) Hardware Video Acceleration (requires XvBA compatible hardware and drivers)
* Improved dedicated AMLCodec hardware accelerated video decoding support for Linux on Amlogic devices
* Removed the unused and unmaintained OpenMAX video decoder from Kodi's VideoPlayer<ref>https://github.com/xbmc/xbmc/pull/12197</ref>
* Removed support for autotools based build system for Kodi and binary addons (in favour of CMake)<ref>http://github.com/xbmc/xbmc/pull/10429</ref>
* ?

=== iOS Specific ===
* Added support for iOS 10.0 by adding support for compiling Kodi with Xcode 8 IDE and iOS SDK 10.0<ref>https://github.com/xbmc/xbmc/pull/10539</ref>
* Improved Apple VDADecoder Video Acceleration support for iOS (on iPad, iPhone, and iPod iDevices)
* Improved support for TVOS (Apple's iOS fork for Apple TV 4) in Kodi mainline
* Improved support for iOS on ARM64 (64-bit iOS)
* ?

=== OS X Specific ===
* Added support for compiling Kodi with Xcode 8 IDE for OSX 10.11 (El Capitan) and macOS 10.12 (Sierra)
* Improved Apple VDADecoder Video Acceleration support for (Mac) OS X
* ?

=== Windows Specific ===
* Added support to build Kodi for Windows 64 / Windows for Intel 64-bit (x86-64)<ref>https://github.com/xbmc/xbmc/pull/12065</ref>
* Added support for 3D LUT (3D Lookup Table) and dithering to Windows video renderer<ref name="WinRenderer re-work">https://github.com/xbmc/xbmc/pull/12475</ref>
* Improved support to compiling Kodi for Microsoft's UWP (Universal Windows Platform) APIs
* Changed the inner working of render buffers and rendering methods<ref name="WinRenderer re-work"/>
* Changed to using unicode win32 api methods<ref>https://github.com/xbmc/xbmc/pull/11780</ref>
* Changed windowing systems for screen saver handling on Windows OS platforms
* Changed to make Kodi for Windows platform independent of posix/main.cpp<ref>https://github.com/xbmc/xbmc/pull/12215</ref>
* Removed support for Windows Vista as the operating-system is no longer supported by Microsoft<ref>https://github.com/xbmc/xbmc/pull/11953</ref>
* ?

== References ==
<references/>

== See also ==
* [[Leia API changes]]
{{Changelogs}}

[[Category:Manual]]
[[Category:Leia|*]]
[[Category:Changelogs|18]]

PulseAudio

2018-06-10T10:50:31Z

Fritsch: /* FAQ */

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation, in order to get 7.1 audio Multichannel Mode must be used}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync. In the case of video with TrueHD/DTS-HD 7.1 audio this must be decoded by Kodi to Multichannel PCM by disabling passthrough, then Pulseaudio can handle the 7.1 channels of audio.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". As Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always an exclusive mode. If you have another application hogging the device, e.g. Chrome or Skype, passthrough won't work. Even applications that simply monitor the device, such as SoundWireServer, will prevent passthrough from working.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate passthrough codecs, setup pavucontrol as following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, first, first identify the correct sound card ID:
'''pacmd list-cards'''

Look at the output to find the id of the card and the name/format of the profile you want to use (in this case, card ID is '''0''' and profile is '''output:hdmi-stereo''')
Once you've identified this information, set your output profile to the one for hdmi-stereo:
'''pacmd set-card-profile 0 output:hdmi-stereo'''

Then, obtain the sink ID you want to set formats on by inspecting output of:
'''pactl list sinks'''

Then set the sink format for the sink you want, as below (in this case '''0'''):
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

{{redv|'''IMPORTANT:'''| Enabling ''' Sync Playback to Display ''' will disable passthrough silently, as it makes zero sense to sync with a display clock while one cannot alter audio.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PulseAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|Doing so may cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>pasuspender -- env AE_SINK=ALSA kodi</pre> (starting with v18 this option was renamed to '''KODI_AE_SINK=ALSA''')

'''pasuspender''' is a tool that can be used to tell a local PulseAudio sound server to temporarily suspend access to the audio devices, to allow other applications access them directly. pasuspender will suspend access to the audio devices, fork a child process, and when the child process terminates, resume access again.

You can also put the previous command in a custom .desktop-file.

Be warned as this will interfere with your Desktop sounds!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

Audio devices are disappearing with pulseaudio 8.0 (Ubuntu 16.04, even later version are affected) especially while running kodi and while using ''Adjust Refreshrate to match video''. This is an issue with the module-switch-on-port-available module and will be fixed with pulseaudio 9.0, the fix sadly won't probably make it into Ubuntu 16.04. As a workaround please disable that feature by editing /etc/pulse/default.pa and commenting or removing ''load-module module-switch-on-port-available'' and reboot the system.

''' Kodi v16 '''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

''' Kodi v17 '''

Starting with the upcoming kodi v17 Krypton the above behaviour is taken care within kodi. You don't have to disable remixing in pulseaudio anymore. That means content is output without further remixing by pulseaudio server if a sane mapping is possible. Basically that means if the audio is FL, FR, FC, LFE, SL, SR and your speaker-mapping is FL, FR, FC, LFE, BL, BR we will resolve that and output 6 channels accordingly. Whenever we cannot map all input channels to the output we ask pulseaudio to do the mixing for us.

''' Volume issues '''

Issue: Changing kodi's volume will change overall system volume, especially on song change this is an irritating behaviour. The effect you hear is not done by kodi, but by a systemwide pulseaudio (mis)configuration. Some distributions sadly still ship pulseaudio with '''flat-volumes = yes''' as the default, which produces this behaviour. In fact it will cause the hardware volume (or master volume) to go up and down for every pulseaudio stream that changes its own volume. As this effect is unexpected behaviour for users, distributions started to ship pulseaudio with '''flat-volumes = no''' by default (as time of writing this is Ubuntu, Arch-Linux and others). In order to change that setting, depending on your distribution edit ''/etc/pulse/daemon.conf'' and set '''flat-volumes = no'''. After a PA server restart, the volume handling is more intuitive. If you are at it, please inform your distribution about those issues, so that they can ship a more user-friendly default with next release. At the time of writing, affected distributions: Debian.

== HOW-TO ==

====[[PulseAudio/HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu|HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu]]====

== References ==
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2018-06-10T10:50:15Z

Fritsch: AE_SINK to KODI_AE_SINK for v18

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation, in order to get 7.1 audio Multichannel Mode must be used}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync. In the case of video with TrueHD/DTS-HD 7.1 audio this must be decoded by Kodi to Multichannel PCM by disabling passthrough, then Pulseaudio can handle the 7.1 channels of audio.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". As Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always an exclusive mode. If you have another application hogging the device, e.g. Chrome or Skype, passthrough won't work. Even applications that simply monitor the device, such as SoundWireServer, will prevent passthrough from working.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate passthrough codecs, setup pavucontrol as following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, first, first identify the correct sound card ID:
'''pacmd list-cards'''

Look at the output to find the id of the card and the name/format of the profile you want to use (in this case, card ID is '''0''' and profile is '''output:hdmi-stereo''')
Once you've identified this information, set your output profile to the one for hdmi-stereo:
'''pacmd set-card-profile 0 output:hdmi-stereo'''

Then, obtain the sink ID you want to set formats on by inspecting output of:
'''pactl list sinks'''

Then set the sink format for the sink you want, as below (in this case '''0'''):
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

{{redv|'''IMPORTANT:'''| Enabling ''' Sync Playback to Display ''' will disable passthrough silently, as it makes zero sense to sync with a display clock while one cannot alter audio.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PulseAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|Doing so may cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>pasuspender -- env AE_SINK=ALSA kodi</pre> (starting with v18 this option was renamed to '''KODI_AE_SINK=ALSA'''

'''pasuspender''' is a tool that can be used to tell a local PulseAudio sound server to temporarily suspend access to the audio devices, to allow other applications access them directly. pasuspender will suspend access to the audio devices, fork a child process, and when the child process terminates, resume access again.

You can also put the previous command in a custom .desktop-file.

Be warned as this will interfere with your Desktop sounds!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

Audio devices are disappearing with pulseaudio 8.0 (Ubuntu 16.04, even later version are affected) especially while running kodi and while using ''Adjust Refreshrate to match video''. This is an issue with the module-switch-on-port-available module and will be fixed with pulseaudio 9.0, the fix sadly won't probably make it into Ubuntu 16.04. As a workaround please disable that feature by editing /etc/pulse/default.pa and commenting or removing ''load-module module-switch-on-port-available'' and reboot the system.

''' Kodi v16 '''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

''' Kodi v17 '''

Starting with the upcoming kodi v17 Krypton the above behaviour is taken care within kodi. You don't have to disable remixing in pulseaudio anymore. That means content is output without further remixing by pulseaudio server if a sane mapping is possible. Basically that means if the audio is FL, FR, FC, LFE, SL, SR and your speaker-mapping is FL, FR, FC, LFE, BL, BR we will resolve that and output 6 channels accordingly. Whenever we cannot map all input channels to the output we ask pulseaudio to do the mixing for us.

''' Volume issues '''

Issue: Changing kodi's volume will change overall system volume, especially on song change this is an irritating behaviour. The effect you hear is not done by kodi, but by a systemwide pulseaudio (mis)configuration. Some distributions sadly still ship pulseaudio with '''flat-volumes = yes''' as the default, which produces this behaviour. In fact it will cause the hardware volume (or master volume) to go up and down for every pulseaudio stream that changes its own volume. As this effect is unexpected behaviour for users, distributions started to ship pulseaudio with '''flat-volumes = no''' by default (as time of writing this is Ubuntu, Arch-Linux and others). In order to change that setting, depending on your distribution edit ''/etc/pulse/daemon.conf'' and set '''flat-volumes = no'''. After a PA server restart, the volume handling is more intuitive. If you are at it, please inform your distribution about those issues, so that they can ship a more user-friendly default with next release. At the time of writing, affected distributions: Debian.

== HOW-TO ==

====[[PulseAudio/HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu|HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu]]====

== References ==
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2018-05-21T08:17:54Z

Fritsch: /* Known issues */

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation, in order to get 7.1 audio Multichannel Mode must be used}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync. In the case of video with TrueHD/DTS-HD 7.1 audio this must be decoded by Kodi to Multichannel PCM by disabling passthrough, then Pulseaudio can handle the 7.1 channels of audio.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". As Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always an exclusive mode. If you have another application hogging the device, e.g. Chrome or Skype, passthrough won't work. Even applications that simply monitor the device, such as SoundWireServer, will prevent passthrough from working.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate passthrough codecs, setup pavucontrol as following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, first, first identify the correct sound card ID:
'''pacmd list-cards'''

Look at the output to find the id of the card and the name/format of the profile you want to use (in this case, card ID is '''0''' and profile is '''output:hdmi-stereo''')
Once you've identified this information, set your output profile to the one for hdmi-stereo:
'''pacmd set-card-profile 0 output:hdmi-stereo'''

Then, obtain the sink ID you want to set formats on by inspecting output of:
'''pactl list sinks'''

Then set the sink format for the sink you want, as below (in this case '''0'''):
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

{{redv|'''IMPORTANT:'''| Enabling ''' Sync Playback to Display ''' will disable passthrough silently, as it makes zero sense to sync with a display clock while one cannot alter audio.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PulseAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|Doing so may cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>pasuspender -- env AE_SINK=ALSA kodi</pre>

'''pasuspender''' is a tool that can be used to tell a local PulseAudio sound server to temporarily suspend access to the audio devices, to allow other applications access them directly. pasuspender will suspend access to the audio devices, fork a child process, and when the child process terminates, resume access again.

You can also put the previous command in a custom .desktop-file.

Be warned as this will interfere with your Desktop sounds!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

Audio devices are disappearing with pulseaudio 8.0 (Ubuntu 16.04, even later version are affected) especially while running kodi and while using ''Adjust Refreshrate to match video''. This is an issue with the module-switch-on-port-available module and will be fixed with pulseaudio 9.0, the fix sadly won't probably make it into Ubuntu 16.04. As a workaround please disable that feature by editing /etc/pulse/default.pa and commenting or removing ''load-module module-switch-on-port-available'' and reboot the system.

''' Kodi v16 '''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

''' Kodi v17 '''

Starting with the upcoming kodi v17 Krypton the above behaviour is taken care within kodi. You don't have to disable remixing in pulseaudio anymore. That means content is output without further remixing by pulseaudio server if a sane mapping is possible. Basically that means if the audio is FL, FR, FC, LFE, SL, SR and your speaker-mapping is FL, FR, FC, LFE, BL, BR we will resolve that and output 6 channels accordingly. Whenever we cannot map all input channels to the output we ask pulseaudio to do the mixing for us.

''' Volume issues '''

Issue: Changing kodi's volume will change overall system volume, especially on song change this is an irritating behaviour. The effect you hear is not done by kodi, but by a systemwide pulseaudio (mis)configuration. Some distributions sadly still ship pulseaudio with '''flat-volumes = yes''' as the default, which produces this behaviour. In fact it will cause the hardware volume (or master volume) to go up and down for every pulseaudio stream that changes its own volume. As this effect is unexpected behaviour for users, distributions started to ship pulseaudio with '''flat-volumes = no''' by default (as time of writing this is Ubuntu, Arch-Linux and others). In order to change that setting, depending on your distribution edit ''/etc/pulse/daemon.conf'' and set '''flat-volumes = no'''. After a PA server restart, the volume handling is more intuitive. If you are at it, please inform your distribution about those issues, so that they can ship a more user-friendly default with next release. At the time of writing, affected distributions: Debian.

== HOW-TO ==

====[[PulseAudio/HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu|HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu]]====

== References ==
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2018-01-04T10:47:08Z

Fritsch: Debian

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation, in order to get 7.1 audio Multichannel Mode must be used}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync. In the case of video with TrueHD/DTS-HD 7.1 audio this must be decoded by Kodi to Multichannel PCM by disabling passthrough, then Pulseaudio can handle the 7.1 channels of audio.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". As Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always an exclusive mode. If you have another application hogging the device, e.g. Chrome or Skype, passthrough won't work. Even applications that simply monitor the device, such as SoundWireServer, will prevent passthrough from working.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate passthrough codecs, setup pavucontrol as following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, first, first identify the correct sound card ID:
'''pacmd list-cards'''

Look at the output to find the id of the card and the name/format of the profile you want to use (in this case, card ID is '''0''' and profile is '''output:hdmi-stereo''')
Once you've identified this information, set your output profile to the one for hdmi-stereo:
'''pacmd set-card-profile 0 output:hdmi-stereo'''

Then, obtain the sink ID you want to set formats on by inspecting output of:
'''pactl list sinks'''

Then set the sink format for the sink you want, as below (in this case '''0'''):
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

{{redv|'''IMPORTANT:'''| Enabling ''' Sync Playback to Display ''' will disable passthrough silently, as it makes zero sense to sync with a display clock while one cannot alter audio.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|Doing so may cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>pasuspender -- env AE_SINK=ALSA kodi</pre>

'''pasuspender''' is a tool that can be used to tell a local PulseAudio sound server to temporarily suspend access to the audio devices, to allow other applications access them directly. pasuspender will suspend access to the audio devices, fork a child process, and when the child process terminates, resume access again.

You can also put the previous command in a custom .desktop-file.

Be warned as this will interfere with your Desktop sounds!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

Audio devices are disappearing with pulseaudio 8.0 (Ubuntu 16.04) especially while running kodi and while using ''Adjust Refreshrate to match video''. This is an issue with the module-switch-on-port-available module and will be fixed with pulseaudio 9.0, the fix sadly won't probably make it into Ubuntu 16.04. As a workaround please disable that feature by editing /etc/pulse/default.pa and commenting or removing ''load-module module-switch-on-port-available'' and reboot the system.

''' Kodi v16 '''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

''' Kodi v17 '''

Starting with the upcoming kodi v17 Krypton the above behaviour is taken care within kodi. You don't have to disable remixing in pulseaudio anymore. That means content is output without further remixing by pulseaudio server if a sane mapping is possible. Basically that means if the audio is FL, FR, FC, LFE, SL, SR and your speaker-mapping is FL, FR, FC, LFE, BL, BR we will resolve that and output 6 channels accordingly. Whenever we cannot map all input channels to the output we ask pulseaudio to do the mixing for us.

''' Volume issues '''

Issue: Changing kodi's volume will change overall system volume, especially on song change this is an irritating behaviour. The effect you hear is not done by kodi, but by a systemwide pulseaudio (mis)configuration. Some distributions sadly still ship pulseaudio with '''flat-volumes = yes''' as the default, which produces this behaviour. In fact it will cause the hardware volume (or master volume) to go up and down for every pulseaudio stream that changes its own volume. As this effect is unexpected behaviour for users, distributions started to ship pulseaudio with '''flat-volumes = no''' by default (as time of writing this is Ubuntu, Arch-Linux and others). In order to change that setting, depending on your distribution edit ''/etc/pulse/daemon.conf'' and set '''flat-volumes = no'''. After a PA server restart, the volume handling is more intuitive. If you are at it, please inform your distribution about those issues, so that they can ship a more user-friendly default with next release. At the time of writing, affected distributions: Debian.

== HOW-TO ==

====[[PulseAudio/HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu|HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu]]====

== References ==
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2018-01-04T10:39:13Z

Fritsch: Add volume description

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation, in order to get 7.1 audio Multichannel Mode must be used}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync. In the case of video with TrueHD/DTS-HD 7.1 audio this must be decoded by Kodi to Multichannel PCM by disabling passthrough, then Pulseaudio can handle the 7.1 channels of audio.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". As Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always an exclusive mode. If you have another application hogging the device, e.g. Chrome or Skype, passthrough won't work. Even applications that simply monitor the device, such as SoundWireServer, will prevent passthrough from working.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate passthrough codecs, setup pavucontrol as following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, first, first identify the correct sound card ID:
'''pacmd list-cards'''

Look at the output to find the id of the card and the name/format of the profile you want to use (in this case, card ID is '''0''' and profile is '''output:hdmi-stereo''')
Once you've identified this information, set your output profile to the one for hdmi-stereo:
'''pacmd set-card-profile 0 output:hdmi-stereo'''

Then, obtain the sink ID you want to set formats on by inspecting output of:
'''pactl list sinks'''

Then set the sink format for the sink you want, as below (in this case '''0'''):
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

{{redv|'''IMPORTANT:'''| Enabling ''' Sync Playback to Display ''' will disable passthrough silently, as it makes zero sense to sync with a display clock while one cannot alter audio.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|Doing so may cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>pasuspender -- env AE_SINK=ALSA kodi</pre>

'''pasuspender''' is a tool that can be used to tell a local PulseAudio sound server to temporarily suspend access to the audio devices, to allow other applications access them directly. pasuspender will suspend access to the audio devices, fork a child process, and when the child process terminates, resume access again.

You can also put the previous command in a custom .desktop-file.

Be warned as this will interfere with your Desktop sounds!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

Audio devices are disappearing with pulseaudio 8.0 (Ubuntu 16.04) especially while running kodi and while using ''Adjust Refreshrate to match video''. This is an issue with the module-switch-on-port-available module and will be fixed with pulseaudio 9.0, the fix sadly won't probably make it into Ubuntu 16.04. As a workaround please disable that feature by editing /etc/pulse/default.pa and commenting or removing ''load-module module-switch-on-port-available'' and reboot the system.

''' Kodi v16 '''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

''' Kodi v17 '''

Starting with the upcoming kodi v17 Krypton the above behaviour is taken care within kodi. You don't have to disable remixing in pulseaudio anymore. That means content is output without further remixing by pulseaudio server if a sane mapping is possible. Basically that means if the audio is FL, FR, FC, LFE, SL, SR and your speaker-mapping is FL, FR, FC, LFE, BL, BR we will resolve that and output 6 channels accordingly. Whenever we cannot map all input channels to the output we ask pulseaudio to do the mixing for us.

''' Volume issues '''

Issue: Changing kodi's volume will change overall system volume, especially on song change this is an irritating behaviour. The effect you hear is not done by kodi, but by a systemwide pulseaudio (mis)configuration. Some distributions sadly still ship pulseaudio with '''flat-volumes = yes''' as the default, which produces this behaviour. In fact it will cause the hardware volume (or master volume) to go up and down for every pulseaudio stream that changes its own volume. As this effect is unexpected behaviour for users, distributions started to ship pulseaudio with '''flat-volumes = no''' by default (as time of writing this is Ubuntu, Arch-Linux and others). In order to change that setting, depending on your distribution edit ''/etc/pulse/daemon.conf'' and set '''flat-volumes = no'''. After a PA server restart, the volume handling is more intuitive. If you are at it, please inform your distribution about those issues, so that they can ship a more user-friendly default with next release.

== HOW-TO ==

====[[PulseAudio/HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu|HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu]]====

== References ==
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

AudioEngine

2017-04-09T11:39:30Z

Fritsch: Gapless and Best Match

{{mininav|[[Development]]{{l2|[[Audio]] }} }}

'''AudioEngine''' or ('''AE''') refers to XBMC's new audio system.

== Features ==
AudioEngine replaces SDL and brings some of the external dependencies into XBMC, and wraps up all the different media types for mixing, samplerate conversion, format conversion, encoding, upmix, downmix, etc.
<br />
;Features of AE include:
* ''Support for DTS-HD MA / Dolby TrueHD Bluray formats''
* ''Support for 24-bit and floating-point audio at up to 384,000hz''
* ''Mixing of all streams including GUI sounds even when transcoding audio''
* ''Start-up enumeration of hardware audio devices and their capabilities with log output''
* ''Bitstreaming support in [[PAPlayer]] (XBMC's music player)''
* ''Upmixing of stereo to full channel layout''
* ''Tighter syncing of A/V streams''
* ''Floating-point processing of audio''
* ''24-bit and floating-point decoding/handling of mp3''
* ''Full support for [[w:ReplayGain|ReplayGain]]''
* ''Built-in sample-rate conversion and transcoding''

It's still early days for AE. Bugs will be found, and new and exciting features added.

== Settings ==
Audio settings can be found in the GUI at

;<big>{{highlight|Settings -> System -> Audio output|bordered=yes}}</big>

Refer to [[AudioEngine/HOW-TO: Configure audio]] for more detail.

== Supported Audio Formats for Passthrough ==

A summary of some of the supported formats within the AudioEngine

{| class="prettytable" style="text-align: center; color: black;"
|-
!rowspan="3" style="color:#000000; background-color:#DBDBDB;" | '''Audio Codec'''
!colspan="12" style="color:#000000; background-color:#DBDBDB;" | '''Audio Source'''
!rowspan="3" style="color:#000000; background-color:#DBDBDB;" | '''XBMC Passthrough Setting'''
|-
!colspan="3" style="color:#000000; background-color:#DBDBDB;" | '''HD DVD'''
!colspan="3" style="color:#000000; background-color:#DBDBDB;" | '''Blu-ray Disc'''
!colspan="3" style="color:#000000; background-color:#DBDBDB;" | '''DVD-Video'''
!colspan="3" style="color:#000000; background-color:#DBDBDB;" | '''DVD-Audio'''
|-
! style="color:#000000; background-color:#DBDBDB;"| Channels (max)
! style="color:#000000; background-color:#DBDBDB;"| Max bit rate
! style="color:#000000; background-color:#DBDBDB;"| Sample rate (max)
! style="color:#000000; background-color:#DBDBDB;"| Channels (max)
! style="color:#000000; background-color:#DBDBDB;"| Max bit rate
! style="color:#000000; background-color:#DBDBDB;"| Sample rate (max)
! style="color:#000000; background-color:#DBDBDB;"| Channels (max)
! style="color:#000000; background-color:#DBDBDB;"| Max bit rate
! style="color:#000000; background-color:#DBDBDB;"| Sample rate (max)
! style="color:#000000; background-color:#DBDBDB;"| Channels (max)
! style="color:#000000; background-color:#DBDBDB;"| Max bit rate
! style="color:#000000; background-color:#DBDBDB;"| Sample rate (max)
|-
| align="left"|'''Dolby Digital (AC-3)'''
| 5.1
| 504 kbit/s
| 48 kHz / 16 bit
| 5.1
| 640 kbit/s
| 48 kHz / 16 bit
| 5.1
| 448 kbit/s
| 48 kHz / 16 bit
| 5.1
| 448 kbit/s
| 48 kHz / 16 bit
| rowspan="2"| Dolby Digital (AC3) capable receiver
|-
| align="left"|'''Dolby Digital Plus (E-AC-3)'''
| 7.1
| 3 Mbit/s
| 48 kHz / 24 bit
| 7.1
| 1.7 Mbit/s
| 48 kHz / 24 bit
| colspan="6" {{NA}}
|-
| align="left"|'''DTS'''
| 5.1 (Core)
| 1536 kbit/s
| 48 kHz / 24 bit
| 5.1 (Core)
| 1536 kbit/s
| 48 kHz / 24 bit
| 6.1
| 768 kbit/s
| 48 kHz / 16 bit
| colspan="3" {{NA}}
| rowspan="2"| DTS capable receiver
|-
| align="left"|'''DTS 24/96'''
| colspan="6" {{NA}}
| 5.1
| 1536 kbit/s
| 96 kHz / 24-bit
| 5.1
| 1536 kbit/s
| 96 kHz / 24-bit
|-
| align="left"|'''Linear PCM (LPCM)'''
| 7.1
| 27 Mbit/s
| 192 kHz / 24 bit
| 8.1
| 27 Mbit/s
| 192 kHz / 24 bit
| 5.1
| 6.1 Mbit/s
| 48 kHz / 16 bit
| 5.1
| 6.1 Mbit/s
| 96 kHz / 24 bit
| MultiChannel LPCM capable receiver
|-
| align="left"|'''Dolby TrueHD'''
| 7.1
| 18 Mbit/s
|192 kHz / 24 bit
| 7.1
| 18 Mbit/s
| 192 kHz / 24 bit
| colspan="6" {{NA}}
| TrueHD capable receiver
|-
| align="left"|'''DTS-HD High Resolution Audio (HRA)'''
| 7.1
| 6 Mbit/s
| 96 kHz / 24 bit
| 7.1
| 6 Mbit/s
| 96 kHz / 24 bit
| colspan="6" style=background:#FFC890 | N/A
| rowspan="3"| DTS-HD capable receiver
|-
| align="left" rowspan="2"|'''DTS-HD Master Audio (MA)'''
| 5.1
| 18 Mbit/s
| 192 kHz / 24 bit
| | 5.1
| 18 Mbit/s
| 192 kHz / 24 bit
| colspan="6" {{NA}}
|-
| 7.1
| 18 Mbit/s
| 96 kHz / 24 bit
| 7.1
| 18 Mbit/s
| 96 kHz / 24 bit
| colspan="6" {{NA}}
|}

=== Test audio files ===
Below You can find a excellent range of flac test audio files stereo/multichannel and varied sample/bit rates and quality.

Click [http://www.2l.no/hires/ here] to download flac test files

Click [http://download.wavetlan.com/SVV/Media/HTTP/http-wma.html here] to download wma test files

Click [http://www.testsounds.com/ here] to download various audio system test files

== Audio hardware compatibility ==
<big>{{See also | Audio hardware compatibility}}</big>

== History and Team ==
AudioEngine, AE for short was two-year project spear-headed by [[User:Gnif|Gnif]] which was released in v12 (Frodo), and was first merged with master for user testing as of May 15th, 2012.

=== Why write a new audio subsystem? ===

It's been an accepted fact that the existing audio code was little-touched since the early days of XBMC, and was limited by the 16-bit architecture of the original Xbox and codecs available at the time. Dolby AC3 and mp3 (or earlier formats!) ruled the media codec world. Over time HTPC's became more mainstream, more powerful and better connected. Analog connections gave way to optical SPDIF connections, which in turn were replaced with HDMI. Processors, GPU's and media formats evolved at a steady pace.

With the growth of the HTPC and new formats like those made available with Bluray technology, the audio subsystem was under scrutiny as an area for improvement. Higher definition audio like multichannel FLAC was becoming a preferred standard for those demanding higher quality audio media. It was time for an update, and what an update!

Early efforts at patching fixes and even an initial attempt at a completely new system fell by the wayside. The scope of the required changes and the complexity of the API made it a daunting task, especially for volunteer programmers working in their spare time. This was compounded by the fact that XBMC runs on a wide range of hardware and operating systems. Most of the developers focus on specific platforms or subsystems within the whole of XBMC. Any new system had to be platform-agnostic, cohesive and flexible.

In time, it became obvious the project was going to require a full re-write and replacement of the audio engine. Furthermore, XBMC's base of hardware and OS platforms continued to grow. The detailed specifications for the new audio formats were unknown, and of course the master code for XBMC was ever-changing.

=== Three years of work ===
In November of 2009 [[User:Gnif|Gnif]] decided to bite the proverbial bullet, and after extensive consultation with the team finalized the API or structure which was to become AE. Drawing in other developers as required, the massive project slowly took shape, and reached the ready-point for user tests a year later. The forum thread for those hardy beta-testers (thank you!) reached over 1,200 posts, and slowly but surely features were added and debugged, and system stability grew.

Over the next two years, thanks to the determination of [[User:Gnif|Gnif]] the core engines, decoders, encoders and utilities that make up AudioEngine became a reality, and other developers began to contribute to the core and especially the platform-specific sinks or output stages. Among those contributing were [[User:Gimli|Gimli]], [[User:Fneufneu|Fneufneu]], [[User:Memphiz|Memphiz]], [[User:Dddamian|Dddamian]], [[User:Anssi|Anssi]] and others.

There was a goal to have the new audio system ready for Eden 11.0, but there was just too much left to do. Many users were eagerly looking forward to it's inclusion, but stable releases must continue, and AE wasn't ready when the Eden feature-freeze went into effect. During this time the AE code-base was solidified, bugs tracked and squashed, features added and testing increased.

Finally, on May 15th 2012, AudioEngine was merged to master. Weighing in at over 22,000 lines of code, it represents one of the single biggest code-merges ever for XBMC. Now for the first time it is readily accessible for all the development team (and users!) to see, test and improve within the greater context of XBMC's master branch.

=== ActiveAE ===
ActiveAE was a large rewrite of SoftAE and combined all platforms to one engine. Sinks are available for all platforms.
ActiveAE uses an active state machine pattern, with a separate high priority sink thread, that cares for underruns. ActiveAE is completely build upon ffmpeg, which is used for resampling, channel mapping and decoding. High performance SSE algorithms - already existent in the AEUtils - were fixed up and are used to do the final conversion into formats the sinks can accept. ActiveAE uses the ''float'' format internally and it is working bit-exact.

A new feature is the upmix via AC3 transcoding support. On optical devices where only 2 pcm channels are available, we can now upmix to 5.1 by transcoding to ac3.
Another new feature is the PulseAudio sink for ActiveAE, which was merged into XBMC mainline on January 9th 2014 and enables Linux desktop users to use the PulseAudio system instead of ALSA, which was an often requested feature. See [[PulseAudio]]

ActiveAE has three build-in profiles: Best Match, Optimized and Fixed.
* ''Fixed'' takes care that all audio you will play is play in the very same data format. Your receiver does not need to switch modes.
* ''Best Match'' is what previously existed as the "audiophile" mode. Whenever a new video or music playback starts, the audio engine will select the best sink for that stream. By design ''Best Match'' and ''gapless'' playback are not compatible. If you rely on ''gapless'' playback, consider using ''Optimized'' instead.
* ''Optimized'' is something special, as it tries to reduce the reopening of sinks a lot. One example is live-TV where it switches between 5.1 to 2.0 during commercials. In order to not open the device anew and loosing some (milliseconds of) audio, the 2.0 commercials are played with the already open 5.1 sink by muting the non existent channels.
The main developers of ActiveAE are [[User:Fernetmenta|Fernetmenta]] and [[User:Fritsch|Fritsch]].
{{frodo updated}}

[[Category:Manual]]
[[Category:Audio]]
[[Category:Development]]

PulseAudio

2016-11-20T09:27:41Z

Fritsch: Adding Sync Playback to Display

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by Kodi to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by Kodi, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio. Als Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

{{redv|'''IMPORTANT:'''| Enabling ''' Sync Playback to Display ''' will disable PT silently. It makes zero sense to sync with a display clock while one cannot alter audio.}}
=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|Doing so may cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>pasuspender -- env AE_SINK=ALSA kodi</pre>

'''pasuspender''' is a tool that can be used to tell a local PulseAudio sound server to temporarily suspend access to the audio devices, to allow other applications access them directly. pasuspender will suspend access to the audio devices, fork a child process, and when the child process terminates, resume access again.

You can also put the previous command in a custom .desktop-file.

Be warned as this will interfere with your Desktop sounds!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

Audio devices are disappearing with pulseaudio 8.0 (Ubuntu 16.04) especially while running kodi and while using ''Adjust Refreshrate to match video''. This is an issue with the module-switch-on-port-available module and will be fixed with pulseaudio 9.0, the fix sadly won't probably make it into Ubuntu 16.04. As a workaround please disable that feature by editing /etc/pulse/default.pa and commenting or removing ''load-module module-switch-on-port-available'' and reboot the system.

''' Kodi v16 '''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

''' Kodi v17 '''

Starting with the upcoming kodi v17 Krypton the above behaviour is taken care within kodi. You don't have to disable remixing in pulseaudio anymore. That means content is output without further remixing by pulseaudio server if a sane mapping is possible. Basically that means if the audio is FL, FR, FC, LFE, SL, SR and your speaker-mapping is FL, FR, FC, LFE, BL, BR we will resolve that and output 6 channels accordingly. Whenever we cannot map all input channels to the output we ask pulseaudio to do the mixing for us.

== HOW-TO ==

====[[PulseAudio/HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu|HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu]]====

== References ==
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

File:Videoplayer-pt.png

2016-11-20T09:22:49Z

Fritsch: MsUpload

MsUpload

PulseAudio

2016-08-25T21:14:41Z

Fritsch: Mixing strategy changed.

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by Kodi to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by Kodi, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio. Als Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|Doing so may cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>pasuspender -- env AE_SINK=ALSA kodi</pre>

'''pasuspender''' is a tool that can be used to tell a local PulseAudio sound server to temporarily suspend access to the audio devices, to allow other applications access them directly. pasuspender will suspend access to the audio devices, fork a child process, and when the child process terminates, resume access again.

You can also put the previous command in a custom .desktop-file.

Be warned as this will interfere with your Desktop sounds!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

Audio devices are disappearing with pulseaudio 8.0 (Ubuntu 16.04) especially while running kodi and while using ''Adjust Refreshrate to match video''. This is an issue with the module-switch-on-port-available module and will be fixed with pulseaudio 9.0, the fix sadly won't probably make it into Ubuntu 16.04. As a workaround please disable that feature by editing /etc/pulse/default.pa and commenting or removing ''load-module module-switch-on-port-available'' and reboot the system.

''' Kodi v16 '''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

''' Kodi v17 '''

Starting with the upcoming kodi v17 Krypton the above behaviour is taken care within kodi. You don't have to disable remixing in pulseaudio anymore. That means content is output without further remixing by pulseaudio server if a sane mapping is possible. Basically that means if the audio is FL, FR, FC, LFE, SL, SR and your speaker-mapping is FL, FR, FC, LFE, BL, BR we will resolve that and output 6 channels accordingly. Whenever we cannot map all input channels to the output we ask pulseaudio to do the mixing for us.

== HOW-TO ==

====[[PulseAudio/HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu|HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu]]====

== References ==
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2016-07-26T20:13:26Z

Fritsch: Typos

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by Kodi to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by Kodi, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio. Als Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|Doing so may cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>pasuspender -- env AE_SINK=ALSA kodi</pre>

'''pasuspender''' is a tool that can be used to tell a local PulseAudio sound server to temporarily suspend access to the audio devices, to allow other applications access them directly. pasuspender will suspend access to the audio devices, fork a child process, and when the child process terminates, resume access again.

You can also put the previous command in a custom .desktop-file.

Be warned as this will interfere with your Desktop sounds!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

Audio devices are disappearing with pulseaudio 8.0 (Ubuntu 16.04) especially while running kodi and while using ''Adjust Refreshrate to match video''. This is an issue with the module-switch-on-port-available module and will be fixed with pulseaudio 9.0, the fix sadly won't probably make it into Ubuntu 16.04. As a workaround please disable that feature by editing /etc/pulse/default.pa and commenting or removing ''load-module module-switch-on-port-available'' and reboot the system.

''' Kodi v16 '''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

''' Kodi v17 '''

Starting with the upcoming kodi v17 Krypton the above behaviour is taken care within kodi. You don't have to disable remixing in pulseaudio anymore. That means content is output without further remixing by pulseaudio server with one exception: if you use the '''default''' device all remixing will ''still'' happen, so make sure to choose the specific output device, which is the device that has the name of your soundcard in its name, when interested in this new capabilities.

== HOW-TO ==

====[[PulseAudio/HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu|HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu]]====

== References ==
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2016-07-26T20:12:33Z

Fritsch: Remixing is fixed in v17

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by Kodi to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by Kodi, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio. Als Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|Doing so may cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>pasuspender -- env AE_SINK=ALSA kodi</pre>

'''pasuspender''' is a tool that can be used to tell a local PulseAudio sound server to temporarily suspend access to the audio devices, to allow other applications access them directly. pasuspender will suspend access to the audio devices, fork a child process, and when the child process terminates, resume access again.

You can also put the previous command in a custom .desktop-file.

Be warned as this will interfere with your Desktop sounds!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

Audio devices are disappearing with pulseaudio 8.0 (Ubuntu 16.04) especially while running kodi and while using ''Adjust Refreshrate to match video''. This is an issue with the module-switch-on-port-available module and will be fixed with pulseaudio 9.0, the fix sadly won't probably make it into Ubuntu 16.04. As a workaround please disable that feature by editing /etc/pulse/default.pa and commenting or removing ''load-module module-switch-on-port-available'' and reboot the system.

''' Kodi v16 '''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

''' Kodi v17 '''

Starting with the upcoming kodi v17 Krypting the above behaviour is taken care within kodi. You don't have to disable remixing in pulseaudio anymore. That means content is output without further remixing by pulseaudio server with one exception: if you use the '''default''' device all remixing will ''still'' happen, so make sure to choose the specific output device, which is the device that has the name of your soundcard in its name, when interested in this new capabilities.

== HOW-TO ==

====[[PulseAudio/HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu|HOW-TO: Disable PulseAudio and use ALSA (without removing PulseAudio) for Ubuntu]]====

== References ==
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2016-04-07T07:43:21Z

Fritsch: /* Known issues */

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by Kodi to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by Kodi, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio. Als Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|But you know that doing so, it will cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>AE_SINK=ALSA Kodi </pre>
: Be warned as this will interfere with your Desktop sounds and PulseAudio! Consider removing pulseaudio instead.
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

Audio devices are disappearing with pulseaudio 8.0 (Ubuntu 16.04) especially while running kodi and while using ''Adjust Refreshrate to match video''. This is an issue with the module-switch-on-port-available module and will be fixed with pulseaudio 9.0, the fix sadly won't probably make it into Ubuntu 16.04. As a workaround please disable that feature by editing /etc/pulse/default.pa and commenting or removing ''load-module module-switch-on-port-available'' and reboot the system.

=== References ===
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2016-04-07T07:41:39Z

Fritsch: /* Known issues */

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by Kodi to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by Kodi, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio. Als Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|But you know that doing so, it will cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>AE_SINK=ALSA Kodi </pre>
: Be warned as this will interfere with your Desktop sounds and PulseAudio! Consider removing pulseaudio instead.
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

Audio devices are disappearing with pulseaudio 8.0 (Ubuntu 16.04). This is an issue with the module-switch-on-port-available module and will be fixed with pulseaudio 9.0. To disable that modules, edit /etc/pulse/default.pa and comment or remove: ''load-module module-switch-on-port-available'' and reboot the system.

=== References ===
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2016-04-06T21:54:42Z

Fritsch: Documented pulseaudio 8.0 wrong switch port behavior

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by Kodi to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by Kodi, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio. Als Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|But you know that doing so, it will cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>AE_SINK=ALSA Kodi </pre>
: Be warned as this will interfere with your Desktop sounds and PulseAudio! Consider removing pulseaudio instead.
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

Audio devices are disappearing with pulseaudio 8.0 (Ubuntu 16.04). This is an issue with the module-switch-on-port-available module and will be fixed with pulseaudio 9.0. To disable that modules, edit /etc/pulse/default.pa and comment or remove:

''load-module module-switch-on-port-available''

and reboot the system.

=== References ===
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2016-03-13T07:55:45Z

Fritsch: /* FAQ */ Make sure that AE_SINK=ALSA harms

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by Kodi to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by Kodi, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio. Als Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|But you know that doing so, it will cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>AE_SINK=ALSA Kodi </pre>
: Be warned as this will interfere with your Desktop sounds and PulseAudio! Consider removing pulseaudio instead.
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

=== References ===
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

HOW-TO:Install Kodi for Linux

2016-01-13T21:41:48Z

Fritsch: /* Debian */

{{Kodi migration note}}

= Official Team Kodi repositories =

The installation instructions within this section reference repositories that are officially sanctioned by Team Kodi. For third party and unofficial build support, please see the section below.

== Installing Kodi on Ubuntu-based distributions ==
See [[SSH]] or [http://help.ubuntu.com/community/UsingTheTerminal Click here to find out how to use the terminal.]

Use the command line terminal and enter the following commands. Follow the prompts as you would any other software installation.

<syntaxhighlight lang="bash">
sudo apt-get install software-properties-common
sudo add-apt-repository ppa:team-xbmc/ppa
sudo apt-get update
sudo apt-get install kodi
</syntaxhighlight>

{{#lst:Team XBMC PPA|repos}}

=== Installing PVR Addons ===
The Linux release of Kodi doesn't include any PVR addons by default. To install a PVR addon, run the following command and replace the XXXXXX with the PVR addon of your choice:

<syntaxhighlight lang="bash">
sudo apt-get install kodi-pvr-XXXXXXX
</syntaxhighlight>

{| class="wikitable"
|-
! PVR Addon !! Description
|-
| kodi-pvr-dev || Kodi Media Center (PVR Add-on Dev package)
|-
| kodi-pvr-argustv || Kodi PVR Addon Argustv
|-
| kodi-pvr-demo || Kodi PVR Demo Addon
|-
| kodi-pvr-dvbviewer || Kodi PVR Addon Dvbviewer
|-
| kodi-pvr-iptvsimple || Kodi PVR Iptv Addon
|-
| kodi-pvr-mediaportal-tvserver || Kodi PVR Addon Mediaportal Tvserver
|-
| kodi-pvr-mythtv || Kodi PVR Addon MythTv - Cmyth
|-
| kodi-pvr-nextpvr || Kodi PVR Addon NextPvr
|-
| kodi-pvr-njoy || Kodi PVR Addon Njoy
|-
| kodi-pvr-hts || Kodi PVR Addon TvHeadend Hts
|-
| kodi-pvr-vdr-vnsi || Kodi PVR Addon VDR Vnsi
|-
| kodi-pvr-vuplus || Kodi PVR Addon Vuplus
|}

=== Installing a development build ===
{{see also|Development builds}}
To install a beta/unstable version of {{kodi}} you must first add the unstable repository, then install XBMC. Use <code>ppa:team-xbmc/xbmc-nightly</code> for nightly builds and <code>ppa:team-xbmc/unstable</code> for [[beta]] builds.

<syntaxhighlight lang="bash">
sudo add-apt-repository ppa:team-xbmc/xbmc-nightly
sudo apt-get update
sudo apt-get install kodi
</syntaxhighlight>

Note that if you have any addons (such as PVR clients), these must be updated as well (they will not be updated automatically):
<syntaxhighlight lang="bash">
sudo apt-get install kodi-pvr-mythtv
</syntaxhighlight>

=== Upgrading ===
<section begin="Ubuntu upgrade" />
To update Kodi when a new version is released, just do a general system/package or use the following commands in the terminal (or via [[SSH]]):

<syntaxhighlight lang="bash">
sudo apt-get update
sudo apt-get upgrade
</syntaxhighlight>

{{note|In some cases where additional packages are required, Kodi will fail to upgrade when using the upgrade commands as above. To install additional packages use the command below:

<syntaxhighlight lang="bash">
sudo apt-get dist-upgrade
</syntaxhighlight>}}
<section end="Ubuntu upgrade" />

=== Downgrading to a stable version from a development version ===
If you install a nightly build or an unstable release and want to return to a stable release, follow these instructions:

Find the current PPA you are using:
<syntaxhighlight lang="bash">
sudo apt-cache policy | grep team-xbmc
</syntaxhighlight>

Remove the unstable or nightly PPA where it says '''PPAHERE''':
<syntaxhighlight lang="bash">
sudo add-apt-repository -r ppa:PPAHERE
</syntaxhighlight>

Then restore the stable version with the following commands:
<syntaxhighlight lang="bash">
sudo add-apt-repository ppa:team-xbmc/ppa
sudo apt-get update
sudo apt-get remove kodi kodi-bin
sudo apt-get install kodi
</syntaxhighlight>

=== Downgrading between stable versions ===
{{incomplete}}

=== Uninstalling ===
If you need to remove and purge an application and finally removing/purging also the application configurations files, do so by using the following commands:

<syntaxhighlight lang="bash" enclose="div">
sudo apt-get update
sudo apt-get remove kodi*
sudo apt-get purge kodi*
</syntaxhighlight>

Then remove the settings folder to remove all settings and library data. This will not delete any videos or music, but just the settings and library data itself:
<syntaxhighlight lang="bash">
rm ~/.kodi/
</syntaxhighlight>
or
<syntaxhighlight lang="bash" enclose="div">
rm ~/.xbmc/ # for older versions before 14.0
</syntaxhighlight>

= Third Party Repositories =


The instructions in this section are for unofficial Linux binaries that are un/semi supported by Team Kodi. Most of those binaries use system ffmpeg or even worse totally untested libav, which is not recommended for {{kodi}} as we support ffmpeg only.

== Debian ==

The installation if you are using Debian (Jessie), you can use the debian-backports repository.

Add the following lines to your /etc/apt/sources.list file, as superuser (sudo)

<syntaxhighlight lang="bash">
# kodi repos
# starting with debian jessie, debian provides kodi via its backports repository
# remember: those packages are not supported by team kodi
deb http://http.debian.net/debian jessie-backports main
</syntaxhighlight>

And then, update APT and install Kodi.

<syntaxhighlight lang="bash">
sudo apt-get update
sudo apt-get install kodi
</syntaxhighlight>

Enjoy your new Kodi.

== Fedora ==
Refer to [[HOW-TO:Install Kodi on Fedora 23 using RPMFusion packages]] for a guide showing how to install Fedora 23 and Kodi to create a quick-booting, standalone style of media player.

== OpenELEC ==
{{main|OpenELEC}}
{{#lst:OpenELEC|intro}}

== KodiBuntu ==
The installation instructions on this page are intended for people who already have a Linux-based OS setup, or wish to do their own installation of Linux. Alternatively you can try out [[KodiBuntu]], which will install both an OS and {{kodi}} with an easy installer.

{{main|KodiBuntu}}
{{#lst:KodiBuntu|intro}}

= Installation from source =
If distribution packages are not available, or you need a newer version, or specific features enabled, then you will most likely need to compile from source. While compiling from source does not differ very much between distributions (except for installation of build dependencies), a few different guides are available in this wiki.

* [[HOW-TO compile XBMC for Linux from source code]]
* [[HOW-TO compile XBMC for Linux on Debian/Ubuntu]] - This is a tutorial on how to compile and install {{kodi}} on Debian and Ubuntu.

= See also =
* [[Linux]]
* [[HOW-TO:Autostart XBMC for Linux]]
*[[JeOS implementations for Kodi]]

* [[Linux FAQ]]

{{Helix updated}}

[[Category:Linux]]
[[Category:How-to]]
[[Category:Installation|Linux]]
[[Category:Manual]]

HOW-TO:Install Kodi for Linux

2016-01-13T21:41:32Z

Fritsch: Add the debian backports repository for jessie

{{Kodi migration note}}

= Official Team Kodi repositories =

The installation instructions within this section reference repositories that are officially sanctioned by Team Kodi. For third party and unofficial build support, please see the section below.

== Installing Kodi on Ubuntu-based distributions ==
See [[SSH]] or [http://help.ubuntu.com/community/UsingTheTerminal Click here to find out how to use the terminal.]

Use the command line terminal and enter the following commands. Follow the prompts as you would any other software installation.

<syntaxhighlight lang="bash">
sudo apt-get install software-properties-common
sudo add-apt-repository ppa:team-xbmc/ppa
sudo apt-get update
sudo apt-get install kodi
</syntaxhighlight>

{{#lst:Team XBMC PPA|repos}}

=== Installing PVR Addons ===
The Linux release of Kodi doesn't include any PVR addons by default. To install a PVR addon, run the following command and replace the XXXXXX with the PVR addon of your choice:

<syntaxhighlight lang="bash">
sudo apt-get install kodi-pvr-XXXXXXX
</syntaxhighlight>

{| class="wikitable"
|-
! PVR Addon !! Description
|-
| kodi-pvr-dev || Kodi Media Center (PVR Add-on Dev package)
|-
| kodi-pvr-argustv || Kodi PVR Addon Argustv
|-
| kodi-pvr-demo || Kodi PVR Demo Addon
|-
| kodi-pvr-dvbviewer || Kodi PVR Addon Dvbviewer
|-
| kodi-pvr-iptvsimple || Kodi PVR Iptv Addon
|-
| kodi-pvr-mediaportal-tvserver || Kodi PVR Addon Mediaportal Tvserver
|-
| kodi-pvr-mythtv || Kodi PVR Addon MythTv - Cmyth
|-
| kodi-pvr-nextpvr || Kodi PVR Addon NextPvr
|-
| kodi-pvr-njoy || Kodi PVR Addon Njoy
|-
| kodi-pvr-hts || Kodi PVR Addon TvHeadend Hts
|-
| kodi-pvr-vdr-vnsi || Kodi PVR Addon VDR Vnsi
|-
| kodi-pvr-vuplus || Kodi PVR Addon Vuplus
|}

=== Installing a development build ===
{{see also|Development builds}}
To install a beta/unstable version of {{kodi}} you must first add the unstable repository, then install XBMC. Use <code>ppa:team-xbmc/xbmc-nightly</code> for nightly builds and <code>ppa:team-xbmc/unstable</code> for [[beta]] builds.

<syntaxhighlight lang="bash">
sudo add-apt-repository ppa:team-xbmc/xbmc-nightly
sudo apt-get update
sudo apt-get install kodi
</syntaxhighlight>

Note that if you have any addons (such as PVR clients), these must be updated as well (they will not be updated automatically):
<syntaxhighlight lang="bash">
sudo apt-get install kodi-pvr-mythtv
</syntaxhighlight>

=== Upgrading ===
<section begin="Ubuntu upgrade" />
To update Kodi when a new version is released, just do a general system/package or use the following commands in the terminal (or via [[SSH]]):

<syntaxhighlight lang="bash">
sudo apt-get update
sudo apt-get upgrade
</syntaxhighlight>

{{note|In some cases where additional packages are required, Kodi will fail to upgrade when using the upgrade commands as above. To install additional packages use the command below:

<syntaxhighlight lang="bash">
sudo apt-get dist-upgrade
</syntaxhighlight>}}
<section end="Ubuntu upgrade" />

=== Downgrading to a stable version from a development version ===
If you install a nightly build or an unstable release and want to return to a stable release, follow these instructions:

Find the current PPA you are using:
<syntaxhighlight lang="bash">
sudo apt-cache policy | grep team-xbmc
</syntaxhighlight>

Remove the unstable or nightly PPA where it says '''PPAHERE''':
<syntaxhighlight lang="bash">
sudo add-apt-repository -r ppa:PPAHERE
</syntaxhighlight>

Then restore the stable version with the following commands:
<syntaxhighlight lang="bash">
sudo add-apt-repository ppa:team-xbmc/ppa
sudo apt-get update
sudo apt-get remove kodi kodi-bin
sudo apt-get install kodi
</syntaxhighlight>

=== Downgrading between stable versions ===
{{incomplete}}

=== Uninstalling ===
If you need to remove and purge an application and finally removing/purging also the application configurations files, do so by using the following commands:

<syntaxhighlight lang="bash" enclose="div">
sudo apt-get update
sudo apt-get remove kodi*
sudo apt-get purge kodi*
</syntaxhighlight>

Then remove the settings folder to remove all settings and library data. This will not delete any videos or music, but just the settings and library data itself:
<syntaxhighlight lang="bash">
rm ~/.kodi/
</syntaxhighlight>
or
<syntaxhighlight lang="bash" enclose="div">
rm ~/.xbmc/ # for older versions before 14.0
</syntaxhighlight>

= Third Party Repositories =


The instructions in this section are for unofficial Linux binaries that are un/semi supported by Team Kodi. Most of those binaries use system ffmpeg or even worse totally untested libav, which is not recommended for {{kodi}} as we support ffmpeg only.

== Debian ==

The installation if you are using Debian (Jessie), you can use the debian-backports repository.

Add the following lines to your /etc/apt/sources.list file, as superuser (sudo)

<syntaxhighlight lang="bash">
# kodi repos
# starting with debian jessi, debian provides kodi via its backports repository
# remember: those packages are not supported by team kodi
deb http://http.debian.net/debian jessie-backports main
</syntaxhighlight>

And then, update APT and install Kodi.

<syntaxhighlight lang="bash">
sudo apt-get update
sudo apt-get install kodi
</syntaxhighlight>

Enjoy your new Kodi.

== Fedora ==
Refer to [[HOW-TO:Install Kodi on Fedora 23 using RPMFusion packages]] for a guide showing how to install Fedora 23 and Kodi to create a quick-booting, standalone style of media player.

== OpenELEC ==
{{main|OpenELEC}}
{{#lst:OpenELEC|intro}}

== KodiBuntu ==
The installation instructions on this page are intended for people who already have a Linux-based OS setup, or wish to do their own installation of Linux. Alternatively you can try out [[KodiBuntu]], which will install both an OS and {{kodi}} with an easy installer.

{{main|KodiBuntu}}
{{#lst:KodiBuntu|intro}}

= Installation from source =
If distribution packages are not available, or you need a newer version, or specific features enabled, then you will most likely need to compile from source. While compiling from source does not differ very much between distributions (except for installation of build dependencies), a few different guides are available in this wiki.

* [[HOW-TO compile XBMC for Linux from source code]]
* [[HOW-TO compile XBMC for Linux on Debian/Ubuntu]] - This is a tutorial on how to compile and install {{kodi}} on Debian and Ubuntu.

= See also =
* [[Linux]]
* [[HOW-TO:Autostart XBMC for Linux]]
*[[JeOS implementations for Kodi]]

* [[Linux FAQ]]

{{Helix updated}}

[[Category:Linux]]
[[Category:How-to]]
[[Category:Installation|Linux]]
[[Category:Manual]]

Archive:Kodi v15 (Isengard) FAQ

2015-05-19T08:40:59Z

Fritsch: /* The "o" screen doesn't show the video FPS anymore */

{{Kodi FAQ}}
{{mininav| [[FAQs]] {{l2| [[Releases]] }} }}
{{Isengard box}}

<section begin="intro" />Frequently Asked Questions for upgrading to the upcoming Kodi v15 (codename Isengard) from a previous version. Includes how to enable some of the new features, where some controls got moved to, etc.<section end="intro" />

__TOC__
{{-}}
== General FAQ ==
::{{big|''See also: '''[[All platforms FAQ]]''' for an FAQ that applies to all versions of Kodi.''}}

=== What is Kodi? What is Isengard? ===
:{{Main|Kodi name change FAQ|History of XBMC}}
:Kodi is the new name for XBMC media center. "Isengard" is the codename for version 15, just as "Gotham" was the codename for XBMC v13 and "Helix was the codename for Kodi v14". You will often see "v15" and "Isengard" used interchangeably in the community. It might be a little confusing with so many new names being used, but this is simply the new version of Kodi/XBMC. As long as you call it version 15/v15/Isengard, then everyone in the community will know what you are talking about.

=== Changelog ===
:See: '''[[Kodi v15 (Isengard) changelog]]''' (and add-on developers should also see '''[[Isengard API changes]]''')

=== What are some of the noticeable new features? ===
:{{Main|New features|Kodi v15 (Isengard) changelog}}
:In addition to many "under the hood" improvements, some of the ''visible'' additions to v15 include:
:* Improved and expanded the internationalization and regional settings options in the GUI. {{highlight|bordered=yes| [[Settings/Appearance#International|Settings → Appearance → International]] }}
:* Added adaptive skipping/seeking through audio and video playback, also known as '''[[skip steps]]'''.
:* Added a universal '''[[skip steps|skip/seek step command]]''' to allow an unlimited number of specific time seeking buttons. e.g., a dedicated "small step forward" now possible.
:* Added a chapter selection window with visual thumbnails. See '''[[bookmarks and chapters]]'''.
:* '''[[Audio nodes]]''' for audio library customization.
:* Automatically jump to the first unwatched episode in a TV show. {{highlight|bordered=yes| [[Settings/Videos#Library|Settings → Videos → Library → "Select first unwatched TV season/episode"]] }}
:* '''[[Video navigation|"Hide watched"]]''' now works with non-library video files.
:* '''[[PVR]]''' add-ons can now auto configure using zeroconf when the PVR server supports it.
:* Add-ons can now add to the '''[[context menu]]'''.
:* Added [[Android]] HEVC/H.265 hardware video decoding. See '''[[Android hardware]]'''.
:* '''[[UPnP]]''' improvements including external subtitle support.
:* '''[[artwork|New season posters]]''' are now added automatically when updating existing TV shows.
:* Local translations are now '''[[:Category:Language add-ons|add-ons]]''' and can be updated with improvements more quickly.
:* The default touchscreen skin, re-Touched, now has '''[[PVR|PVR/Live TV]]''' support.
:* Improved '''[[add-on manager]]''' with better categorization that makes it easier to find and manage add-ons.
:* '''[[Kodi v15 (Isengard) changelog|...and many more]]'''

=== Seeking/skip steps are different ===
:{{main|Skip steps}}
:{{#lst:Skip steps|intro}}

=== SmallStepBack doesn't seem to work ===
: In '''[[Keymaps]]''' the <code>SmallStepBack</code> [[action ID]] has been replaced by <code>seek(-7)</code>. Users with custom keymaps should apply this change as well. <code>SmallStepBack</code> will still work, but it will default to the first back step in '''[[skip steps]]'''.

=== HOW-TO:Install languages offline ===
:{{main|HOW-TO:Install languages offline}}
: {{#lst:HOW-TO:Install languages offline|intro}}

== New system requirements ==
:{{main|Supported hardware}}

=== Android 4.2 required ===
:'''[[Android|Android 4.2]]''' is now the minimal supported version for Kodi to run on Android platform.

=== iOS 5.1.1 required ===
:'''[[iOS|iOS 5.1.1]]''' is now the minimal supported version for Kodi to run on a '''''jailbroken''''' "iDevice".

=== Mac OS X 10.7 required ===
:'''[[Mac OS X|Mac OS X 10.7]]''' is now the minimal supported version for Kodi to run on the Mac platform.

=== OUYA needs OS upgrade to run v15 ===
:Due to the new system requirements and lack of needed updates from the OUYA company, OUYA's Android-based OS is unable to run Kodi v15. The OUYA hardware can still be used for Kodi, but will need a replacement for the OUYA OS. There is a work-in-progress guide in doing so at '''[[HOW-TO:Install CyanogenMod on OUYA]]'''. It might even be possible to still use OUYA games on CM 11, or at least have some kind of dual booting option for users who want to retain access to their old OUYA games.

=== Apple TV 2 is no longer supported ===
:[[Apple TV 2]] is no longer supported as of v15. See '''[http://kodi.tv/farewell-to-future-appletv2-development/ here]''' for details.

== Upgrading ==
{{warning|image_size=25px| If you are upgrading from XBMC v13 to Kodi v15 then please read '''[[Migration from XBMC to Kodi]]''' first.}}

{{warning|image_size=25px| Always '''[[backup]]''' your settings before upgrading, just incase! }}

=== How do I upgrade from v14 to v15? ===
:{{main|Installing}}

* '''ANDROID USERS:''' '''{{color|red|Don't}}''' uninstall an earlier version of Kodi/XBMC before installing the new version. Uninstalling first would remove all of your settings. Just install the new version and it will replace the older version and retain your settings.

* In most cases you can just '''[[Installing|install Kodi v15]]''' over Kodi v14. All your settings and library are saved and will continue to work in the new version. See '''[[Installing]]''' for specific install instructions.

* Interface [[skins]] that worked in Kodi v14 should still work in v15.

* Most other [[add-ons]] that worked in Kodi v14 should still work in v15.

* If you have any issues (settings not being copied over, blank screens, etc) when updating from versions ''older'' than v14: remove the new version, install the older version of Kodi/XBMC from http://mirrors.kodi.tv/releases/ , and then upgrade to the next version. In other words, if you have v13, first update to v14, and then install v15.

=== MySQL ===
:{{main|MySQL/Upgrading}}
:As long as your MySQL server is set up to allow XBMC/Kodi to make new databases for the upgrade itself (see '''[[MySQL/Upgrading]]''') then you don't need to do anything for upgrading a MySQL set up for Kodi. Even if you use "XBMC" in your advancedsettings.xml file, you can leave this the same and everything will still work.

== Where did it this or that go? ==

=== advancedsettings.xml changes ===
:{{main|advancedsettings.xml}}
* '''<hideallitems>''' - For both the <code><videolibrary></code> and <code><musiclibrary></code> sections, this is replaced by a GUI option in v15 Isengard
* '''<SmallStepBackSeconds>''' - In v15 the <code>SmallStepBack</code> [[action ID]] has been replaced by <code>seek(-7)</code> in default keymaps. See '''[[skip steps]]''' for details. When the original <code>SmallStepBack</code> action ID is used it defaults to the first backwards [[skip steps|additive seeking value]].
* '''<timeseekforward>/<timeseekbackward>''' - In v15 these tags are replaced by GUI options via [[skip steps|additive seeking]], which is configured in the GUI. See '''[[skip steps]]''' for details.

=== Add-on manager: navigation changes ===
:{{main|Add-on manager}}

:{{editor note|Need a blurb here about the add-on manager changes. Full details should then be updated to the main [[add-on manager]] page.}}

=== Add-on manager: checking for new updates ===
:{{main|Add-on manager}}

: In most Kodi interface skins, including the default skin Confluence, the button to check for new add-on updates has been moved to the lefthand sidebar menu. When you've gone into {{highlight|bordered=yes| Settings → Add-ons }} you can press {{keypress|left}} (left) to show the menu and update button.

=== Automatic crop black bars setting ===
:The video playback setting for cropping black bars has been removed due to various bugs. Team Kodi is looking for any developers who might be interested in creating replacement code and is willing to guide them. Please inquire on the '''[http://forum.kodi.tv/forumdisplay.php?fid=93 development forum]''' for more information.

=== Apple File Protocol (AFP) has been removed ===
:Unfortunately, the AFP client has now been removed from Kodi. When AFP was first added to Kodi (then called XBMC) it was to help those Mac users who had issues with [[SMB]] sharing. However, the AFP client has always had major crashing issues, and the open source project behind it was no longer maintained. Team Kodi looked for a replacement and even tried to make our own replacement AFP client code, but in the end it didn't work out.

:Users who have AFP file servers can use '''[[path substitution]]''' to change those URLs into another formatted protocol. We recommend using '''[[NFS]]''' or getting SMB to work by reading '''[[SMB/Mac]]'''. {{editor note|maybe make a mini-how-to for the path subs.}}

=== HTSP has been removed ===
:<section begin="HTSP" />The HTSP protocol was a way for older versions of Kodi/XBMC to access [[Tvheadend]] before [[PVR]]/live TV features were officially added to Kodi/XBMC. Now that PVR/live TV has been supported since v12.0 (January 29th, 2013), and replaced the need for HTSP support, the HTSP protocol has finally been retired. Please see our '''[[PVR]]''' guide for details on how to set up the Tvheadend PVR add-on.<section end="HTSP" />

== Troubleshooting ==
:{{main|Troubleshooting}}

=== What are some of the known issues in Isengard? ===
{{see|Common issues}}

=== Where can I get more help? ===
:The '''[[FAQ|general and platform specific FAQs]]''', the Kodi support forums: '''http://forum.kodi.tv''', and/or the '''[irc://irc.freenode.org/kodi #kodi]''' [[w:IRC|IRC]] chat channel on irc.freenode.org.

=== The "o" screen doesn't show the video FPS anymore ===
:In the '''[[codecinfo]] window''', the one that shows when you press {{keypress|o}} on a keyboard, the '''FPS''' data no longer reports ''video'' FPS.

:In past versions of Kodi/XBMC (before v15) this value reported the estimated frames per second for the actual video itself, but was horribly inaccurate most of the time. Due to those inaccuracies, and various other code changes, the setting has been changed to only report what FPS the graphical interface (the buttons, menus, etc) is being rendered at. This doesn't actually mean anything for most users, but just understand that this no longer has anything to do with the video FPS.

:If you want to check if your video playback is working as it should, watch the skip and drop values. If those stay low, nothing to worry about. Increasing skip value means, that video frames cannot be rendered in time. If you even see dropping, then it's our last resort, as the system seems to be too slow to play that video and we told the decoder to throw away complete frames. Also take care that the '''[[codecinfo]] window''' byself puts more pressure on the hardware. Open it from time to time only and compare the skip / drop values.

== See also ==
{{Upgrade FAQs}}

{{Isengard updated}}

[[Category:FAQ]]
[[Category:Manual]]
[[Category:Isengard|*]]
[[Category:Upgrade FAQ|15]]

PulseAudio

2015-04-26T20:42:19Z

Fritsch: Disadvantages of disabling remixing

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by Kodi to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by Kodi, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio. Als Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|But you know that doing so, it will cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>AE_SINK=ALSA Kodi </pre>
: Be warned as this might interfere with your Desktop sounds and PulseAudio!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

Beware: This will also forbid PA to remix e.g. FL,FR, LFE, FC, BL, BR into FL, FR, LFE, FC, SL, SR - which means you might loose your rears if your speaker layout is non standard.

=== References ===
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

Archive:Chromebox

2015-02-02T11:22:41Z

Fritsch: This was plain wrong. VAAPI does full range by default - so if full range is wanted - everything can stay is. Prefer Render needs only to be disabled when Limited Range is needed - but still setting the gpu to full range is needed!

{{Infobox information appliance
| name = Chromebox
| image = [[File:Asus_chromebox.jpg|300px]]
| releasedate = 2014-03-14 (US)
| os = Chrome OS
| cpu = Intel® Celeron 2955U/2957U <br /> Intel® Core i3-4010U <br /> Intel® Core i7-4600U
| graphics = Intel® HD Graphics/GT1 (Celeron) <br /> Intel® HD Graphics 4400/GT2 (i3/i7)
| storage = 16GB internal SSD (M.2 SATA)
| memory = 2 GB/4GB standard, 16GB max <br />Dual Channel DDR3L-12800
| connectivity = HDMI, Displayport, Bluetooth 4.0, USB 3.0, Wifi 802.11 a/b/g/n, 10/100/1000 Ethernet, 2 -in-1 Card Reader, Audio jack
| dimensions = 4.88 x 4.88 x 1.65 inch (WxDxH)
}}
[[File:Asus_chromebox_ports.jpg|right|300px|Asus Chromebox Rear Ports|thumb]]
[[File:Asus_chromebox_ports_2.jpg|right|300px|Asus Chromebox Side/Front Ports|thumb]]
{{mininav|[[Devices]]|[[x86 hardware]]}}

<section begin="intro" />The Haswell Celeron-based Chromeboxes (Asus, HP, Acer, and Dell) are small lightweight x86-64 PCs that natively run ChromeOS, but with a few simple tweaks, have the capability to boot pretty much any Linux distro. They feature HDMI and DisplayPort video outputs (which can be used simultaneously), 4x USB 3.0 ports, gigabit Ethernet, an SD card slot, and built-in 802.11a/b/g/n wireless and Bluetooth 4.0.

Capability wise, these ChromeBoxes fully support hardware accelerated H.264/MPEG-2/VC-1 video playback at up to 2160p24 (4K), proper 24p output, and full 7.1/HD audio bitstreaming (Linux only). 3D playback is supported, though the decoding of MVC streams (as used in 3D Blu-ray ISOs) is not, due to Windows/driver limitations; the hardware itself is capable. Hi10 1080p playback is software decoded, but works well with few exceptions. From a purely Kodi/media playback standpoint, there's no advantage to the Core i3/i7 models over the Celeron 2955U/2957U boxes.

This page is complete guide to running Kodi (formerly XBMC) under Linux on the ChromeBox PCs.

<section end="intro" />

{{note|This page was originally written for the ASUS ChromeBox, but nearly all of these steps will be the same on the HP, Acer, and Dell Chromeboxes as well. The hardware is virtually identical: the Acer has a slightly different form factor; the HP model has only 1 dimm slot (vs the 2 the others have); the fan of the HP is also a bit louder than the others (with the Asus being the most quiet); the Dell model has an Intel 802.11ac wifi module, whereas the rest have 802.11abgn.
}}

== Device Preparation ==

=== Disable Firmware Write Protect ===

Disabling the firmware write protect will allow us to shorten the developer boot screen timeout (from 30s to ~1s) in a dual boot configuration, and optionally boot directly to the legacy BIOS (and into Ubuntu or OpenELEC). This is also necessary for standalone setups so that the stock firmware can be replaced with a custom build of [http://www.coreboot.org coreboot].

With the device powered off and unplugged:

# Remove (4) rubber feet from bottom of unit
# Remove (4) screws under rubber feet
# Separate two halves of unit. Tip: partially insert the screw removed from the notched end, but do not re-thread it. Use it to help separate the two halves.
# Remove write-protect screw circled below:
#::Asus/HP/Dell: [[File:Inside-chrome1.jpg|300px]]
#::Acer: [[File:Acer wp screw.png|400px]]
#:: Note: the write-protect screw on the Acer model is under the heat pipe, which needs to be removed to access it. Be sure to smooth out the heatsink grease/pad before reinstallation of the heat sink / heat pipe.
# Reassemble in reverse order

'''Important:''' The write-protect screw should be left out permanently.
<br />
<br />

=== Put in Developer Mode ===

Putting the ChromeBox in developer mode will allow you to access the underlying Linux operating system features necessary for installing/running Kodi.

'''WARNING''': This will erase all user data on the device.
<br />
<br />
With the device powered off:
# Insert a paperclip into the hole left of the SD card slot and press the recovery button
#: [[File:Recoverybutton.png|200px]]
# Power on the device, then remove the paper clip
# When greeted with the recovery screen, press [CTRL-D] to enter developer mode
# Press the recovery button (with paperclip) to confirm.
<br />
After confirming, the device will reboot and wipe any existing user data - this will take ~5 minutes. Afterwards, the ChromeBox will be in developer mode (as opposed to standard/verified boot mode), and the developer boot screen will be shown at each boot.
<br />
<br />

[[File:ChromeBox_dev_boot.jpg|400px]]

The developer boot screen, shown above, has a warning about OS verification being off. '''Do not hit [SPACE]''' to re-enable OS verification, as it will return the device from developer mode to standard/verified boot mode. The ChromeBox must permanently remain in developer mode, else you will potentially have to redo the setup from the beginning. The developer mode boot screen has a ~30s delay, followed by two beeps, before booting. You can skip the delay by pressing [CTRL-D] to immediately boot into ChromeOS.
<br />
<br />

=== Perform a Factory Reset ===

A factory reset is not needed for a standalone setup, but must be performed prior to any dual-boot installation.

Google's recovery tool seems to be picky about what kind/size of USB/SD media you use. I've had the best luck with 4GB/8GB media, but YMMV.
Anecdotally, creating the recovery media from within ChromeOS seems to be the most reliable method.

# Create recovery media using step 2 of Google's instructions here: https://support.google.com/chromebook/answer/1080595?hl=en or use the [https://chrome.google.com/webstore/detail/chromebook-recovery-utili/jndclpdbaamdhonoechobihbbiimdgai?hl=en ChromeBook Recovery Utility from the Chrome web store].

# With the device powered off, use a paperclip to press the Recovery button and power on the device
# Insert the recovery media (USB or SD) when prompted
<br />
Note that this will re-partition the internal hard drive and restore the original copy of ChromeOS, erasing anything else on the drive. The ChromeBox will still be left in developer mode, and if you changed the Boot Options they will still be set - so be sure to reset them back to the 'ChromeOS + 30s default' option '''before''' performing a factory reset. If you forget to do that, you'll need to press [CTRL-D] on the developer boot screen (or before the legacy boot/SeaBIOS boot screen) in order to boot ChromeOS after performing the recovery.
<br />
<br />
If you're having trouble creating the recovery media using Google's recovery tool above, you can manually download the recovery image and write it to a USB stick:
:*Download Recovery image:
:*:Asus: https://dl.google.com/dl/edgedl/chromeos/recovery/chromeos_6158.76.0_panther_recovery_stable-channel_mp.bin.zip
:*: HP: https://dl.google.com/dl/edgedl/chromeos/recovery/chromeos_6158.76.0_zako_recovery_stable-channel_mp-v2.bin.zip
:*:Acer: https://dl.google.com/dl/edgedl/chromeos/recovery/chromeos_6158.76.0_mccloud_recovery_stable-channel_mp.bin.zip
:*:Dell: https://dl.google.com/dl/edgedl/chromeos/recovery/chromeos_6158.76.0_tricky_recovery_stable-channel_mp.bin.zip
:* Download Win32 Disk Imager: http://sourceforge.net/projects/win32diskimager/
:* Unzip the recovery image; the file should be ~1.5 GB
:* Rename the recovery image extension from .bin to .img
:* Write the image to your USB media using Win32 Disk Imager
<br />
<br />

== Setup, Installation, Configuration, and Updating ==

=== OS and Kodi Installation ===
Kodi can be installed on the ChromeBox in a variety of ways. The two most common are via OpenELEC or Ubuntu+Kodi, in either a standalone or dual boot configuration. This is accomplished via the ChromeBox E-Z Setup script, which must be run (at least initially) from ChromeOS.
<br /><br />
The EZ setup script will facilitate everything needed to install either a dual boot setup, or install a custom firmware which allows the installation of any Linux-based OS in standalone mode.
<br /><br />
To run the ChromeBox E-Z Setup script, perform the following steps:

# Power on and boot to ChromeOS. Do not log in, but ensure a network connection is established.
# Hit CTRL-ALT-F2 to open command prompt
# Login with user chronos (no password required)
# Download and run the ChromeBox setup script with the commands:
#: <nowiki>curl -L -O http://goo.gl/3Tfu5W</nowiki>
#: <nowiki>sudo bash 3Tfu5W </nowiki>

Full instructions and a detailed explanation of the script's functions and usage can be found at the following forum thread: http://forum.kodi.tv/showthread.php?tid=194362
<br />
<br />
'''Note:''' If installing a Linux-based OS other than OpenELEC, you may need to manually update the kernel for optimal operation. Kernel version 3.14 is the minimum recommended; 3.16 has a fix for most MCE remote controls, and 3.18.4 has a fix for an Intel GPU bug that can cause hanging during video playback.
<br />
<br />

=== Dual Boot OS Selection ===
When dual booting with ChromeOS and OpenELEC/Ubuntu, due to the ChromeBox's firmware setup, there is no conventional boot menu. Instead, the OS selection is made via keyboard shortcuts on the developer mode boot screen (shown above): [CTRL-D] boots directly ChromeOS; [CTRL-L] boots the legacy BIOS (and whatever secondary OS is installed). The default OS and boot timeout are set using the 'Set Boot Options' feature of the EZ Setup Script.
<br />
<br />

=== Updating Kodi ===

==== OpenELEC ====

The Chromebox is, at its core, a standard x86_64 Intel system (albeit, like the NUC, with an ultra low power processor). The standard OpenELEC builds - labeled 'Generic x86_64' - work perfectly well, and it is recommended to use OpenELEC's auto-update feature (System --> OpenELEC --> System --> Automatic Updates: auto). If that doesn't work for some reason, or you want to update to a nightly/beta/RC build, you can manually update using the instructions on the [http://wiki.openelec.tv/index.php?title=Updating_OpenELEC OpenELEC wiki].
<br />
<br />

=== Recommended Settings ===

==== Kodi General ====

* System-->Settings-->System: Settings Level:'''Expert'''
* System-->Settings-->System-->Video Output: Vertical blank sync:'''Enabled during video playback''' (or just 'Enabled' if you experience UI tearing)
* System-->Settings-->System-->Power Saving: Shutdown function:'''Suspend''' (sets IR power toggle to suspend)
* System-->Settings-->Videos-->Acceleration: Use VC-1 VAAPI:'''Selected''' (de-select if you have interlaced VC-1 content)

==== OpenELEC Specific ====

* System-->OpenELEC-->System: Automatic Updates:'''Auto'''
* System-->OpenELEC-->Network: Wait for network before starting Kodi:'''Selected''' (if using a external mysql database)
* System-->OpenELEC-->Services: Enable Bluetooth:'''Selected''' (if using Bluetooth)
* System-->Settings-->Videos-->Acceleration: Use SW Filter for VAAPI:'''Selected''' (OE 4.x only)
<br />
<br />

== Known issues + Fixes/Workarounds ==

Installation, Dual Booting, USB booting:
:* Some keyboards seem to have issues working on the ChromeOS developer boot screen (before the OS is booted), and therefore cannot be used to setup/install Kodi on a ChromeBox, or to select between OSes in a dual boot setup. The Logitech K400 is one of these, so use another keyboard to install if yours doesn't appear to be working. Bluetooth keyboards '''will not work''' due to the fact that they require the OS to be loaded in order to connect to the ChromeBox.
:* On the SeaBIOS boot screen, some users may have issues bringing up the boot menu: either the 'Press ESC for boot menu' text never appears, or it appears, but pressing [ESC] doesn't do anything; both result in the box trying (and failing) to boot the internal hard drive.
:*: If you see the 'Press ESC for boot menu' text but pressing it doesn't work, then the issue is your keyboard, so try using a different one.
:*: If you '''don't''' see the 'Press ESC for boot menu' text, then the issue is with your boot media, so try using a different USB flash drive.
:* An effort is underway on the forums to catalog which keyboards work (and which do not); the thread (which is being updated regularly) can be found here: http://forum.kodi.tv/showthread.php?tid=211797
:* Some TVs/displays are not able to show the developer boot screen due to the resolution it uses (1024x768 @ 60Hz), in which case you'll need to use a different display to complete the initial setup steps.
:* Many TVs have overscan enabled by default, which will cut off the text display of the ChromeOS shell. Be sure to set your TV to a mode which does not overscan (varies by manufacturer - often called 'just scan', 'exact' 'pixel perfect').
:* Using a '''passive''' DisplayPort-->HDMI cable/adapter is often problematic, and can cause the video output drop out after booting. Use either a straight DP cable or straight HDMI/HDMI-->DVI cable; if you have to use a DisplayPort-->HDMI adapter, be sure it is the '''active''' type.

Color Range Selection:
:* This topic is a bit of a minefield, but [http://forum.kodi.tv/showthread.php?tid=176718&pid=1756704#pid1756704 this post on the forums is a good read]. It's for a NUC, but it applies to the ChromeBox as well. On some displays, the display and Intel video driver are not able to automatically sync up (in terms of which color space is being used), leading to incorrect black/white levels. You can download/play the following video clip to test: [https://dl.dropboxusercontent.com/u/98309225/1-Grayscale%20Ramp%20.mp4 Grayscale Ramp test] (file courtesy of avsforum.com). The correct output will show the grayscale ramp having a smooth transition (rather than stair steps) from 16-235, with solid black/white past the dots at the ends. See: [https://dl.dropboxusercontent.com/u/98309225/grayscale_ramp_good.png correct grayscale ramp].
:*: Solution: add the following line to the autostart script and reboot the device:
:*::<nowiki>xrandr --output HDMI1 --set "Broadcast RGB" "Full"</nowiki>
:*: Use 'DP1' instead of 'HDMI1' if connected via the DisplayPort output. See [http://wiki.openelec.tv/index.php?title=Autostart.sh the OpenELEC Autostart wiki page] for more info.
:*: You may also need to select the Kodi option 'Used limited color range' under Settings-->System-->Video Output. Use the video clip and image above as a guide.
:*: '''Note:''' If you want to output Limited color range, you are required to do the following setting as well: Settings-->Video-->Acceleration-->Prefer VAAPI Rendering: disabled/de-selected.

No Audio and/or corrupted video on Wakeup from Suspend:
:* Some displays/AVRs don't successfully handshake when resuming from suspend, leading to no audio output and/or corrupted video output until the Chromebox is rebooted.
:*: Solution: If using a universal remote, such as a Harmony, ensure that you are turning off (suspending) the ChromeBox '''before''' your AVR/TV, and turning it on (resuming) '''after''' the AVR/TV.
:*: Solution: download/enable a script that will force the ChromeBox to reset the audio/video output on resume from suspend. Use an SSH client like Putty to connect to the ChromeBox, and execute the following commands:
:*::<nowiki>mkdir -p /storage/.config/sleep.d</nowiki>
:*::<nowiki>cd /storage/.config/sleep.d</nowiki>
:*::<nowiki>curl -L -O https://dl.dropboxusercontent.com/u/98309225/01-cbox_resume.power</nowiki>
:*::<nowiki>chmod +x 01-cbox_resume.power</nowiki>
:*: Then reboot the ChromeBox
:*: Note: If connected via the DisplayPort output, use a text editor (eg, nano) to edit the script and replace references to 'HDMI1' with 'DP1'.

Video Playback:
:* An Intel Linux video driver bug ( https://bugs.freedesktop.org/show_bug.cgi?id=78960 ) causes intermittent freezes/pauses.
:*: Workaround: (OpenELEC 4.x) enable the 'Use SW filter for VAAPI' option Settings-->Video-->Acceleration.
:*: '''Note:''' this bug is fixed in OpenELEC 5.0.0, but currently requires an updated or patched kernel for other Linux distros. Update to kernel 3.18.4 or later, or see this forum post for a pre-patched kernel: http://forum.kodi.tv/showthread.php?tid=194362&pid=1877749#pid1877749

Remote Controls:
:* Most MCE IR receivers work properly now when connected to USB3 ports under Linux with kernel 3.16+ (older kernels will require a patch/fix); OpenELEC 4.0+ is fully up to date. The version of Ubuntu installed by the ChromeBox EZ setup script in a dual boot setup also includes an up-to-date kernel. However, some buggy MCE receivers still do not work properly (at all), as noted below in the Hardware/Remotes section.

:: For standalone Ubuntu (or any other distro) installs, you will need to update to a 3.16 (or later) kernel.

Power Management:
:* Suspend/resume is generally problematic with the stock firmware (dual boot setups - OpenELEC will reboot on resume), but works reliably in standalone setups running the coreboot firmware. Resume via IR remote (USB) and wake-on-lan (eg, via YATSE) work perfectly well.
:* Note: WOL only works when the ChromeBox is suspended, not fully powered off, and requires the MAC address of the box to be set (eg, in YATSE)

Windows 8 (unsupported):
:* HDMI audio doesn't work, at all, even with the proper drivers loaded. Either use the analog audio output, an external USB sound card, or run Linux.
:* Bluray disc playback doesn't work, as PowerDVD and WinDVD report that the video drivers are not supported, even though they report the hardware is capable.
:* Update: now fixed in 2015/01/29 coreboot firmware. The CPU fan will shut down at boot and not come back on unless a utility like SpeedFan is used to start it.

Linux Video Tearing:
:* Some users may experience screen tearing under the Linux desktop, or when watching video (e.g., Netflix). The fix for this is [https://wiki.archlinux.org/index.php/Intel_Graphics#Tear-free_video documented on the Arch Wiki], and copied here for convenience.

:: from a terminal/shell prompt:
:::<nowiki>sudo nano /usr/share/X11/xorg.conf.d/20-intel.conf</nowiki>

:: copy/paste the following:

:::<nowiki>Section "Device"</nowiki>
::::<nowiki>Identifier "Intel Graphics"</nowiki>
::::<nowiki>Driver "intel"</nowiki>
::::<nowiki>Option "TearFree" "true"</nowiki>
:::<nowiki>EndSection</nowiki>

:: then save, exit, and reboot.

High CPU at Idle:
:* When running a Linux setup, there is high idle CPU usage with some older kernels which do not fully support the Haswell platform; be sure to update to the latest kernel available (at '''least''' 3.14). On some (mostly dual boot) setups, it may also be necessary to add the following kernel boot parameters to disable the TPM: tpm_tis.force=1 tpm_tis.interrupts=0
<br />
<br />

== Recommended Accessories / Hardware Upgrades ==
<br />
'''RAM:'''
: The ChromeBox has two (2) 204-Pin SODIMM slots (HP models only have one), which accept 1.35V DDR3-1600 (PC3-12800) modules. Known working modules include:
:* Crucial CT25664BF160B (2GB, 1.35v/1.5v)
:* Crucial CT2CP51264BF160B (8GB [4GB x2] 1.35v/1.5v)
:* Crucial CT2KIT102464BF160B (16GB [8GB x2] 1.35v/1.5v)
:* Hynix HMT351S6CFR8C-PB (2GB, OEM)
:* HP H6Y75AA (4GB, 1.35v)
: <br />
: Crucial also has a list of 1.35v-only compatible modules here: http://www.crucial.com/usa/en/compatible-memory-for/ASUS/chromebox
<br />
'''SDD:'''
: The ChromeBox uses a single M.2 NGFF SATA III SSD (42mm); stock is a 16GB SanDisk unit. Compatible upgrades include:
:* MyDigitalSSD MDM242-SC2-128 (128GB)
:* MyDigitalSSD MDM242-SB-064 (64GB)
:* MyDigitalSSD MDM242-SB-032 (32GB)
<br />
'''Remote Controls:'''
: The ChromeBox does not have a built-in IR sensor, and must therefore use a USB IR receiver (or a Bluetooth remote). In general, any remote/receiver listed on the Kodi wiki as fully working under Linux should be fine, though some have issues when connected to USB3 ports. A Microsoft eHome compatible remote/receiver is one of the most compatible, subject to the limitations listed in the 'Known Issues' section above. Specific models tested as working include:
:* [http://flirc.tv/ Flirc]
:*: Flirc users need to set the "sleep detection" bit and program a wake key when setting it up, otherwise absolutely any IR signal will wake up your box from sleep.
:* HP IR receiver model 5188-1667 (MCE/eHome)
:* HP IR receiver model 5187-4593 (MCE/eHome)
:* Microsoft IR receiver model 1040 (MCE/eHome)
:* Sony IR receiver model PCVA-IR8U (MCE/eHome)
:* HP IR remote/receiver kit [http://www.amazon.com/dp/B00AYE6JDO/ OVU400102/71] (MCE/eHome, includes 5187-4593 receiver)
:* Ortek IR remote/receiver kit [http://www.amazon.com/dp/B00224ZDFY/ VRC-1100] (MCE clone, receiver also works well w/Logitech Harmony remotes)
:* Rosewill RHRC-11002 remote (MCE clone, includes receiver model IR605)
:* Rosewill WMC RRC-127 remote/receiver
:* Microsoft XBOX 360 IR remote (with MCE/eHome receiver or Flirc)
:* Microsoft XBOX One IR remote (with MCE/eHome receiver or Flirc)
:* Logitech Harmony remotes (programmed as Microsoft Media Center Extender - not as a keyboard - with MCE/eHome receiver; not recommended for use with a Flirc)
:* Sony Playstation 3 (PS3) Bluetooth remote (works with built-in BT receiver; press/hold START + ENTER to pair)
:* Logitech Harmony Smart Hub (via Bluetooth, works with built-in BT receiver, [http://forum.kodi.tv/showthread.php?tid=194362&pid=1843165#pid1843165 see forum post here])
:* Measy RC11 Android Monitor Wireless Keyboard Air Mouse Remote Controller With Gyroscope (cannot wake up Chromebox but works otherwise nicely, with keys as well as with mouse pointer at both OpenELEC and ChromeOS)
:* Amazon FireTV / Fire Stick remotes (Bluetooth)
:NOTE: If you need to re-map remote buttons, you can use the [[Add-on:Keymap Editor|Keymap Editor Add-on]] to do so.

:'''Currently non-working''':
:* HP IR receiver model 5070-2584 (MCE/eHome)
:* AVS Gear HA-IR01SV (MCE/eHome)
:* All Topseed manufactured MCE IR receivers
<br />
'''USB Audio Devices''':
:As the ChromeBox only has HDMI and analog audio outputs, if you need SPDIF, then either a converter or external/USB device must be used. The following devices have been tested/confirmed working:
:* [http://www.amazon.com/gp/product/B0036VO4X4/ Turtle Beach Audio Advantage Micro II ] (plug/play in both OpenELEC and Win8.1)
:* ASUS Xonar U3 USB (OpenELEC: requires un-muting the SPDIF line, see [http://openelec.tv/forum/41-supported-hardware/71023-asus-xonar-u3-usb-soundcard this forum post])
<br />
<br />

== Troubleshooting ==

=== Dual Booting ===

The most common issue with dual boot setups is being stuck on the black SeaBIOS boot screen, with the "booting from hard disk" text displayed. 99% of the time, this is due to not having performed a factory reset using the recovery media, [[Chromebox#Perform_a_Factory_Reset|as listed in the Device Prep section above]]. Simply perform the factory reset, then re-run the dual boot setup using the script as before.
<br />
<br />

=== OpenELEC ===

==== Install Media Creation ====

If you're looking to run a standalone setup, and the install media created by the script doesn't work (or you forget to create it before rebooting), then you can simply download the latest stable version (or beta/RC if you'd like) from [http://openelec.tv/get-openelec/download/viewcategory/8-generic-builds OpenELEC's website here]. The ChromeBox runs the 'Generic x86-64' version of OpenELEC, and it's recommended that you download the disk image version, and create the install media, as per the instructions [http://wiki.openelec.tv/index.php/HOW-TO:Installing_OpenELEC/Creating_The_Install_Key#tab=DiskImage on the OpenELEC wiki].

==== Misc ====
If the system isn't shutdown cleanly, sometimes a filesystem check (fsck) will be automatically performed. In some cases, the automatic repair is unsuccessful, and an error will show:
::<nowiki>***Error in check_disks: could not repair filesystem, dropping to debug shell, try to run 'fsck' manually: ***</nowiki><br />
::<nowiki>### Starting debugging shell... type exit to quit ###</nowiki><br />
::<nowiki>sh: can't access tty; job control turned off</nowiki><br />
::<nowiki>#_</nowiki><br />
<br />
In this case, simply run fsck manually as instructed, using the following commands, hitting [enter] after each:<br />
<br />
For a standalone setup:
:<nowiki>fsck /dev/sda1</nowiki><br />
:<nowiki>fsck /dev/sda2</nowiki><br />
<br />
For a dual-boot setup:
:<nowiki>fsck /dev/sda6</nowiki><br />
:<nowiki>fsck /dev/sda7</nowiki><br />
<br />
After the fsck is run, type 'reboot' then hit [enter] and the system should boot normally.
<br />
<br />

== Firmware/BIOS Updating ==

The ChromeBox's firmware consists of two main parts: the firmware itself (coreboot), and the Legacy BIOS (SeaBIOS). Users running a dual-boot configuration only need be concerned with updating the Legacy BIOS portion. Users running a standalone setup should update the custom coreboot firmware only, as it already contains an updated SeaBIOS payload, which is not able to be updated separately.
<br />
<br />
=== Updating the Legacy BIOS ===

Dual-boot users should simply boot to ChromeOS and re-download/re-run the setup script, choosing the '''Update Legacy BIOS''' option under the Dual Boot heading.
<br />
<br />
=== Updating Coreboot ===

Standalone users should also re-download/re-run the setup script, but instead choosing the '''coreboot firmware install/update''' option under the Standalone heading. As of v3.0, the script can be run under any version of Linux with a full bash shell. As OpenELEC does not have a full bash shell, OE users will need to use the standalone firmware update script, as described in [http://forum.kodi.tv/showthread.php?tid=194362 this forum post].
<br />
<br />

=== Restoring the Stock Firmware ===
If you have used the ChromeBox Setup Script's Standalone setup option, or otherwise manually updated the ChromeBox's firmware with a custom coreboot build, it is necessary to restore the stock firmware before [[Chromebox#Perform_a_Factory_Reset|performing a factory reset]] to re-load ChromeOS.

In order to do this, we will create a bootable USB stick with ChromiumOS (the open-source version of ChromeOS) and use that to re-flash the stock firmware, which you backed up before flashing the Coreboot firmware. If you didn't make a backup, we can use a copy extracted from Google's recovery image, but an actual backup is preferred.
<br />
<br />

# Create ChromiumOS USB Stick
#:* Download the latest AMD64OS daily build from http://arnoldthebat.co.uk/wordpress/chromium-os/. Be sure it's the 64-bit (AMD64OS) version, and the image version (.img.7z) and not the virtual machine version (.vdi.7z). Example: Camd64OS-20140527010101.img.7z
#:* Follow the instructions at the link above to extract and copy the image onto a USB disk. You will need at least a 4GB drive, and the contents of it will be erased. Do '''NOT''' use the same USB stick that you used for your firmware backup
# Get a ChromiumOS Shell Prompt
#:* Connect the ChromiumOS USB stick to the ChromeBox, power on, and select the USB stick from the boot menu. Boot into ChromiumOS
#:* Open a shell the same way as in ChromeOS: [CTRL]-[ALT]-[F2] and login as user 'chronos' with password 'password'
# Copy firmware backup file
#:* If you have your firmware backup on USB, connect it now, then run the following commands from the shell prompt
#:*:<nowiki>mkdir /tmp/usb</nowiki>
#:*:<nowiki>sudo mount /dev/sdc /tmp/usb (If this fails, use /dev/sdc1 instead of /dev/sdc)</nowiki>
#:*:<nowiki>cp /tmp/usb/stock-firmware.rom ./</nowiki>
#:*:<nowiki>sudo umount /tmp/usb</nowiki>
#:* If you don't have a firmware backup, then run the following command to download one extracted from the recovery image
#:*:(Asus) <nowiki>curl -L -o stock-firmware.rom https://db.tt/sLQL9i1p</nowiki>
#:*:( HP ) <nowiki> curl -L -o stock-firmware.rom https://db.tt/8NmzlrZ6</nowiki>
#:*:(Acer) <nowiki> curl -L -o stock-firmware.rom https://db.tt/Nh5EeEti</nowiki>
#:*:(Dell) <nowiki> curl -L -o stock-firmware.rom https://db.tt/IXLtQ097</nowiki>
# Restore stock firmware
#:* After completing the above, then run the following commands from the shell prompt
#:*:<nowiki>sudo flashrom -w stock-firmware.rom</nowiki>
#:*Assuming it is successful, then:
#:*:<nowiki>sudo poweroff</nowiki>

You can now remove the ChromiumOS USB drive (and firmware backup USB drive). Proceed to [[ASUS_Chromebox#Perform_a_Factory_Reset|Perform_a_Factory_Reset]] above to restore/reload ChromeOS.
<br />
<br />

[[Category:Hardware]]
[[Category:HTPC]]
[[Category:x86]]

PulseAudio

2015-01-15T10:26:35Z

Fritsch: Transition from XBMC to Kodi

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when Kodi is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows Kodi playback of video or audio to be paused in order to run a game, Skype or similar. Kodi is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within Kodi, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device Kodi required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later (named Kodi since 14 'Helix') we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in Kodi when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the Kodi implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode Kodi must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by Kodi to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by Kodi, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio. Als Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in Kodi ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| Kodi Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within Kodi will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|Kodi Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

Kodi will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside Kodi, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination Kodi will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your Kodi computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with Kodi.
* You use Kodi in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, Kodi audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use Kodi as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that Kodi chooses, might be busy or even might vanish while you are using Kodi, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|But you know that doing so, it will cause problems!}}

Yes, you can - start Kodi from terminal with:
<pre>AE_SINK=ALSA Kodi </pre>
: Be warned as this might interfere with your Desktop sounds and PulseAudio!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in Kodi. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

=== References ===
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

HOW-TO:Install Kodi for Linux

2015-01-15T07:30:54Z

Fritsch: Make clear what we support

{{mininav| [[Installing]] {{l2| [[Linux]] }} }}
{{see also|Linux FAQ}}

These are instructions for people who already have a Linux-based OS setup, or wish to do their own installation of Linux. Alternatively you can try out [[XBMCbuntu]], which will install both an OS and {{kodi}} with an easy installer.

{{Kodi migration note}}

= Official Team Kodi repositories =

== Ubuntu ==
;Simple Install Instructions

{{note|1=[http://help.ubuntu.com/community/UsingTheTerminal Click here to find out how to use the terminal.]}}

Use the command line terminal and enter the following commands. Follow the prompts as you would any other software installation.

<syntaxhighlight lang="bash">
sudo apt-get install python-software-properties pkg-config
sudo apt-get install software-properties-common
sudo add-apt-repository ppa:team-xbmc/ppa
sudo apt-get update
</syntaxhighlight>
<syntaxhighlight lang="bash">
sudo apt-get install kodi
</syntaxhighlight>

{{#lst:Team XBMC PPA|repos}}

=== Upgrading ===
<section begin="Ubuntu upgrade" />
To update XBMC/Kodi when a new version is released, just do a general system/package or use the following commands in the terminal (or via [[SSH]]):

<syntaxhighlight lang="bash">
sudo apt-get update
sudo apt-get upgrade
</syntaxhighlight>
<section end="Ubuntu upgrade" />

=== KodiBuntu ===
{{main|KodiBuntu}}
{{#lst:KodiBuntu|intro}}

=== Installing a development build ===
{{see also|Development builds}}
To install a beta/unstable version of {{kodi}} you must first add the unstable repository, then install XBMC:

Use <code>ppa:team-xbmc/xbmc-nightly</code> for nightly builds and <code>ppa:team-xbmc/unstable</code> for [[beta]] builds.

<syntaxhighlight lang="bash">
sudo add-apt-repository ppa:team-xbmc/xbmc-nightly
sudo apt-get update
sudo apt-get install kodi
</syntaxhighlight>

Follow the prompts to add the repository, then to add the updates, and finally install the new version of Kodi.

=== Going back to a stable version from a development version ===
To return to a stable release:

Find the current PPA you are using:
<syntaxhighlight lang="bash">
sudo apt-cache policy | grep team-xbmc
</syntaxhighlight>

Remove the unstable or nightly PPA where it says '''PPAHERE''':
<syntaxhighlight lang="bash">
sudo add-apt-repository -r ppa:PPAHERE
</syntaxhighlight>

Then restore the stable version with the following commands:
<syntaxhighlight lang="bash">
sudo add-apt-repository ppa:team-xbmc/ppa
sudo apt-get update
sudo apt-get remove kodi
sudo apt-get install kodi
</syntaxhighlight>

=== Downgrading ===
{{note|If you have existing settings then they probably won't migrate well to the older version. Especially add-ons and library data. It is recommended that you start fresh ''(delete the [[userdata folder]] and parent .kodi/.xbmc folder)'' or restore from a [[backup]] that works with the older version you are installing.}}

Use these commands if you need to downgrade. For example, from Kodi v14 to XBMC v13.2:

<syntaxhighlight lang="bash" enclose="div">
sudo apt-get update
sudo apt-get install xbmc=2:13.2* xbmc-bin=2:13.2*
</syntaxhighlight>

Note the version number after "<code>xbmc=2:</code>". For older Kodi versions replace "xbmc" with "kodi" for both <code>xbmc</code> and <code>xbmc-bin</code>.

For a full list of available versions type in this command:

<syntaxhighlight lang="bash" enclose="div">
sudo apt-cache policy xbmc
</syntaxhighlight>

or

<syntaxhighlight lang="bash" enclose="div">
sudo apt-cache policy kodi
</syntaxhighlight>

=== Uninstalling ===
If you need to remove and purge an application and finally removing/purging also the application configurations files, do so by using the following commands:

<syntaxhighlight lang="bash" enclose="div">
sudo apt-get update
sudo apt-get remove kodi*
sudo apt-get purge kodi*
</syntaxhighlight>

Then remove the settings folder to remove all settings and library data. This will not delete any videos or music, but just the settings and library data itself:
<syntaxhighlight lang="bash">
rm ~/.kodi/
</syntaxhighlight>
or
<syntaxhighlight lang="bash" enclose="div">
rm ~/.xbmc/ # for older versions before 14.0
</syntaxhighlight>

= Other repositories =


Unofficial Linux binaries that are un/semi supported by Team Kodi. Most of those binaries use system ffmpeg or even worse totally untested libav, which is not recommended for {{kodi}} as we support ffmpeg only.

== Debian ==
http://people.debian.org/~rbalint/ppa/xbmc-ffmpeg/

== Fedora ==

Refer to [[HOW-TO:Install Kodi on Fedora 21 using RPMFusion packages]] for a guide showing how to install Fedora 21 and Kodi to create a quick-booting, standalone style of media player.

FedoraProject also has [http://fedoraproject.org/wiki/HTPC this page] discussing how to build a dedicated home theatre.

== OpenELEC ==
{{main|OpenELEC}}
{{#lst:OpenELEC|intro}}

= Installation from source =

If distribution packages are not available, or you need a newer version, or specific features enabled, then you will most likely need to compile from source. While compiling from source does not differ very much between distributions (except for installation of build dependencies), a few different guides are available in this wiki.

* [[HOW-TO compile XBMC for Linux from source code]]
* [[HOW-TO compile XBMC for Linux on Debian/Ubuntu]] - This is a tutorial on how to compile and install {{kodi}} on Debian and Ubuntu.

= See also =
* [[Linux]]
* [[HOW-TO:Autostart XBMC for Linux]]

{{Helix updated}}

[[Category:Linux]]
[[Category:How-to]]
[[Category:Installation|Linux]]
[[Category:Manual]]

PulseAudio

2014-12-10T09:17:05Z

Fritsch: /* PulseAudio Output Configuration */

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when XBMC is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows XBMC playback of video or audio to be paused in order to run a game, Skype or similar. XBMC is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within XBMC, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device XBMC required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in XBMC when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the XBMC implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode XBMC must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by XBMC to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by XBMC, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio. Als Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see Known issues), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in xbmc ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| XBMC Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within xbmc will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|XBMC Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

xbmc will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside xbmc, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination xbmc will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your XBMC computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with XBMC.
* You use xbmc in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, xbmc audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use XBMC as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that xbmc chooses, might be busy or even might vanish while you are using xbmc, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|But you know that doing so, it will cause problems!}}

Yes, you can - start xbmc from terminal with:
<pre>AE_SINK=ALSA xbmc</pre>
: Be warned as this might interfere with your Desktop sounds and PulseAudio!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in xbmc. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

=== References ===
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2014-12-10T09:14:54Z

Fritsch: /* Setup Guide */

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when XBMC is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows XBMC playback of video or audio to be paused in order to run a game, Skype or similar. XBMC is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within XBMC, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device XBMC required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in XBMC when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the XBMC implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode XBMC must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by XBMC to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by XBMC, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio. Als Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see FAQ), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in xbmc ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| XBMC Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''. If '''Passthrough''' was not configured with pavucontrol - no '''Passthrough''' setting within xbmc will be available.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|XBMC Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

xbmc will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside xbmc, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination xbmc will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your XBMC computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with XBMC.
* You use xbmc in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, xbmc audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use XBMC as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that xbmc chooses, might be busy or even might vanish while you are using xbmc, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|But you know that doing so, it will cause problems!}}

Yes, you can - start xbmc from terminal with:
<pre>AE_SINK=ALSA xbmc</pre>
: Be warned as this might interfere with your Desktop sounds and PulseAudio!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in xbmc. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

=== References ===
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2014-12-10T09:13:12Z

Fritsch: Dolby Pro Logic II

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when XBMC is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows XBMC playback of video or audio to be paused in order to run a game, Skype or similar. XBMC is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within XBMC, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device XBMC required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in XBMC when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the XBMC implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode XBMC must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by XBMC to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by XBMC, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio. Als Pulseaudio will always open the number of channels you have configured. You can stop it doing upmixing (see FAQ), but it will still open all configured channels which makes Dolby Pro Logic II of your AVR not usable.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in xbmc ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| XBMC Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|XBMC Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

xbmc will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside xbmc, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination xbmc will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your XBMC computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with XBMC.
* You use xbmc in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, xbmc audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use XBMC as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that xbmc chooses, might be busy or even might vanish while you are using xbmc, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|But you know that doing so, it will cause problems!}}

Yes, you can - start xbmc from terminal with:
<pre>AE_SINK=ALSA xbmc</pre>
: Be warned as this might interfere with your Desktop sounds and PulseAudio!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in xbmc. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

=== References ===
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2014-12-07T12:51:23Z

Fritsch: No passthrough when combine sink in use.

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when XBMC is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows XBMC playback of video or audio to be paused in order to run a game, Skype or similar. XBMC is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within XBMC, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device XBMC required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in XBMC when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the XBMC implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode XBMC must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by XBMC to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by XBMC, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in xbmc ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| XBMC Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|XBMC Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

xbmc will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music you will realize that direct passthrough output for your movies won't be working anymore, too. This is a pulseaudio bug, cause the combine sink is not deconstructed fast enough internally while the passthrough opening is always exclusive. It will work however if your passthrough device is not part of the device combination. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside xbmc, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination xbmc will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your XBMC computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with XBMC.
* You use xbmc in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, xbmc audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use XBMC as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that xbmc chooses, might be busy or even might vanish while you are using xbmc, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|But you know that doing so, it will cause problems!}}

Yes, you can - start xbmc from terminal with:
<pre>AE_SINK=ALSA xbmc</pre>
: Be warned as this might interfere with your Desktop sounds and PulseAudio!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in xbmc. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

=== References ===
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2014-12-07T12:46:55Z

Fritsch: Make it even more clear why we don't have a device chooser

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when XBMC is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows XBMC playback of video or audio to be paused in order to run a game, Skype or similar. XBMC is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within XBMC, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device XBMC required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in XBMC when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the XBMC implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode XBMC must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by XBMC to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by XBMC, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in xbmc ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| XBMC Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|XBMC Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

xbmc will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music and the direct passthrough output for your movies, you get probably best out of both worlds. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside xbmc, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination xbmc will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your XBMC computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with XBMC.
* You use xbmc in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, xbmc audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use XBMC as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
* Whenever '''PulseAudio''' is running your '''ALSA''' device that xbmc chooses, might be busy or even might vanish while you are using xbmc, when system sounds are playing and pulseaudio is trying to access the device again. Out of this reason we also won't implement a selection box to decide between '''ALSA''' and '''PULSE''', because it will actively harm users. Advanced Users can go with the workaround listed beneath.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|But you know that doing so, it will cause problems!}}

Yes, you can - start xbmc from terminal with:
<pre>AE_SINK=ALSA xbmc</pre>
: Be warned as this might interfere with your Desktop sounds and PulseAudio!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in xbmc. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

=== References ===
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

Advancedsettings.xml

2014-12-07T09:56:16Z

Fritsch: Add new setting forcevaapienabled to use vaapi on non intel hw. Remove old mpeg4 settings not existent anymore.

{{TOC right}}{{mininav|[[Settings]]|page=advancedsettings.xml}}
{{bigger|{{note|'''The advancedsettings.xml file does not exist by default. You have to create it first!'''}} }}

<section begin="intro" />The [[advancedsettings.xml]] file, which does not exist by default, can be created by a user in their '''[[userdata folder]]'''. This file is used for advanced settings and options that do not have GUI controls inside of XBMC. Some settings are experimental or very rarely set, so they can only be used via the advancedsettings.xml file. The file is simply a plain text file and can be edited by various text editors, so long as the name is "advancedsettings.xml". These advanced settings can be used to tweak various things such as episode naming patterns, special network ports, special behaviors, and more.<section end="intro" />

The following page will describe the structure of the advancedsettings.xml file and the various individual settings.

{{note|
# All XML tags must be lowercase. The start and end of the advancedsettings.xml file must have the <advancedsettings> and </advancedsettings> tags.
# XBMC will only read the advancedsettings.xml file when it starts up. If you make changes while XBMC is running then you must restart XBMC.
# For some Windows versions, XBMC has two <code>\userdata\</code> folders. The correct one to put the advancedsettings.xml file in is not the one in Program Files, but in <code>%appdata%\XBMC\userdata\.</code>}}

== Layout ==

The layout of <code>advancedsettings.xml</code> is as follows:

<syntaxhighlight lang="xml" enclose="div">
<advancedsettings>
<setting>value</setting>
...
<setting>value</setting>
</advancedsettings>
</syntaxhighlight>

where "setting" gives the name of the setting, and "value" gives it's value.

A list of the available "setting" strings and their values is given below.

= List of available settings =

== Troubleshooting settings ==

=== loglevel ===
{{Anchor|.3Cloglevel.3E}}
{{see also|debug log}}
<section begin="loglevel" />
{{xml setting
| tag name = loglevel
| tag attribute = hide
| tag attribute type = true_false
| tag attribute values =
{{option values
| value1= true | value1 description= Hides "enable debugging" guisetting.
| value2= false | value2 description= "enable debugging" guisetting will switch between min(loglevel, 0) and max(loglevel, 2) for off and on respectively. '''(Default)'''
}}
| tag attribute default values = true
| option type = list
| option values =
{{option values
| value1= -1 | value1 description= No logging, suppresses all log output
| value2= 0 | value2 description= Normal logging, only logging errors '''(Default)'''
| value3= 1 | value3 description= Debug logging ''(without showing text on screen)''
| value4= 2 | value4 description= Debug logging with freemem, fps and cpu usage shown on screen
| value5= 3 | value5 description= Debug logging with freemem, fps and cpu usage and full smb logging
}}
| default values = 0
| example values =
| platform = all
| XBMC version = 8-12
| description =
The logging level that XBMC will use to log errors and information. The "hide" attribute is optional.
| example =
Example:
<syntaxhighlight lang="xml" enclose="div">
<loglevel hide="false">1</loglevel>
</syntaxhighlight>

<br />

{{Note| If debugging is switched on in the GUI, loglevel will be set to 2 (''log to both file and on-screen information''); this will over-ride any <code>advancedsettings.xml</code> setting.}}<br />

{{Note| If debugging is switched on in the GUI when XBMC is shut down, then it will be automatically be re-enabled at level 2 when XBMC is re-started. This is true even if 'hide' is subsequently set to 'true' - in other words, if you enable it in the GUI and then hide the GUI toggle, it will stay on level 2 irrespective of what you subsequently set in <code>advancedsettings.xml</code>.}}<br />
}}
<section end="loglevel" />

=== jsonrpc ===
{{Anchor|.3Cjsonrpc.3E}}
To make it easier for developers using the [[JSON RPC]] API in their (third party) applications to debug during development the json output of XBMC can be prettified by setting '''compactoutput''' to '''false'''. Default json output mode is a compact print which does not contain any unnecessary whitespaces and therefore is difficult to read for humans.
Furthermore using the '''tcpport''' setting it is possible to change the default TCP port used by XBMC for JSON RPC (which is 9090) to any other valid port.

Example:
<syntaxhighlight lang="xml" enclose="div">
<jsonrpc>
<compactoutput>false</compactoutput>
<tcpport>9999</tcpport>
</jsonrpc>
</syntaxhighlight>

=== other - enableairtunesdebuglog ===
{{see|#enableairtunesdebuglog}}

== Audio/video playback settings ==

=== skiploopfilter ===
{{anchor|.3Cskiploopfilter.3E}}
The amount of the loop filter to skip on h264 decoding. This can help the performance of slower machines when decoding h264 content. Values, in decreasing CPU usage (and decreasing quality)
* -16 None
* 0 Skip only empty frames (default)
* 8 Skip non-reference frames (default on ATV)
* 16 Skip bi-dir frames
* 32 Skip all non-key frames
* 48 Skip all frames
Example:
<syntaxhighlight lang="xml" enclose="div">
<skiploopfilter>8</skiploopfilter>
</syntaxhighlight>

=== video ===
{{anchor|.3Cvideo.3E}}
{{see also|HOW-TO:Modify automatic watch and resume points|HOW-TO:Modify time seeking}}
<syntaxhighlight lang="xml" enclose="div">
<video>
<subsdelayrange>10</subsdelayrange> 
<audiodelayrange>10</audiodelayrange> 
<smallstepbackseconds>7</smallstepbackseconds> 
<usetimeseeking>true</usetimeseeking> 
<timeseekforward>30</timeseekforward> 
<timeseekbackward>-30</timeseekbackward> 
<timeseekforwardbig>600</timeseekforwardbig> 
<timeseekbackwardbig>-600</timeseekbackwardbig> 
<percentseekforward>2</percentseekforward> 
<percentseekbackward>-2</percentseekbackward> 
<percentseekforwardbig>10</percentseekforwardbig> 
<percentseekbackwardbig>-10</percentseekbackwardbig> 
<blackbarcolour>1</blackbarcolour> 
<fullscreenonmoviestart>true</fullscreenonmoviestart> 
<defaultplayer>dvdplayer</defaultplayer> 
<excludefromscan> 
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromscan>
<excludefromlisting> 
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
<playcountminimumpercent>90</playcountminimumpercent> 
<ignoresecondsatstart>180</ignoresecondsatstart> 
<ignorepercentatend>8</ignorepercentatend>


<forcevaapienabled>true</forcevaapienabled> 

<vdpauscaling>true</vdpauscaling>


<enablehighqualityhwscalers>true</enablehighqualityhwscalers> 
<ppffmpegdeinterlacing>linblenddeint</ppffmpegdeinterlacing> 
<ppffmpegpostprocessing>ha:128:7,va,dr</ppffmpegpostprocessing> 
<autoscalemaxfps>30</autoscalemaxfps> 



<adjustrefreshrate>









<override>
<fps>23.976</fps> 
<refresh>60.0</refresh> 
</override>

<override>
<fpsmin>29.96</fpsmin> 
<fpsmax>30.01</fpsmax>
<refreshmin>59.0</refreshmin> 
<refreshmax>61.0</refreshmax>
</override>




<fallback>
<refresh>50.0</refresh> 
</fallback>


<fallback>
<refreshmin>49.0</refreshmin>
<refreshmax>51.0</refreshmax>
</fallback>




</adjustrefreshrate>

<checkdxvacompatibility>value</checkdxvacompatibility>


<useocclusionquery>-1</useocclusionquery> 
<fpsdetect>1</fpsdetect> 



<latency>


<delay>0</delay>




<refresh>
<min>23</min>
<max>24</max>
<delay>125</delay>
</refresh>


<refresh>
<rate>50</rate>
<delay>50</delay>
</refresh>

</latency>

<stereoscopicregex3d>[-. _]3d[-. _]</stereoscopicregex3d>
<stereoscopicregexsbs>[-. _]h?sbs[-. _]</stereoscopicregexsbs>
<stereoscopicregextab>[-. _]h?tab[-. _]</stereoscopicregextab>
<stagefright>

<useavccodec>-1</useavccodec>
<usevc1codec>-1</usevc1codec>
<usevpxcodec>-1</usevpxcodec>
<usemp4codec>-1</usemp4codec>
<usempeg2codec>-1</usempeg2codec>
<useswrenderer>false</useswrenderer>
</stagefright>
<mediacodec>

<useavccodec>-1</useavccodec>
<usevc1codec>-1</usevc1codec>
<usevpxcodec>-1</usevpxcodec>
<usemp4codec>-1</usemp4codec>
<usempeg2codec>-1</usempeg2codec>
<useswrenderer>false</useswrenderer>
</mediacodec>
<disablehi10pmultithreading>false</disablehi10pmultithreading> 
</syntaxhighlight>
{{helix box|1=
<syntaxhighlight lang="xml" enclose="div">

<disableswmultithreading>false</disableswmultithreading> 
<dxvaallowhqscaling>false</dxvaallowhqscaling> 
<useffmpegvda>false</useffmpegvda> 
</syntaxhighlight>
}}
<syntaxhighlight lang="xml" enclose="div">
</video>
</syntaxhighlight>

=== audio ===
{{anchor|.3Caudio.3E}}
<syntaxhighlight lang="xml" enclose="div">
<audio>

<headroom>0</headroom>

<defaultplayer>paplayer</defaultplayer>

<excludefromscan>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromscan>

<excludefromlisting>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromlisting>

<ac3downmixgain>12.0</ac3downmixgain>

<playcountminimumpercent>99</playcountminimumpercent>

<applydrc>true</applydrc>

<dvdplayerignoredtsinwav>false</dvdplayerignoredtsinwav>

<limiterhold>0.025</limiterhold>

<limiterrelease>0.1</limiterrelease>
</audio>
</syntaxhighlight>

For more information on the configuration of audio under Frodo see [[AudioEngine/HOW-TO: Configure audio]]

=== measurerefreshrate ===
{{anchor|.3Cmeasurerefreshrate.3E}}
When using "Sync playback to display" on Windows, the detected refreshrate might be wrong.
When enabling measurerefreshrate, the refreshrate is measured instead, which makes it more accurate.

<syntaxhighlight lang="xml" enclose="div">
<measurerefreshrate>true</measurerefreshrate>
</syntaxhighlight>

=== edl ===
{{anchor|.3Cedl.3E}}
{{main|EDL}}
Commercial break detection not as good you think it could be? Are some commercial breaks in a series of adverts not being skipped? Are some parts being skipped that are clearly not commercials? Does the end of the previous recording still show? The following advanced settings can be used to better identify full commercial break sequences, remove incorrectly flagged commercial breaks, and have playback start at the actual beginning of the recording.

<syntaxhighlight lang="xml" enclose="div">
<edl>

<mergeshortcommbreaks>false</mergeshortcommbreaks>

<maxcommbreaklength>250</maxcommbreaklength>

<mincommbreaklength>90</mincommbreaklength>

<maxcommbreakgap>120</maxcommbreakgap>

<commbreakautowait>0</commbreakautowait>

<commbreakautowind>0</commbreakautowind>
</edl>
</syntaxhighlight>

=== pvr ===
{{anchor|.3Cpvr.3E}}
<syntaxhighlight lang="xml" enclose="div">
<pvr>
<timecorrection>0</timecorrection> 
<infotoggleinterval>3000</infotoggleinterval> 
<minvideocachelevel>5</minvideocachelevel> 
<minaudiocachelevel>10</minaudiocachelevel> 
<cacheindvdplayer>true</cacheindvdplayer> 
<channeliconsautoscan>true</channeliconsautoscan> 
<autoscaniconsuserset>false</autoscaniconsuserset> 
<numericchannelswitchtimeout>1000</numericchannelswitchtimeout> 
</pvr>
</syntaxhighlight>

=== epg ===
{{anchor|.3Cpvr.3E}}
<syntaxhighlight lang="xml" enclose="div">
<epg>
<lingertime>1440</lingertime> 
<updatecheckinterval>300</updatecheckinterval> 
<lingercleanupintervaltime>900</cleanupinterval> 
<activetagcheckinterval>60</activetagcheckinterval> 
<retryinterruptedupdateinterval>30</retryinterruptedupdateinterval> 
<updateemptytagsinterval>60</updateemptytagsinterval> 
<displayupdatepopup>true</displayupdatepopup> 
<displayincrementalupdatepopup>false</displayincrementalupdatepopup> 
</epg>
</syntaxhighlight>

=== forcedswaptime ===
{{anchor|.3Cforcedswaptime.3E}}
Use to force a backbuffer->frontbuffer swap while vsync is enabled. Set to the time (in ms) to allow for the swap (e.g. <forcedswaptime>1</forcedswaptime> is typical).

Default: Off

== Video library settings ==

=== videoextensions ===
{{anchor|.3Cvideoextensions.3E}}<section begin="videoextensions" />
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Video windows.

Default extensions for VIDEOS:
<pre>
.m4v .3gp .nsv .ts .ty .strm .rm .rmvb .m3u .ifo .mov .qt .divx .xvid .bivx .vob .nrg .img
.iso .pva .wmv .asf .asx .ogm .m2v .avi .bin .dat .dvr-ms .mpg .mpeg .mp4 .mkv .avc .vp3
.svq3 .nuv .viv .dv .fli .flv .rar .001 .wpl .zip
</pre>
Examples:
<syntaxhighlight lang="xml" enclose="div">
<videoextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</videoextensions>
</syntaxhighlight>
<section end="videoextensions" />

=== discstubextensions ===
{{anchor|.3Cdiscstubextensions.3E}}
A list of additional file-extensions that will (<tt><add></tt>) or will not (<tt><remove></tt>) be treated as disc stubs.

Default extensions for DISC STUBS:
<pre>
.disc
</pre>

Examples:
<syntaxhighlight lang="xml" enclose="div">
<discstubextensions>
<add>.dvd|.blu</add>
<remove>.cd|.vhs</remove>
</discstubextensions>
</syntaxhighlight>

=== languagecodes ===
{{anchor|.3Clanguagecodes.3E}}
Translation table for subtitle and audio names. Contains entries of the form

<syntaxhighlight lang="xml" enclose="div">
<languagecodes>
<code>
<short>alt</short>
<long>Alternate</long>
</code>
</languagecodes>
</syntaxhighlight>

=== sorttokens ===
{{anchor|.3Csorttokens.3E}}
Allows you to specify additional tokens that will be ignored at the start of lines during sorting.
<syntaxhighlight lang="xml" enclose="div">
<sorttokens>
<token>the</token>
</sorttokens>
</syntaxhighlight>

=== moviestacking ===
{{anchor|.3Cmoviestacking.3E}}<section begin="moviestacking" />
This is used by the [[File Stacking]] algorithm to combine multi-part files and contains a list of "''[[Regular Expression (RegEx) Tutorial|Regular Expressions]]''"

As of XBMC v9.11, video stacking regular expressions '''must''' contain exactly four (4) capture expressions. Old ones and three capture expressions are dropped (see [[Log file|log]]). More information on how the algorithm works is available [[File Stacking#How does it work.3F|here]].

Default:
<syntaxhighlight lang="xml" enclose="div">
<moviestacking>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck]|d)[ _.-]*[0-9]+)(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck]|d)[ _.-]*[a-d])(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ ._-]*[a-d])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="append"</tt> or <tt>append="yes"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the end.

Example:
<syntaxhighlight lang="xml" enclose="div">
<moviestacking action="append">

<regexp>(.*?)([ ._-]*[0-9])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="prepend"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the beginning.

Example:
<syntaxhighlight lang="xml" enclose="div">
<moviestacking action="prepend">
<regexp>(Title)(Volume)(Ignore)(Extension)</regexp>
</moviestacking>
</syntaxhighlight>

If no argument is supplied, or the argument <tt>append="no"</tt> is supplied, the default moviestacking regular expressions are overwritten by the user specified ones.
<section end="moviestacking" />

=== cleandatetime ===
{{anchor|.3Ccleandatetime.3E}}
Matches a year number in a string using a ''[[Regular Expression (RegEx) Tutorial|Regular Expression]]''

Default expression:
<syntaxhighlight lang="xml" enclose="div">
<video>
<cleandatetime>(.+[^ _\,\.\[\]\-])[ _\.\[\]\-]+(19[0-9][0-9]|20[0-1][0-9])([ _\,\.\[\]\-][^0-9]|$)</cleandatetime>
</video>
</syntaxhighlight>
:* The string found before will be used as basis string getting cleaned by the cleanstrings expressions.
:* By default date formats like MM:YY are ignored.

=== cleanstrings ===
{{anchor|.3Ccleanstrings.3E}}
Clean unwanted characters from filenames or folders by using a list of ''[[Regular Expression (RegEx) Tutorial|Regular Expressions]]''. Please note that everything right of the match (at the end of the file name) is removed, so if you would have a file named ''Super movie.mp4'' and would add <tt><regexp> </regexp></tt> (only a space), the only thing that would be left is ''Super'', which is probably not what you want.

Default expressions:
<syntaxhighlight lang="xml" enclose="div">
<video>
<cleanstrings>
<regexp>[ _\,\.\[\]\-](ac3|dts|custom|dc|divx|divx5|dsr|dsrip|dutch|dvd|dvdrip|dvdscr|dvdscreener|screener|dvdivx|cam|fragment|fs|hdtv|hdrip|hdtvrip|internal|limited|multisubs|ntsc|ogg|ogm|pal|pdtv|proper|repack|rerip|retail|cd[1-9]|r3|r5|bd5|se|svcd|swedish|german|read.nfo|nfofix|unrated|ws|telesync|ts|telecine|tc|brrip|bdrip|480p|480i|576p|576i|720p|720i|1080p|1080i|hrhd|hrhdtv|hddvd|bluray|x264|h264|xvid|xvidvd|xxx|www.www|\[.*\])([ _\,\.\[\]\-]|$)</regexp>
<regexp>(\[.*\])</regexp>
</cleanstrings>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== tvshowmatching ===
{{anchor|.3Ctvshowmatching.3E}}
Matches the season and episode numbers in file paths by using a list of ''[[Regular Expression (RegEx) Tutorial|Regular Expressions]]''

Defaults:
<syntaxhighlight lang="xml" enclose="div">
<tvshowmatching>
<regexp>[Ss]([0-9]+)[][ ._-]*[Ee]([0-9]+)([^\\/]*)$</regexp> 
<regexp>[\._ -]()[Ee][Pp]_?([0-9]+)([^\\/]*)$</regexp> 
<regexp>([0-9]{4})[\.-]([0-9]{2})[\.-]([0-9]{2})</regexp> 
<regexp>([0-9]{2})[\.-]([0-9]{2})[\.-]([0-9]{4})</regexp> 
<regexp>[\\/\._ \[\(-]([0-9]+)x([0-9]+)([^\\/]*)$</regexp> 
<regexp>[\\/\._ -]([0-9]+)([0-9][0-9])([\._ -][^\\/]*)$</regexp> 
<regexp>[\/._ -]p(?:ar)?t[_. -]()([ivx]+)([._ -][^\/]*)$</regexp> 
</tvshowmatching>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)
:* Expressions are converted to lower case before being evaluated. ''(XBMC v13.0 alpha4 and earlier only)''
:* Paths are converted to lower case before matching.
:* Examples of matching regexps for certain filenames can be found on the [[TV Shows (Video Library)|TV shows]] page.

:* For multi-episode matching to work, there needs to be a third set of parentheses '()' at the end, this part is fed back into the regexp engine.

:* A [http://forum.xbmc.org/showthread.php?t=51614 forum thread] has a discussion of pre-made regex lists to match common names. These drastically improve XMBC's ability to match TV show names, at the risk of some additional false positives.

==== Filenames without Season ====
There are two methods to add episodes without a season in their file path. Both ways will force the season to '1', so that you can use
the 'Use Absolute Ordering (Single Season)' setting from the TheTvDb.com scraper.

; Simple Method ''(XBMC v9.11 onwards)''
: Use only one pair of parentheses
<syntaxhighlight lang="xml" enclose="div"><regexp>[/\._ \-]([0-9]+)</regexp></syntaxhighlight>
; Advanced Method ''(XBMC v10.05 onwards)''
: Supports multi-episode files without season
: Use an empty pair of parentheses for the season
<syntaxhighlight lang="xml" enclose="div"><regexp>[/\._ \-]()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

=== tvmultipartmatching ===
{{anchor|.3Ctvmultipartmatching.3E}}
Matches a multipart episode number based on a previously identified episode file, using a list of ''[[Regular Expression (RegEx) Tutorial|Regular Expressions]]''.

Default:
<syntaxhighlight lang="xml" enclose="div">
<tvmultipartmatching>^[-_ex]+([0-9]+(?:(?:[a-i]|\\.[1-9])(?![0-9]))?)</tvmultipartmatching>
</syntaxhighlight>
:* Text matching is compared case-insensitive.
:* Specifying this option '''replaces''' the default value

=== excludefromscan ===
{{anchor|.3Cexcludefromscan.3E}}
Matches filenames or folders which should be excluded from a library scan (except tvshows) using a list of ''[[Regular Expression (RegEx) Tutorial|Regular Expressions]]''. This can be for both Video or Audio sections of <tt>advancedsettings.xml</tt>.

Defaults:
<syntaxhighlight lang="xml" enclose="div">
<video>
<excludefromscan>
<regexp>-trailer</regexp>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludefromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== excludefromlisting ===
{{anchor|.3Cexcludefromlisting.3E}}
<syntaxhighlight lang="xml" enclose="div">
<video>
<excludefromlisting> 
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</video>
</syntaxhighlight>

=== excludetvshowsfromscan ===
{{anchor|.3Cexcludetvshowsfromscan.3E}}
Matches filenames or folders which should be excluded from a tvshow library scan using a list of ''[[Regular Expression (RegEx) Tutorial|Regular Expressions]]''

Defaults:
<syntaxhighlight lang="xml" enclose="div">
<video>
<excludetvshowsfromscan>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludetvshowsfromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== trailermatching ===
{{anchor|.3Ctrailermatching.3E}}
Contains "''[[Regular Expression (RegEx) Tutorial|Regular Expression]]''" syntax (commonly referred to as "''[[Regular Expression (RegEx) Tutorial|RegEx]]''" or "''[[Regular Expression (RegEx) Tutorial|RegExp]]''") to match the locally stored trailers to movies in the library.

<syntaxhighlight lang="xml" enclose="div">
<trailermatching>

<regexp>(.*?)(_Trailer)(\.[^.]+)$</regexp>
</trailermatching>
</syntaxhighlight>

=== videolibrary ===
{{anchor|.3Cvideolibrary.3E}}
Options specific to the Video Library

<syntaxhighlight lang="xml" enclose="div">
<videolibrary>
<allitemsonbottom>false</allitemsonbottom> 
<backgroundupdate>false</backgroundupdate> 

<cleanonupdate>false</cleanonupdate> 
<hideallitems>false</hideallitems> 
<hideemptyseries>false</hideemptyseries> 
<recentlyaddeditems>35</recentlyaddeditems> 
<itemseparator> / </itemseparator> 
<exportautothumbs>false</exportautothumbs> 
<importwatchedstate>false</importwatchedstate> 
<importresumepoint>false</importresumepoint> 
<mymovies> 
<categoriestogenres>false</categoriestogenres> 
</mymovies>
<dateadded>1</dateadded> 
</videolibrary>
</syntaxhighlight>

=== videoscanner ===
{{anchor|.3Cvideoscanner.3E}}
Options specific to the Video scanner
<syntaxhighlight lang="xml" enclose="div">
<videoscanner>
<ignoreerrors>true</ignoreerrors> 
</videoscanner>
</syntaxhighlight>

=== myth ===
{{anchor|.3Cmyth.3E}}
Not seeing all the recordings you expected in the Movies folder? If so, it's very likely that the electronic program guide (EPG) used by MythTV doesn't accurately distinguish between TV Shows and Movies all the time. The following setting allows the length of the recording to also be used to determine if a recording is a Movie.

<syntaxhighlight lang="xml" enclose="div">
<myth>

<movielength>0</movielength>
</myth>
</syntaxhighlight>

== Library artwork ==

=== imageres ===
{{anchor|.3Cimageres.3E}}
This tag is new for v12 (Frodo), replacing <thumbsize>.

<section begin="imageres description" />Specify the maximal resolution that art should be resized to in pixels. The width is automatically calculated as being 16/9*height. The image will be resized to fit within this size. e.g. an image that is 2000x500 will be cached at size 1280x320. An image that is 500x800 will be cached at size 450x720 using the default value of 720.<section end="imageres description" />

<syntaxhighlight lang="xml" enclose="div">
<imageres>720</imageres>
</syntaxhighlight>

=== fanartres ===
{{anchor|.3Cfanartres.3E}}
This tag is new for v12 (Frodo), replacing <fanartheight>.

<section begin="fanartres description" />Specify the resolution that cached fanart should be resized to in pixels. The width is automatically calculated as being 16/9*height. Only images that are exactly 16x9 and equal to or greater than this resolution will be cached at this size - all other images will be cached using <imageres>. The default value is 1080.<section end="fanartres description" />

<syntaxhighlight lang="xml" enclose="div">
<fanartres>1080</fanartres>
</syntaxhighlight>

=== fanart ===
{{anchor|.3Cfanart.3E}}
As of v12 (Frodo), this tag is only used for music and not video.

A list of additional files to try when searching for fanart images. (The defaults are fanart.jpg and fanart.png which can be removed.)

Example:
<syntaxhighlight lang="xml" enclose="div">
<fanart>
<remove>fanart.jpg</remove>
<add>backdrop.jpg</add>
</fanart>
</syntaxhighlight>

=== musicthumbs ===
{{anchor|.3Cmusicthumbs.3E}}
A list of additional files to try when searching for music thumbnail images. (The default is folder.jpg which can be removed.)

Example:
<syntaxhighlight lang="xml" enclose="div">
<musicthumbs>
<remove>folder.jpg</remove>
<add>thumb.jpg|cover.jpg</add>
</musicthumbs>
</syntaxhighlight>

=== useddsfanart ===
{{anchor|.3Cuseddsfanart.3E}}
This settings allows XBMC to use your GPU rendering fanart and some other images. This will make loading images considerably faster, especially on systems with slower processors (e.g. atom based systems). Do not use this option on ARM based systems (Apple TV2/iOS/RPi/many Android systems) as it is likely to degrade performance because DDS images are not supported.

<syntaxhighlight lang="xml" enclose="div">
<useddsfanart>true</useddsfanart>
</syntaxhighlight>

== Video and music library settings ==

=== playlistasfolders ===
{{anchor|.3Cplaylistasfolders.3E}}
In the recent releases, playlists are treated as folders. Selecting a playlist no longer plays it, but opens it, as if it were a folder.

Set to false to revert to the previous behaviour. When you select a playlist, its content is added to the list of elements to be played.

:{{note|This setting will not affect smart playlists, they will always show as folders.}}

;Example
<syntaxhighlight lang="xml" enclose="div">
<playlistasfolders>true</playlistasfolders>
</syntaxhighlight>

=== playlistretries ===
{{anchor|.3Cplaylistretries.3E}}
The number of retries attempted if a source is offline. With this control you can alter the number of consecutive failed items before a playlist fails.

Default:
<syntaxhighlight lang="xml" enclose="div">
<playlistretries>100</playlistretries>
</syntaxhighlight>

=== playlisttimeout ===
{{anchor|.3Cplaylisttimeout.3E}}
The timeout, in seconds, before item failure.

Default:
<syntaxhighlight lang="xml" enclose="div">
<playlisttimeout>20</playlisttimeout>
</syntaxhighlight>

=== musicdatabase/videodatabase ===
{{anchor|.3Cmusicdatabase.3E/.3Cvideodatabase.3E}}
{{main|MySQL}}
<section begin="videodatabase" />
Allows advanced customization of the default database settings for both music and video.

:{{note| '''It is HIGHLY recommended that you not attempt to place an sqlite3 database outside of XBMC's path. sqlite3 contains no filesystem abstraction, so this will plain break on any non-local (as far as XBMC is concerned) paths. Use this for mysql only.'''}}
'''type'''

Can be either "sqlite3" or "mysql" (default: sqlite3)

'''host'''

sqlite3: defines the relative path to the database file (eg. /usr/local/xbmc/databases).

mysql: defines the host of the mysql socket (eg. localhost, 192.168.0.1, etc)

'''port'''

sqlite3: silently ignored

mysql: defines the port of the mysql socket (default: 3306)

'''name'''
:''Not needed by default, and some users report issues when defining the this tag. When not used "MyVideos"+DB number will be used.
sqlite3: defines the name of the database file to read from, excluding the ".db" extension.

mysql: defines the name of the database to use

'''user'''

sqlite3: silently ignored

mysql: defines the user with privileged access to the database

'''pass'''

sqlite3: silently ignored

mysql: defines the password for the user with privileged access to the database

'''Examples:'''

1) Configure a database for MySQL.
:{{note| ''The videodatabase and musicdatabase tags are interchangeable here.''}}
<syntaxhighlight lang="xml" enclose="div">
<videodatabase>
<type>mysql</type>
<host>192.168.0.10</host>
<name>xbmc_video</name>
<user>xbmc</user>
<pass>xbmc</pass>
</videodatabase>
</syntaxhighlight>

2) Configure a database for an sqlite database.
:{{note|''The videodatabase and musicdatabase tags are interchangeable here.''}}
<syntaxhighlight lang="xml" enclose="div">
<musicdatabase>
<type>sqlite3</type>
<host>/usr/local/share/xbmc/databases</host>
<name>xbmc_music</name>
</musicdatabase>
</syntaxhighlight>

{{note| ''If you use MySQL for the music database, but are finding that it slows down your music library significantly, execute the following query to create an index on the song table. This will significantly speed up queries using the songview views looking up by artist:'' }}

<syntaxhighlight lang="sql" enclose="div">
CREATE INDEX ixSongArtist
ON song(idArtist, idAlbum)
</syntaxhighlight>
<section end="videodatabase" />

=== externalplayer ===
{{anchor|.3Cexternalplayer.3E}}
{{see|External players}}

== Music settings ==

=== musicextensions ===
{{anchor|.3Cmusicextensions.3E}}
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Music windows.

Default extensions for MUSIC:
<pre>
.nsv .m4a .flac .aac .strm .pls .rm .mpa .wav .wma .ogg .mp3 .mp2 .m3u .mod .amf .669 .dmf .dsm .far .gdm
.imf .it .m15 .med .okt .s3m .stm .sfx .ult .uni .xm .sid .ac3 .dts .cue .aif .aiff .wpl .ape .mac .mpc
.mp+ .mpp .shn .zip .rar .wv .nsf .spc .gym .adplug .adx .dsp .adp .ymf .ast .afc .hps .xsp
</pre>

Examples:
<syntaxhighlight lang="xml" enclose="div">
<musicextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</musicextensions>
</syntaxhighlight>

=== cddbaddress ===
{{anchor|.3Ccddbaddress.3E}}
The address of the online CDDb database. You may set this to another freedb mirror if there is a more suitable one.

Default:
<syntaxhighlight lang="XML" enclose="div>
<cddbaddress>freedb.freedb.org</cddbaddress>
</syntaxhighlight>

=== songinfoduration ===
{{anchor|.3Csonginfoduration.3E}}
This controls how long the song information will remain onscreen when the song changes during visualisations. The valid range is "1" to "Indefinite (0)", in seconds. This does not include the duration of any transition effects.

Default:
<syntaxhighlight lang="xml" enclose="div">
<songinfoduration>10</songinfoduration>
</syntaxhighlight>

=== musicfilenamefilters ===
{{anchor|.3Cmusicfilenamefilters.3E}}
Contains filters to match music information (artist, title etc.) from a tag-less music filename. The first <filter> to match completely is used. Matched items include:

<pre>
%A - Artist
%T - Title
%B - Album
%N - Track number
%S - Part of set (disk number)
%D - Duration
%G - Genre
%Y - Year
%R - Rating
</pre>

Example:
<syntaxhighlight lang="xml" enclose="div">
<musicfilenamefilters>
<filter>%A - %T</filter>
</musicfilenamefilters>
</syntaxhighlight>

=== musiclibrary ===
{{anchor|.3Cmusiclibrary.3E}}
Options specific to the Music Library

<syntaxhighlight lang="xml" enclose="div">
<musiclibrary>
<hideallitems>true</hideallitems> 
<allitemsonbottom>true</allitemsonbottom> 
<backgroundupdate>true</backgroundupdate> 
<recentlyaddeditems>35</recentlyaddeditems> 
<albumssortbyartistthenyear>true</albumssortbyartistthenyear> 
<albumformat>%B - %Y</albumformat> 
<albumformatright>%A</albumformatright> 
<prioritiseapetags>true</prioritiseapetags> 
<itemseparator> / </itemseparator> 
</musiclibrary>
</syntaxhighlight>

=== karaoke ===
{{anchor|.3Ckaraoke.3E}}
{{Main|Karaoke}}<section begin="karaoke" />
<syntaxhighlight lang="xml" enclose="div">
<karaoke>

<syncdelaycdg>0.0</syncdelaycdg>

<syncdelaylrc>0.0</syncdelaylrc>

<alwaysreplacegenre>false</alwaysreplacegenre>

<storedelay>true</storedelay>

<autoassignstartfrom>1</autoassignstartfrom>

<nocdgbackground>true</nocdgbackground>

<defaultbackground type="video" path="special://masterprofile/karaokevideobg.avi"/>

<nextsongpopuptime>0.0</nextsongpopuptime>
</karaoke>
</syntaxhighlight>
<section end="karaoke" />

== Photos settings ==

=== pictureextensions ===
{{anchor|.3Cpictureextensions.3E}}
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Pictures window.

Default extensions for PICTURES:
<pre>
.png .jpg .jpeg .bmp .gif .ico .tif .tiff .tga .pcx .cbz .zip .cbr .rar .m3u
</pre>

Examples:
<syntaxhighlight lang="xml" enclose="div">
<pictureextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</pictureextensions>
</syntaxhighlight>

=== pictureexcludes ===
{{anchor|.3Cpictureexcludes.3E}}
Matches filenames or folders which should be excluded from being displayed in My Pictures using a list of ''[[Regular Expression (RegEx) Tutorial|Regular Expressions]]''

<syntaxhighlight lang="xml" enclose="div">
<pictureexcludes> 
<regexp>small</regexp>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</pictureexcludes>
</syntaxhighlight>

=== slideshow ===
{{anchor|.3Cslideshow.3E}}
<syntaxhighlight lang="xml" enclose="div">
<slideshow>

<panamount>2.5</panamount>

<zoomamount>5.0</zoomamount>



<blackbarcompensation>20</blackbarcompensation>
</slideshow>
</syntaxhighlight>

== Network settings ==

=== samba ===
{{anchor|.3Csamba.3E}}
<syntaxhighlight lang="xml" enclose="div">
<samba>
<doscodepage></doscodepage> 
<clienttimeout>10</clienttimeout> 
<statfiles>true</statfiles> 
</samba>
</syntaxhighlight>

=== hosts ===
{{anchor|.3Cfhosts.3E}}
Static dns entries which take precedence over your dns server.
<syntaxhighlight lang="xml" enclose="div">
<hosts>
<entry name="HOSTNAME">IPADDRESS</entry>
</hosts>
</syntaxhighlight>

=== network ===
{{anchor|.3Cnetwork.3E}}
{{see also|HOW-TO:Modify the cache}}
<syntaxhighlight lang="xml" enclose="div">
<network>
<curlclienttimeout>10</curlclienttimeout> 
<curllowspeedtime>5</curllowspeedtime> 
<httpproxyusername></httpproxyusername> 
<httpproxypassword></httpproxypassword> 
<cachemembuffersize>20971520</cachemembuffersize> 
<buffermode>0</buffermode> 
<readbufferfactor>1.0</readbufferfactor> 
</network>
</syntaxhighlight>

=== tuxbox ===
{{anchor|.3Ctuxbox.3E}}
<syntaxhighlight lang="xml" enclose="div">
<tuxbox>

<audiochannelselection>false</audiochannelselection>

<submenuselection>false</submenuselection>

<defaultrootmenu>0</defaultrootmenu>

<defaultsubmenu>4</defaultsubmenu>

<pictureicon>true</pictureicon>

<epgrequesttime>10</epgrequesttime>

<zapwaittime>0</zapwaittime>
</tuxbox>
</syntaxhighlight>

=== enableairtunesdebuglog ===
{{helix box|This option will be replaced by a GUI option in v14:
{{anchor|.3Cenableairtunesdebuglog.3E}}<section begin="enableairtunesdebuglog" />
This enables the debug output of libshairport which is used for the AirTunes feature. Defaults to off - because its spamming badly.

Example:
<syntaxhighlight lang="xml" enclose="div">
<enableairtunesdebuglog>1</enableairtunesdebuglog>)
</syntaxhighlight>
<section end="enableairtunesdebuglog" />
}}

=== airtunesport ===
{{anchor|.3Cairtunesport.3E}}<section begin="airtunesport" />
This overwrites the defalt listening port of the AirTunes server (announced via zeroconf).
<section end="airtunesport" />

=== airplayport ===
{{anchor|.3Cairplayport.3E}}<section begin="airplayport" />
This overwrites the default listening port of the AirPlay server (announced via zeroconf).
<section end="airplayport" />

== File system settings ==

=== packagefoldersize ===
<section begin="packagefoldersize" />
{{anchor|.3Cpackagefoldersize.3E}}
{{xml setting
| tag name = packagefoldersize
| option type = numerical
| option values =
| default values = 200
| platform = all
| XBMC version = 12
| description = The amount (in megabytes) of add-on zip packages saved from previous add-on installs. These packages are mainly used for the [[add-on]] rollback feature. Increasing the size should increase the amount of past versions saved.
| example = Example: <syntaxhighlight lang="xml" enclose="div"><packagefoldersize>200</packagefoldersize> </syntaxhighlight>
}}
<section end="packagefoldersize" />
=== detectasudf ===
{{anchor|.3Cdetectasudf.3E}}
Set to true if you wish to detect joint ISO9660/UDF disks as UDF.

Default: False

=== pathsubstitution ===
{{anchor|.3Cpathsubstitution.3E}}
'''[[Path substitution]]s''' are for use for redirecting file paths. These are processed in order, and are useful for substituting an absolute path on a PC with a path suitable for XBMC to handle.

Default: No path substitutions defined.

Example:
<syntaxhighlight lang="xml" enclose="div">
<pathsubstitution>
<substitute>
<from>G:\dvds\</from>
<to>smb://somecomputer/g-share/dvds/</to> 
</substitute>
</pathsubstitution>
</syntaxhighlight>

== Remote control settings ==

=== remotedelay ===
{{anchor|.3Cremotedelay.3E}}
The repeat delay for a LIRC remote control. A delay value between 1 and 20 before a remote button starts repeating on a long keypress (i.e. continuously sending button pushes while it's held down).

Default: 3
<syntaxhighlight lang="xml" enclose="div">
<remotedelay>10</remotedelay>
</syntaxhighlight>

=== remoterepeat ===
{{anchor|.3Cremoterepeat.3E}}
This used to adjust the amount of time in milliseconds between repeated keystrokes. Used to prevent key-bounce, in other words prevents xbmc (lirc?) seeing one key press as multiple key presses with certain remotes.

<syntaxhighlight lang="xml" enclose="div">
<remoterepeat>800</remoterepeat>
</syntaxhighlight>

=== controllerdeadzone ===
{{anchor|.3Ccontrollerdeadzone.3E}}
The controller deadzone is the region of movement around the center which is not recognized by the device. Because joysticks can have noise (report motion when still) and bias (report an offset when centered), spurious events can be reported even though the controller isn't being touched. If you notice these kinds of events, you most likely need to increase your controller's deadzone (both axes recommended). The values range from 0.0 (no deadzone, XBMC will see all input your controller is capable of registering) to 1.0 (XBMC will ignore all input inside of the device's physical limits).

<syntaxhighlight lang="xml" enclose="div">
<controllerdeadzone>0.2</controllerdeadzone>
</syntaxhighlight>

=== enablemultimediakeys ===
{{anchor|.3Cenablemultimediakeys.3E}}
This setting only has any effect on Windows versions of XBMC, and only applies to builds from 28th May 2011 onwards.
In Windows the multimedia keys generate a WM_APPCOMMAND message in addition the keypress. XBMC processes both keypresses and the WM_APPCOMMAND messages, and the end result would be that the command is executed twice. To avoid this, by default multimedia keypresses are disabled. Although it should rarely be necessary, the enablemultimediakeys setting allows you to enable the multimedia keys.

Example:
<syntaxhighlight lang="xml" enclose="div">
<enablemultimediakeys>true</enablemultimediakeys>
</syntaxhighlight>

== Other interface settings ==

=== window ===
{{anchor|.3Cwindow.3E}}
This allows you to manually set the default size of XBMC's windowed mode. If you resize the window, it will return to the set size when restarting.

WIDTH and HEIGHT are the values for each dimension, in pixels.

<syntaxhighlight lang="xml" enclose="div">
<window><width>WIDTH</width><height>HEIGHT</height></window>
</syntaxhighlight>

=== allowd3d9ex ===
{{anchor|.3Callowd3d9ex.3E}}
Applies only to Windows Vista and up. Values: true/false. Allows xbmc to use Direct3D 9Ex, which is a bit more stable and robust than Direct3D 9.

Default:
<syntaxhighlight lang="xml" enclose="div">
<allowd3d9ex>true</allowd3d9ex>
</syntaxhighlight>

=== restrictcapsmask ===
{{anchor|.3Crestrictcapsmask.3E}}
Windows only. A bitmask to prevent xbmc from using detected texture capabilities of the GPU. This helps work around buggy hardware/drivers.

1: prevent the use of compressed textures (DXT1, DXT3, DXT5)
2: prevent the use of non-power-of-two dimensions for textures
4: prevent the use of compressed textures with non-power-of-two dimensions.

<syntaxhighlight lang="xml" enclose="div">
<restrictcapsmask>0</restrictcapsmask>
</syntaxhighlight>

=== forced3d9ex ===
{{anchor|.3Cforced3d9ex.3E}}
Windows only: XBMC attempts to detect drivers released for a version earlier than Vista, to avoid using advanced features which are often not emulated correctly. The detection may be incorrect and this setting allows forcing the using of D3D9Ex.

<syntaxhighlight lang="xml" enclose="div">
<forced3d9ex>false</forced3d9ex>
</syntaxhighlight>

=== algorithmdirtyregions ===
{{anchor|.3Calgorithmdirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="algorithmdirtyregions" /> {{note|Some GPU/hardware configurations will have some minor issues (such as a visual "flicker"). For those situations try mode 2 or use the default (mode 3, which requires no advancedsetting). Almost all ARM-based devices (such as [[Android]]) willl likely have flickering issues.}}

Enable dirty-region processing. Dirty regions are any parts of the screen that have changed since the last frame. By not re-rendering what hasn't changed the GUI can be sped up. Because all GPUs work differently, only Mode 3, combined with nofliptimeout=0, is guaranteed to work for everyone without flickering issues. This mode will reduce CPU/GPU usage, but will not increase GUI speed.

{| class="prettytable"
! value !! result !! description
|-
! 0
| Off
| The entire viewport is always rendered.
|-
! 1
|Union
|All dirty regions are grouped into the smallest possible rectangle. This is typically the fastest mode for slower GPUs due to only making one pass.
|-
! 2
| {{nowrap|Cost reduction}}
| Each dirty region is presented separately, in as many passes as there are regions.
|-
! 3
| {{nowrap|Whole Screen}}
| The entire screen is rendered if there are any dirty regions. This, combined with nofliptimeout is a safe default for drivers that clear buffer contents (manifests as blinking or vibrating images). '''Default'''
|}<section end="algorithmdirtyregions" />

Example:
<syntaxhighlight lang="xml" enclose="div">
<gui>
<algorithmdirtyregions>1</algorithmdirtyregions>
</gui>
</syntaxhighlight>

=== nofliptimeout ===
{{anchor|.3Cnofliptimeout.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="nofliptimeout" />Specifies the timeout in milliseconds after which XBMC will not flip the graphics buffers anymore when nothing has been rendered, this lowers both CPU and GPU usage. Sometimes adjusting this value can help prevent flickering.

* -1: disabled
* 0 or higher: timeout in milliseconds '''(0 is default)'''
<section end="nofliptimeout" />
Example:
<syntaxhighlight lang="xml" enclose="div">
<gui>
<nofliptimeout>1000</nofliptimeout>
</gui>
</syntaxhighlight>

=== visualizedirtyregions ===
{{anchor|.3Cvisualizedirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="visualizedirtyregions" />Enable dirty-region visualization. Paints a rectangle over marked controls.

* true: on
* false: off '''(Default)'''

{{note|This is only a development mode and isn't of use to normal users.}}
<section end="visualizedirtyregions" />
Example:
<syntaxhighlight lang="xml" enclose="div">
<gui>
<visualizedirtyregions>true</visualizedirtyregions>
</gui>
</syntaxhighlight>

=== showexitbutton ===
{{anchor|.3Cshowexitbutton.3E}}
Setting to hide the exit button, useful for people running appliance based setup's where exit would only confuse/complicate the user. Modifiable via the advancedsettings.xml by setting showexitbutton to false, default is true (show)

Example:
<syntaxhighlight lang="xml" enclose="div">
<showexitbutton>true</showexitbutton>
</syntaxhighlight>

=== fullscreen ===
{{anchor|.3Cfullscreen.3E}}
Starts XBMC in full screen (check resolutions!).

<syntaxhighlight lang="xml" enclose="div">
<fullscreen>false</fullscreen>
</syntaxhighlight>

=== splash ===
{{anchor|.3Csplash.3E}}
Set to false if you wish to disable the startup splash image. Defaults to true.

<syntaxhighlight lang="xml" enclose="div">
<splash>true</splash>
</syntaxhighlight>

=== cputempcommand ===
{{anchor|.3Ccputempcommand.3E}}
Provide a shell command XBMC will use to get CPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia and Raspberry Pi</u>
<syntaxhighlight lang="xml" enclose="div">
<cputempcommand>sed -e 's/$[0-9]*$[0-9]\{3\}.*/\1 C/' /sys/class/thermal/thermal_zone0/temp</cputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang="xml" enclose="div">
<cputempcommand>echo "$(sensors -u | tail -n64 | grep temp1_input | awk '{print $2 }' |awk '{printf("%d\n",$1 + 0.5);}') C"</cputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang="xml" enclose="div">
<cputempcommand>sensors|sed -ne "s/temp1: \+[-+]$[0-9]\+$.*/\1 C/p"</cputempcommand>
</syntaxhighlight>

=== gputempcommand ===
{{anchor|.3Cgputempcommand.3E}}
Provide a shell command XBMC will use to get GPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia</u>
<syntaxhighlight lang="xml" enclose="div">
<gputempcommand>echo "$(nvidia-settings -tq gpuCoreTemp) C"</gputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang="xml" enclose="div">
<gputempcommand>echo "$(nvidia-smi -q -d TEMPERATURE | grep Gpu | cut -c35-36) C"</gputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang="xml" enclose="div">
<gputempcommand>/usr/bin/aticonfig --od-gettemperature | grep Temperature | cut -f 2 -d "-" | cut -f 1 -d "." | sed -e "s, ,," | sed 's/$/ C/'</gputempcommand>
</syntaxhighlight>

;<u>For Raspberry Pi</u>
<syntaxhighlight lang="xml" enclose="div">
<gputempcommand>/opt/vc/bin/vcgencmd measure_temp | sed -e "s/temp=//" -e "s/\..*'/ /"</gputempcommand>
</syntaxhighlight>

=== glrectanglehack ===
{{anchor|.3Cglrectanglehack.3E}}
Problems with ghosting or videos which are only played back in the left upper quarter? The following ATI hack may solve it.
<syntaxhighlight lang="xml" enclose="div">
<glrectanglehack>yes</glrectanglehack>
</syntaxhighlight>

=== alwaysontop ===
{{anchor|.3Calwaysontop.3E}}
Added in XBMC v9.11 (Windows OS only). Keeps XBMC always on top when windowed.
<syntaxhighlight lang="xml" enclose="div">
<alwaysontop>yes</alwaysontop>
</syntaxhighlight>

Alternate code.
<syntaxhighlight lang="xml" enclose="div">
<videoscreen>
<fakefullscreen>false</fakefullscreen>
</videoscreen>
</syntaxhighlight>

== Recently removed tags ==
* {{anchor|.3Cthumbsize.3E}}'''<thumbsize>''' - replaced by <[[#imageres|imageres]]> in v12 Frodo
* {{anchor|.3Cfanartheight.3E}}'''<fanartheight>''' - replaced by <[[#fanartres|fanartres]]> in v12 Frodo
* {{anchor|.3Cdvdthumbs.3E}}'''<dvdthumbs>''' - removed in v12 Frodo
* {{anchor|.3Cbginfoloadermaxthreads.3E}}'''<bginfoloadermaxthreads>''' - removed in v13 Gotham
* '''<showepginfoonselect>''' - replaced by a GUI setting in v13 Gotham
* {{anchor|.3Cbusydialogdelayms.3E}}'''<busydialogdelayms>''' - removed in v13 Gotham
* '''<resample>''', '''<forceDirectSound>''', '''<audiophile>''', '''<audiosinkbufferdurationmsec>''', '''<allowtranscode44100>''', and '''<streamsilence>''' - These were various sub-tags for <audio> that were removed in v13 Gotham and either replaced by GUI settings or were no longer needed.
* {{anchor|.3Cenableairtunesdebuglog.3E}}'''<enableairtunesdebuglog>''' replaced by a GUI option in v14 Helix
* '''<videoDisableHi10pMultithreading>''' renamed to <disableswmultithreading> in v14 Helix

== guisettings.xml settings ==
{{Note|In XBMC v13 "Gotham", using guisettings in advancedsettings.xml might not work anymore or might give unexpected results.}}

You can also define the settings normally defined in the GUI (and stored in guisettings.xml) in advancedsettings.xml. Any guisettings.xml settings defined in advancedsettings.xml will override the guisettings.xml values, and the settings will be removed completely from the XBMC's interface.

The easiest way to include a guisettings.xml setting is to first change the setting in XBMC's interface to the value that you want, and then open the '''[[userdata]]/guisettings.xml''' file and find the XML entry that corresponds to that setting.

Then just add that entry to the advancedsettings.xml file.

For instance, to set the Font Character Set (found in the appearance setting, in the Look and Feel section), you'd open up guisettings.xml and find:

<syntaxhighlight lang="xml" enclose="div">
<lookandfeel>
<charset>Hebrew (Windows)</charset>
</lookandfeel>
</syntaxhighlight>

Simply take that entry and place it in advancedsettings.xml. The option in XBMC's interface for the character set will then no longer be visible, and XBMC will always use the Hebrew (Windows) character set.

{{Gotham updated}}
{{DISPLAYTITLE:advancedsettings.xml}}

[[Category:Settings]]
[[Category:Manual]]
[[Category:Advanced topics]]

Archive:XBMC v13 (Gotham) changelog

2014-08-09T05:36:00Z

Fritsch: X11 was dropped beginning of helix cycle - gotham uses sdl bloat

{{mininav|[[Releases]]}}
{{see also|XBMC v13 (Gotham) FAQ|Gotham API changes|Releases}}

XBMC Wiki copy of the XBMC v13 (Gotham) condensed changelog for the release with a summery of larger and important features and functions.

== Changelog ==

=== Live TV and PVR (Personal Video Recorder) ===
* Added much improved PVR / EPG and Live TV interface in XBMC's GUI skinning engine (already in use in Confluence)
* Added improved PVR / DVR timeshift support to pause Live TV (note that each PVR backend still need to support timeshifting)
* Added much improved PVR / EPG extensions and notifications support over the JSON-RPC API
* Improved PVR front-end with Live TV and EPG specific windows, plus PVR stuff in OSD and GUI settings in Confluence skin
* Added, updated, and improved PVR backend clients addons for many popular third-party external [[PVR backend]] platforms:
** [[PVR/Testing|PVR Demo Client]] dummy addon with fake backend from Team-XBMC for skin development and regression testing
** [[PVR/Backend/IPTV|IPTV (IPTV Simple Client)]] PVR Addon backend client maintained and available from XBMC's community
** [[PVR/Backend/Tvheadend|Tvheadend]] PVR Addon backend clients maintained and available from XBMC's community
** [[PVR/Backend/NextPVR|NextPVR (former GB-PVR)]] PVR Addon backend client maintained and available from XBMC's community
** [[PVR/Backend/Njoy|Njoy Digital (N7)]] PVR Addon backend client maintained and available from XBMC's community
** [[PVR/Backend/MediaPortal|MediaPortal]] PVR Addon backend client maintained and available from XBMC's community
** [[PVR/Backend/MythTV|MythTV]] PVR Addon backend client maintained and available from the XBMC's community
** [[PVR/Backend/VDR|VDR (Video Disk Recorder)]] PVR Addon backend client maintained and available from XBMC's community
** [[PVR/Backend/VUPlus|Vu+ / Enigma2 / Dreambox]] PVR Addon backend client maintained and available from XBMC's community
** [[PVR/Backend/ForTheRecord|Argus TV / ForTheRecord]] PVR Addon backend client maintained and available from XBMC's community
** [[Add-on:PVR.WMC|WMC (Windows Media Center)]] PVR Addon backend client maintained and available from XBMC's community
** [[DVBLink]] PVR Addon backend client maintained and available from XBMC's community
** [[PVR/Backend/DVBViewer|DVBViewer]] PVR Addon backend client maintained and available from XBMC's community

=== Add-ons Framework, API, and Manager ===
For full changelogs on changes to all Addons APIs, see [[Gotham API changes]], the [http://forum.xbmc.org/showthread.php?tid=98551 JSON-RPC Development Forum], and the [http://forum.xbmc.org/showthread.php?tid=173943 Python Development Forum]
* Added option for allowing skins to query directories (e.g. plugins) to fill static content
* Added a Monitor class to receive JSON-RPC notifications directly through the Python bindings
* Added announce function and register addon for announcements to the Add-ons API
* Added new Built-In function to control state of attached HDMI CEC device via Add-ons API
* Added support for XBMC's Python interface to use native keyboard if possible (currently only iOS)
* Added support for addon binary reading and writing via a "buffer" class usable from addons
* Added WOL (Wake-on-LAN) with send magic packet function to the Add-ons API
* Improved the ability to [http://github.com/xbmc/xbmc/pull/901 extend XBMC's native Python API by writing C++ code generated] via [http://en.wikipedia.org/wiki/Groovy_%28programming_language%29 Groovy] and [http://en.wikipedia.org/wiki/Groovy_%28programming_language%29 SWIG]
* Improved Addons API for homebrew DIY RGB LED [http://en.wikipedia.org/wiki/Ambilight Ambilight] clone client software such as [[Add-on:XBMC Boblight|Boblight]]

=== GUI Engine (Skinning Engine) ===
For full changelog on changes to the skinning engine, see [[Gotham API changes]] and the [http://forum.xbmc.org/showthread.php?tid=158812 Skin Development Forum]
* Added support for customizable menu structure for home and beyond
* Added Stereoscopic 3D rendering support (Side-by-Side, Top-Bottom, and Anaglyph) to XBMC's GUI skinning engine
* Added Stereoscopic 3D rendering support (Side-by-Side, Top-Bottom, and Anaglyph) for Subtitles when in 3D mode
* Added a simple Movie Set management to GUI for Edit/Clear Set and Add/Remove Set members
* Added option support for both banner and poster music art types simultaneously
* Added picture tags metadata info accessible for skins or addons developers
* Added further optimizations to XBMC's GUI engine for faster rendering on low resource embedded devices
* Improved touch and gesture support for all platforms, and also improved the default touch screen skin ([[Touched]])
* Added [http://github.com/xbmc/xbmc/pull/2040 ImageFactory implementation] with factory to abstract different image libraries and hardware acceleration
* Improved [[Dirty regions|Dirty Regions]] rendering on all platforms
* Refactored settings system to consist of XML files containing descriptions of every setting

=== Platform Independent Playback ===
* Added support for H.264 (including [[Hi10P]]) multi-threaded video decoding when software decoder on CPU is used
* Added support for Forced Subtitles ("forced flag") in external subtitle files
* Added support for video playback of SageTV recordings
* Added unified buffering capability to video and overlay renderers for all internal players
* Upgraded FFmpeg (libavcodec and libavformat) audio/video codec and demuxer libraries to [http://www.ffmpeg.org/download.html#release_1.2 FFmpeg 1.2 (rev e820e3a)]

=== Library ===
* Added extensive [[MusicBrainz]] tags support to the Music Library and Database
* Added ability to queue list of items / add items to a playlist without playing them
* Improved and extended [[Smart playlists|Smart Playlists]] functionality
* Added support for scanning videos SFTP and SSH sources so can scrape metadata
* Added support for write-enabled WebDAV (delete/rename/write files and directories)
* Added "Add art" button to video artwork selection dialog
* Added support for "last played" sort option to the TV Show GUI
* Added support for OGG cover art extraction to TagLib
* Added option support for exporting music art as JPEG or PNG rather than TBN file extension
* Improved performance for SQL database queries for faster browsing

=== Web Scrapers ===
* Added theaudiodb.com music video scraper as new default for music videos

=== AudioEngine ===
* Added new cross-platform event driven active state machine pattern [[AudioEngine#ActiveAE|ActiveAE]] sink as the default for XBMC's [[AudioEngine]]
* Added ALSA sink for [[AudioEngine#ActiveAE|ActiveAE]] for Linux Desktop and generic Linux based Embedded Systems
* Added PulseAudio sink for [[AudioEngine#ActiveAE|ActiveAE]] for Linux Desktop
* Added OSS (Open Sound System) sink for [[AudioEngine#ActiveAE|ActiveAE]] for BSD, like FreeBSD, PC-BSD, and similar Unix based systems
* Added AUDIOTRACK sink for [[AudioEngine#ActiveAE|ActiveAE]] for [[Amlogic]]
* Added Pi Audio sink for [[AudioEngine#ActiveAE|ActiveAE]] for [[Raspberry Pi]]
* Added DirectSound sink for [[AudioEngine#ActiveAE|ActiveAE]] for Windows
* Added WASAPI sink for [[AudioEngine#ActiveAE|ActiveAE]] for Windows
* Added Darwin sink for [[AudioEngine#ActiveAE|ActiveAE]] for Mac OS X and iOS
* Added support for CoreAudio AudioEngine to OS notifications for device changes on Mac OS X and iOS

=== Other ===
* Added support for "Play to" and controlling remote XBMC / DLNA instance over UPnP
* Added new "Fishbmc" audio visualization addon (only OpenGL versions for Linux and Mac OS X for now)
* Added GUI settings levels for Basic, Standard, Advanced, Expert (defaults to "Standard")
* Added support and GUI settings for SOCKS 4/4a/5 proxy types and remote DNS
* Added possibility to define help descriptions ("I" key) for every setting in GUI settings
* Added option to set auto login of a specific user profile via the GUI
* Added CPU / GPU frequency and temperature for all supported Linux platforms
* Added support to allow key IDs in keyboard.xml to be in hexadecimal format
* Upgraded DVD-Video navigation and playback libraries (libdvdnav, libdvdread, and libdvdcss)
* Upgraded SAMBA client to version 3.6.x adding full support for SMB 2.0 and SMB 2.1 protocols
* Added initial support for running libxbmc.so headless (without GUI) as a background service / deamon
* Added a generic and user-mappable cross-platform touch input system
* Improved [http://en.wikipedia.org/wiki/HDMI#CEC|HDMI CEC (Consumer Electronics Control)] support for [http://libcec.pulse-eight.com/ Pulse-Eight's LibCEC]
* Moved subtitle addon core handling to core and added native support for subtitle plugin services
* Updated community maintained translations to over 60+ languages to date for XBMC via [[Translation System|Transifex Translation System]]

=== Android Specific ===
* Added first full (and stable) XBMC for [[Android]] port with multi-architecture platform support (supports ARM, MIPS, and x86)
* Added built-in command for addons and skins to execute Android apps with optional params via applicationmanager
* Added support to allow landscape and reverse landscape orientation of XBMC GUI on Android
* Added MediaCodec API (Android 4.1 API level 16) software rendering implementation support to XBMC's DVDPlayer
* Added StageFright API (Android 4.0 API level 14) hardware rendering implementation support to XBMC
* Added OpenMAX Video Acceleration API support for OpenMAX AL API on Android via StageFright and MediaCodec
* Improved the dedicated AMLPlayer video player for hardware accelerated video decoding on [[AMLogic devices|Amlogic]]
* Added external player (external player launcher) support on Android
* Added native volume control for Android from within XBMC
* Improved [http://en.wikipedia.org/wiki/ARM_architecture#Advanced_SIMD_.28NEON.29 NEON (Advanced SIMD instruction set)] CPU acceleration support for ARM architecture

=== BSD Specific ===
* Improved XBMC support for [http://en.wikipedia.org/wiki/Berkeley_Software_Distribution BSD (operating system)] on FreeBSD, PC-BSD, and other similar BSD platforms
* Improved VDPAU (NVIDIA) Hardware Acceleration Video Decoding support on BSD
* Improved VAAPI (Video Acceleration API) Hardware Acceleration Video Decoding support on BSD

=== Linux Specific ===
* Added VA-API (libva) support for decoding videos with larger resolutions than 1080p (such as 4K resolution)
* Improved ARM processor architecture ([http://www.pivosgroup.com/xios.html Pivos XIOS DS] and [[Raspberry Pi]] as reference devices)
* Improved OpenGL ES and EGL support ([http://www.pivosgroup.com/xios.html Pivos XIOS DS] and [[Raspberry Pi]] as reference devices)
* Improved VAAPI (Video Acceleration API) support (requires VAAPI compatible hardware and drivers)
* Improved VDPAU (NVIDIA) Hardware Video Acceleration and its upscaling/deinterlacing capabilities
* Improved OpenMAX Video Acceleration API support for Linux (using Raspberry Pi as reference hardware)
* Added RenderCapture implementation to Linux for Raspberry Pi for Ambilight addons
* Added support for OpenMAX pipeline to handle JPEG decode/resize/convert/encode to texture on Raspberry Pi
* Added support for hardware assisted video decoding of MJPEG, VP6, VP8 and Ogg Theora on Raspberry Pi
* Added support for Fast Forward and Rewind video up 4x to OpenMAX (OMXPlayer) on Linux for Raspberry Pi
* Added support multi-channel PCM audio output over HDMI to OpenMAX (OMXPlayer) on Linux for Raspberry Pi
* Added screenshot implementation to Linux for Raspberry Pi that includes the video layer
* Added hot-plug support for Linux input devices, such as Bluetooth remotes and keyboards
* Improved AMD/Intel x86-64 64-bit (AMD64 / IA-64t CPU architectures) support under Linux

=== iOS Specific ===
* Added support for native media control bar and play background music on iOS
* Added adaptions for developing XBMC on non-jailbroken iSO devices (for development only, not to release on App Store)

=== Mac OS X Specific ===
* Improved XBMC support for OS X 10.9 (Mavericks)
* Added support for copy and paste to and from clipboard with command key

=== Windows Specific ===
* Added support for Pixel Shader based HQ (High Quality) scalers for DXVA renderer on Windows
* Added hybrid shutdown option on Windows 8 (which in turn enables quick boot)
* Removed Windows XP support (as from now XBMC for Windows requires at least Vista or later)

== References ==
<references/>

== See also ==
{{Changelogs}}

[[Category:XBMC Manual]]
[[Category:Gotham|*]]
[[Category:Changelogs]]

Archive:Linux audio

2014-06-18T07:46:56Z

Fritsch: /* Intel GPU HD Audio */

{{mininav|[[Audio]]}}
<section begin="intro" />This page describes how to set up audio for Linux-based systems. Primarily, it covers how to setup XBMC when using either ALSA or PulseAudio.<section end="intro" />

=PulseAudio vs ALSA=

Linux has two different audio systems, these are '''[[w:PulseAudio|PulseAudio]]''' and '''[[w:Advanced Linux Sound Architecture|Advanced Linux Sound Architecture (ALSA)]]'''.

If you have a PC that is exclusively used for XBMC then using ALSA maybe the best solution.

If you have a PC runs many applications other than XBMC then using PulseAudio maybe the the best solution.
<br />

== PulseAudio FAQ ==
To help you decide which is best for you:
{{See|PulseAudio#FAQ}}

== Configuring PulseAudio ==
When using PulseAudio some configuration at the OS level maybe necessary to get audio from XBMC.

For how to do this
{{See|PulseAudio}}

= Hardware Vendor Specifics =

== AMD ==

For AMD GPU's there are two sets of drivers available, the AMD supplied binary fglrx drivers or the newer Radeon OSS drivers.

===fglrx Drivers===

The AMD fglrx drivers on Linux support TrueHD, LPCM 7.1 and DTS-HD starting with kernel 3.13.

The AMD developers responsible for the fglrx drivers have failed to provide any updates or improvements to the XvBA hardware acceleration API which is for example used in the infamous xvba-va-driver. We suggest you disable hw decoding support and choose multithreaded Software Decoding in the Video -> Acceleration settings.

===Radeon OSS Drivers===

As a consequence of the lack of XvBA updates, XBMC's developers got in contact with the AMD OSS developers to see what could be done to improve AMD graphics in Linux, the result was the Radeon OSS drivers which have been developed to use the open source VDPAU API.

The Radeon OSS driver are now more feature rich and better performing than the fglrx ever were, amongst other things they are capable of allowing HD audio (DTS-HD, TrueHD) to be bitstreamed.

For more detail see forum thread:

{{forum link2|[[forum:174854|Linux - Radeon OSS with vdpau (howto)]] Discussion and further information.}}<br />

== Intel GPU HD Audio ==
Ubuntu 14.04 and therefore Xbmcbuntu v13 support HD Audio with intel hardware (IVB, SNB, HSW) out of the box you don't have to do any modifications to your system configuration. If and only if you are running a very old distribution, e.g. Ubuntu 12.04 that is shipped with an old kernel {{see|Intel Linux Modifications for HD Audio}}, those changes will break and harm your audio on a recent distributions, don't change your config files.

Archive:Linux audio

2014-06-18T07:44:33Z

Fritsch: /* Intel GPU HD Audio */

{{mininav|[[Audio]]}}
<section begin="intro" />This page describes how to set up audio for Linux-based systems. Primarily, it covers how to setup XBMC when using either ALSA or PulseAudio.<section end="intro" />

=PulseAudio vs ALSA=

Linux has two different audio systems, these are '''[[w:PulseAudio|PulseAudio]]''' and '''[[w:Advanced Linux Sound Architecture|Advanced Linux Sound Architecture (ALSA)]]'''.

If you have a PC that is exclusively used for XBMC then using ALSA maybe the best solution.

If you have a PC runs many applications other than XBMC then using PulseAudio maybe the the best solution.
<br />

== PulseAudio FAQ ==
To help you decide which is best for you:
{{See|PulseAudio#FAQ}}

== Configuring PulseAudio ==
When using PulseAudio some configuration at the OS level maybe necessary to get audio from XBMC.

For how to do this
{{See|PulseAudio}}

= Hardware Vendor Specifics =

== AMD ==

For AMD GPU's there are two sets of drivers available, the AMD supplied binary fglrx drivers or the newer Radeon OSS drivers.

===fglrx Drivers===

The AMD fglrx drivers on Linux support TrueHD, LPCM 7.1 and DTS-HD starting with kernel 3.13.

The AMD developers responsible for the fglrx drivers have failed to provide any updates or improvements to the XvBA hardware acceleration API which is for example used in the infamous xvba-va-driver. We suggest you disable hw decoding support and choose multithreaded Software Decoding in the Video -> Acceleration settings.

===Radeon OSS Drivers===

As a consequence of the lack of XvBA updates, XBMC's developers got in contact with the AMD OSS developers to see what could be done to improve AMD graphics in Linux, the result was the Radeon OSS drivers which have been developed to use the open source VDPAU API.

The Radeon OSS driver are now more feature rich and better performing than the fglrx ever were, amongst other things they are capable of allowing HD audio (DTS-HD, TrueHD) to be bitstreamed.

For more detail see forum thread:

{{forum link2|[[forum:174854|Linux - Radeon OSS with vdpau (howto)]] Discussion and further information.}}<br />

== Intel GPU HD Audio ==
HD Audio on Intel SandyBridge & IvyBridge systems require a patch from Intel to be included within the kernel, Linux 3.7 and higher include this patch as standard.
On very old Linux Distributions (Ubuntu 12.04) you might need to alter your system configuration. This is not needed for Xbmcbuntu v13 nor is it needed for Ubuntu 14.04 LTS, don't touch those config files.

For more detail on the required Linux modifications for old distributions:

{{See|Intel Linux Modifications for HD Audio}}

Archive:Linux audio

2014-06-18T07:42:37Z

Fritsch: /* fglrx Drivers */

{{mininav|[[Audio]]}}
<section begin="intro" />This page describes how to set up audio for Linux-based systems. Primarily, it covers how to setup XBMC when using either ALSA or PulseAudio.<section end="intro" />

=PulseAudio vs ALSA=

Linux has two different audio systems, these are '''[[w:PulseAudio|PulseAudio]]''' and '''[[w:Advanced Linux Sound Architecture|Advanced Linux Sound Architecture (ALSA)]]'''.

If you have a PC that is exclusively used for XBMC then using ALSA maybe the best solution.

If you have a PC runs many applications other than XBMC then using PulseAudio maybe the the best solution.
<br />

== PulseAudio FAQ ==
To help you decide which is best for you:
{{See|PulseAudio#FAQ}}

== Configuring PulseAudio ==
When using PulseAudio some configuration at the OS level maybe necessary to get audio from XBMC.

For how to do this
{{See|PulseAudio}}

= Hardware Vendor Specifics =

== AMD ==

For AMD GPU's there are two sets of drivers available, the AMD supplied binary fglrx drivers or the newer Radeon OSS drivers.

===fglrx Drivers===

The AMD fglrx drivers on Linux support TrueHD, LPCM 7.1 and DTS-HD starting with kernel 3.13.

The AMD developers responsible for the fglrx drivers have failed to provide any updates or improvements to the XvBA hardware acceleration API which is for example used in the infamous xvba-va-driver. We suggest you disable hw decoding support and choose multithreaded Software Decoding in the Video -> Acceleration settings.

===Radeon OSS Drivers===

As a consequence of the lack of XvBA updates, XBMC's developers got in contact with the AMD OSS developers to see what could be done to improve AMD graphics in Linux, the result was the Radeon OSS drivers which have been developed to use the open source VDPAU API.

The Radeon OSS driver are now more feature rich and better performing than the fglrx ever were, amongst other things they are capable of allowing HD audio (DTS-HD, TrueHD) to be bitstreamed.

For more detail see forum thread:

{{forum link2|[[forum:174854|Linux - Radeon OSS with vdpau (howto)]] Discussion and further information.}}<br />

== Intel GPU HD Audio ==
HD Audio on Intel SandyBridge & IvyBridge systems require a patch from Intel to be included within the kernel, Linux 3.7 and higher include this patch as standard. In addition modification to system files maybe required in order to get the HDMI audio working.

For more detail on the required Linux modifications:

{{See|Intel Linux Modifications for HD Audio}}

Advancedsettings.xml

2014-06-14T22:50:04Z

Fritsch: Typo

{{TOC right}}{{mininav|[[Settings]]|page=advancedsettings.xml}}
{{bigger|{{note|'''The advancedsettings.xml file does not exist by default. You have to create it first!'''}} }}

<section begin="intro" />The [[advancedsettings.xml]] file, which does not exist by default, can be created by a user in their '''[[userdata folder]]'''. This file is used for advanced settings and options that do not have GUI controls inside of XBMC. Some settings are experimental or very rarely set, so they can only be used via the advancedsettings.xml file. The file is simply a plain text file and can be edited by various text editors, so long as the name is "advancedsettings.xml". These advanced settings can be used to tweak various things such as episode naming patterns, special network ports, special behaviors, and more.<section end="intro" />

The following page will describe the structure of the advancedsettings.xml file and the various individual settings.

{{note|
# All XML tags must be lowercase. The start and end of the advancedsettings.xml file must have the <advancedsettings> and </advancedsettings> tags.
# XBMC will only read the advancedsettings.xml file when it starts up. If you make changes while XBMC is running then you must restart XBMC.
# For some Windows versions, XBMC has two <code>\userdata\</code> folders. The correct one to put the advancedsettings.xml file in is not the one in Program Files, but in <code>%appdata%\XBMC\userdata\.</code>}}

== Layout ==

The layout of <code>advancedsettings.xml</code> is as follows:

<syntaxhighlight lang="xml" enclose="div">
<advancedsettings>
<setting>value</setting>
...
<setting>value</setting>
</advancedsettings>
</syntaxhighlight>

where "setting" gives the name of the setting, and "value" gives it's value.

A list of the available "setting" strings and their values is given below.

== How to include GUI settings ==
{{Note|In XBMC v13 "Gotham", using guisettings in advancedsettings.xml might not work anymore or might give unexpected results.}}

You can also define the settings normally defined in the GUI in advancedsettings.xml. Any GUI based settings defined in advancedsettings.xml will override the GUI values, and the settings will be removed completely from the GUI (ie only alterable by editing advancedsettings.xml).

The easiest way to include a GUI setting is to first make sure it is set in the GUI to the value that you want, and then to open the '''UserData\guisettings.xml''' file and find the XML entry that corresponds to that setting.

Then just add that entry to the advancedsettings.xml file.

For instance, to set the Font Character Set for the GUI (found in the appearance setting, in the Look and Feel section), you'd open up guisettings.xml and find:

<syntaxhighlight lang="xml" enclose="div">
<lookandfeel>
<charset>Hebrew (Windows)</charset>
</lookandfeel>
</syntaxhighlight>

Simply take that entry and place it in advancedsettings.xml. The GUI entry for the character set will then no longer appear, and XBMC will always use the Hebrew (Windows) character set.

= List of available settings =

== Troubleshooting settings ==

=== loglevel ===
{{Anchor|.3Cloglevel.3E}}
{{see also|debug log}}
<section begin="loglevel" />
{{xml setting
| tag name = loglevel
| tag attribute = hide
| tag attribute type = true_false
| tag attribute values =
{{option values
| value1= true | value1 description= Hides "enable debugging" guisetting.
| value2= false | value2 description= "enable debugging" guisetting will switch between min(loglevel, 0) and max(loglevel, 2) for off and on respectively. '''(Default)'''
}}
| tag attribute default values = true
| option type = list
| option values =
{{option values
| value1= -1 | value1 description= No logging, suppresses all log output
| value2= 0 | value2 description= Normal logging, only logging errors '''(Default)'''
| value3= 1 | value3 description= Debug logging ''(without showing text on screen)''
| value4= 2 | value4 description= Debug logging with freemem, fps and cpu usage shown on screen
| value5= 3 | value5 description= Debug logging with freemem, fps and cpu usage and full smb logging
}}
| default values = 0
| example values =
| platform = all
| XBMC version = 8-12
| description =
The logging level that XBMC will use to log errors and information. The "hide" attribute is optional.
| example =
Example:
<syntaxhighlight lang="xml" enclose="div">
<loglevel hide="false">1</loglevel>
</syntaxhighlight>

<br />

{{Note| If debugging is switched on in the GUI, loglevel will be set to 2 (''log to both file and on-screen information''); this will over-ride any <code>advancedsettings.xml</code> setting.}}<br />

{{Note| If debugging is switched on in the GUI when XBMC is shut down, then it will be automatically be re-enabled at level 2 when XBMC is re-started. This is true even if 'hide' is subsequently set to 'true' - in other words, if you enable it in the GUI and then hide the GUI toggle, it will stay on level 2 irrespective of what you subsequently set in <code>advancedsettings.xml</code>.}}<br />
}}
<section end="loglevel" />

=== jsonrpc ===
{{Anchor|.3Cjsonrpc.3E}}
To make it easier for developers using the [[JSON RPC]] API in their (third party) applications to debug during development the json output of XBMC can be prettified by setting '''compactoutput''' to '''false'''. Default json output mode is a compact print which does not contain any unnecessary whitespaces and therefore is difficult to read for humans.
Furthermore using the '''tcpport''' setting it is possible to change the default TCP port used by XBMC for JSON RPC (which is 9090) to any other valid port.

Example:
<syntaxhighlight lang="xml" enclose="div">
<jsonrpc>
<compactoutput>false</compactoutput>
<tcpport>9999</tcpport>
</jsonrpc>
</syntaxhighlight>

=== other - enableairtunesdebuglog ===
{{see|#enableairtunesdebuglog}}

== Audio/video playback settings ==

=== skiploopfilter ===
{{anchor|.3Cskiploopfilter.3E}}
The amount of the loop filter to skip on h264 decoding. This can help the performance of slower machines when decoding h264 content. Values, in decreasing CPU usage (and decreasing quality)
* -16 None
* 0 Skip only empty frames (default)
* 8 Skip non-reference frames (default on ATV)
* 16 Skip bi-dir frames
* 32 Skip all non-key frames
* 48 Skip all frames
Example:
<syntaxhighlight lang="xml" enclose="div">
<skiploopfilter>8</skiploopfilter>
</syntaxhighlight>

=== video ===
{{anchor|.3Cvideo.3E}}
{{see also|HOW-TO:Modify automatic watch and resume points|HOW-TO:Modify time seeking}}
<syntaxhighlight lang="xml" enclose="div">
<video>
<subsdelayrange>10</subsdelayrange> 
<audiodelayrange>10</audiodelayrange> 
<smallstepbackseconds>7</smallstepbackseconds> 
<usetimeseeking>true</usetimeseeking> 
<timeseekforward>30</timeseekforward> 
<timeseekbackward>-30</timeseekbackward> 
<timeseekforwardbig>600</timeseekforwardbig> 
<timeseekbackwardbig>-600</timeseekbackwardbig> 
<percentseekforward>2</percentseekforward> 
<percentseekbackward>-2</percentseekbackward> 
<percentseekforwardbig>10</percentseekforwardbig> 
<percentseekbackwardbig>-10</percentseekbackwardbig> 
<blackbarcolour>1</blackbarcolour> 
<fullscreenonmoviestart>true</fullscreenonmoviestart> 
<defaultplayer>dvdplayer</defaultplayer> 
<excludefromscan> 
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromscan>
<excludefromlisting> 
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
<playcountminimumpercent>90</playcountminimumpercent> 
<ignoresecondsatstart>180</ignoresecondsatstart> 
<ignorepercentatend>8</ignorepercentatend>


<vdpauscaling>true</vdpauscaling>


<enablehighqualityhwscalers>true</enablehighqualityhwscalers> 
<ppffmpegdeinterlacing>linblenddeint</ppffmpegdeinterlacing> 
<ppffmpegpostprocessing>ha:128:7,va,dr</ppffmpegpostprocessing> 
<allowmpeg4vdpau>true</allowmpeg4vdpau> 
<allowmpeg4vaapi>true</allowmpeg4vaapi> 
<autoscalemaxfps>30</autoscalemaxfps> 



<adjustrefreshrate>









<override>
<fps>23.976</fps> 
<refresh>60.0</refresh> 
</override>

<override>
<fpsmin>29.96</fpsmin> 
<fpsmax>30.01</fpsmax>
<refreshmin>59.0</refreshmin> 
<refreshmax>61.0</refreshmax>
</override>




<fallback>
<refresh>50.0</refresh> 
</fallback>


<fallback>
<refreshmin>49.0</refreshmin>
<refreshmax>51.0</refreshmax>
</fallback>




</adjustrefreshrate>

<checkdxvacompatibility>value</checkdxvacompatibility>


<useocclusionquery>-1</useocclusionquery> 
<fpsdetect>1</fpsdetect> 



<latency>


<delay>0</delay>




<refresh>
<min>23</min>
<max>24</max>
<delay>125</delay>
</refresh>


<refresh>
<rate>50</rate>
<delay>50</delay>
</refresh>

</latency>

<stereoscopicregex3d>[-. _]3d[-. _]</stereoscopicregex3d>
<stereoscopicregexsbs>[-. _]h?sbs[-. _]</stereoscopicregexsbs>
<stereoscopicregextab>[-. _]h?tab[-. _]</stereoscopicregextab>
<stagefright>

<useavccodec>-1</useavccodec>
<usevc1codec>-1</usevc1codec>
<usevpxcodec>-1</usevpxcodec>
<usemp4codec>-1</usemp4codec>
<usempeg2codec>-1</usempeg2codec>
<useswrenderer>false</useswrenderer>
</stagefright>
<disablehi10pmultithreading>false</disablehi10pmultithreading> 
</video>
</syntaxhighlight>
{{helix note|disablehi10pmultithreading will be renamed to disableswmultithreading in v14 Helix}}

=== audio ===
{{anchor|.3Caudio.3E}}
<syntaxhighlight lang="xml" enclose="div">
<audio>

<headroom>0</headroom>

<defaultplayer>paplayer</defaultplayer>

<excludefromscan>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromscan>

<excludefromlisting>
<regexp>[-\._ ](podcast)[-\._ ]</regexp>
</excludefromlisting>

<ac3downmixgain>12.0</ac3downmixgain>

<playcountminimumpercent>99</playcountminimumpercent>

<applydrc>true</applydrc>

<dvdplayerignoredtsinwav>false</dvdplayerignoredtsinwav>

<limiterhold>0.025</limiterhold>

<limiterrelease>0.1</limiterrelease>
</audio>
</syntaxhighlight>

For more information on the configuration of audio under Frodo see [[AudioEngine/HOW-TO: Configure audio]]

=== measurerefreshrate ===
{{anchor|.3Cmeasurerefreshrate.3E}}
When using "Sync playback to display" on Windows, the detected refreshrate might be wrong.
When enabling measurerefreshrate, the refreshrate is measured instead, which makes it more accurate.

<syntaxhighlight lang="xml" enclose="div">
<measurerefreshrate>true</measurerefreshrate>
</syntaxhighlight>

=== edl ===
{{anchor|.3Cedl.3E}}
{{main|EDL}}
Commercial break detection not as good you think it could be? Are some commercial breaks in a series of adverts not being skipped? Are some parts being skipped that are clearly not commercials? Does the end of the previous recording still show? The following advanced settings can be used to better identify full commercial break sequences, remove incorrectly flagged commercial breaks, and have playback start at the actual beginning of the recording.

<syntaxhighlight lang="xml" enclose="div">
<edl>

<mergeshortcommbreaks>false</mergeshortcommbreaks>

<maxcommbreaklength>250</maxcommbreaklength>

<mincommbreaklength>90</mincommbreaklength>

<maxcommbreakgap>120</maxcommbreakgap>

<commbreakautowait>0</commbreakautowait>

<commbreakautowind>0</commbreakautowind>
</edl>
</syntaxhighlight>

=== pvr ===
{{anchor|.3Cpvr.3E}}
<syntaxhighlight lang="xml" enclose="div">
<pvr>
<timecorrection>0</timecorrection> 
<infotoggleinterval>3000</infotoggleinterval> 
<minvideocachelevel>5</minvideocachelevel> 
<minaudiocachelevel>10</minaudiocachelevel> 
<cacheindvdplayer>true</cacheindvdplayer> 
<channeliconsautoscan>true</channeliconsautoscan> 
<autoscaniconsuserset>false</autoscaniconsuserset> 
<numericchannelswitchtimeout>1000</numericchannelswitchtimeout> 
</pvr>
</syntaxhighlight>

=== epg ===
{{anchor|.3Cpvr.3E}}
<syntaxhighlight lang="xml" enclose="div">
<epg>
<lingertime>1440</lingertime> 
<updatecheckinterval>300</updatecheckinterval> 
<lingercleanupintervaltime>900</cleanupinterval> 
<activetagcheckinterval>60</activetagcheckinterval> 
<retryinterruptedupdateinterval>30</retryinterruptedupdateinterval> 
<updateemptytagsinterval>60</updateemptytagsinterval> 
<displayupdatepopup>true</displayupdatepopup> 
<displayincrementalupdatepopup>false</displayincrementalupdatepopup> 
</epg>
</syntaxhighlight>

=== forcedswaptime ===
{{anchor|.3Cforcedswaptime.3E}}
Use to force a backbuffer->frontbuffer swap while vsync is enabled. Set to the time (in ms) to allow for the swap (e.g. <forcedswaptime>1</forcedswaptime> is typical).

Default: Off

== Video library settings ==

=== videoextensions ===
{{anchor|.3Cvideoextensions.3E}}<section begin="videoextensions" />
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Video windows.

Default extensions for VIDEOS:
<pre>
.m4v .3gp .nsv .ts .ty .strm .rm .rmvb .m3u .ifo .mov .qt .divx .xvid .bivx .vob .nrg .img
.iso .pva .wmv .asf .asx .ogm .m2v .avi .bin .dat .dvr-ms .mpg .mpeg .mp4 .mkv .avc .vp3
.svq3 .nuv .viv .dv .fli .flv .rar .001 .wpl .zip
</pre>
Examples:
<syntaxhighlight lang="xml" enclose="div">
<videoextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</videoextensions>
</syntaxhighlight>
<section end="videoextensions" />

=== discstubextensions ===
{{anchor|.3Cdiscstubextensions.3E}}
A list of additional file-extensions that will (<tt><add></tt>) or will not (<tt><remove></tt>) be treated as disc stubs.

Default extensions for DISC STUBS:
<pre>
.disc
</pre>

Examples:
<syntaxhighlight lang="xml" enclose="div">
<discstubextensions>
<add>.dvd|.blu</add>
<remove>.cd|.vhs</remove>
</discstubextensions>
</syntaxhighlight>

=== languagecodes ===
{{anchor|.3Clanguagecodes.3E}}
Translation table for subtitle and audio names. Contains entries of the form

<syntaxhighlight lang="xml" enclose="div">
<languagecodes>
<code>
<short>alt</short>
<long>Alternate</long>
</code>
</languagecodes>
</syntaxhighlight>

=== sorttokens ===
{{anchor|.3Csorttokens.3E}}
Allows you to specify additional tokens that will be ignored at the start of lines during sorting.
<syntaxhighlight lang="xml" enclose="div">
<sorttokens>
<token>the</token>
</sorttokens>
</syntaxhighlight>

=== moviestacking ===
{{anchor|.3Cmoviestacking.3E}}<section begin="moviestacking" />
This is used by the [[File Stacking]] algorithm to combine multi-part files and contains a list of "''[[Regular Expression (RegEx) Tutorial|Regular Expressions]]''"

As of XBMC v9.11, video stacking regular expressions '''must''' contain exactly four (4) capture expressions. Old ones and three capture expressions are dropped (see [[Log file|log]]). More information on how the algorithm works is available [[File Stacking#How does it work.3F|here]].

Default:
<syntaxhighlight lang="xml" enclose="div">
<moviestacking>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck]|d)[ _.-]*[0-9]+)(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ _.-]*(?:cd|dvd|p(?:ar)?t|dis[ck]|d)[ _.-]*[a-d])(.*?)(\.[^.]+)$</regexp>

<regexp>(.*?)([ ._-]*[a-d])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="append"</tt> or <tt>append="yes"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the end.

Example:
<syntaxhighlight lang="xml" enclose="div">
<moviestacking action="append">

<regexp>(.*?)([ ._-]*[0-9])(.*?)(\.[^.]+)$</regexp>
</moviestacking>
</syntaxhighlight>

If the argument <tt>action="prepend"</tt> is supplied, the default moviestacking regular expressions will remain intact and the user specified ones will be added to the beginning.

Example:
<syntaxhighlight lang="xml" enclose="div">
<moviestacking action="prepend">
<regexp>(Title)(Volume)(Ignore)(Extension)</regexp>
</moviestacking>
</syntaxhighlight>

If no argument is supplied, or the argument <tt>append="no"</tt> is supplied, the default moviestacking regular expressions are overwritten by the user specified ones.
<section end="moviestacking" />

=== cleandatetime ===
{{anchor|.3Ccleandatetime.3E}}
Matches a year number in a string using a ''[[Regular Expression (RegEx) Tutorial|Regular Expression]]''

Default expression:
<syntaxhighlight lang="xml" enclose="div">
<video>
<cleandatetime>(.+[^ _\,\.\[\]\-])[ _\.\[\]\-]+(19[0-9][0-9]|20[0-1][0-9])([ _\,\.\[\]\-][^0-9]|$)</cleandatetime>
</video>
</syntaxhighlight>
:* The string found before will be used as basis string getting cleaned by the cleanstrings expressions.
:* By default date formats like MM:YY are ignored.

=== cleanstrings ===
{{anchor|.3Ccleanstrings.3E}}
Clean unwanted characters from filenames or folders by using a list of ''[[Regular Expression (RegEx) Tutorial|Regular Expressions]]''. Please note that everything right of the match (at the end of the file name) is removed, so if you would have a file named ''Super movie.mp4'' and would add <tt><regexp> </regexp></tt> (only a space), the only thing that would be left is ''Super'', which is probably not what you want.

Default expressions:
<syntaxhighlight lang="xml" enclose="div">
<video>
<cleanstrings>
<regexp>[ _\,\.\[\]\-](ac3|dts|custom|dc|divx|divx5|dsr|dsrip|dutch|dvd|dvdrip|dvdscr|dvdscreener|screener|dvdivx|cam|fragment|fs|hdtv|hdrip|hdtvrip|internal|limited|multisubs|ntsc|ogg|ogm|pal|pdtv|proper|repack|rerip|retail|cd[1-9]|r3|r5|bd5|se|svcd|swedish|german|read.nfo|nfofix|unrated|ws|telesync|ts|telecine|tc|brrip|bdrip|480p|480i|576p|576i|720p|720i|1080p|1080i|hrhd|hrhdtv|hddvd|bluray|x264|h264|xvid|xvidvd|xxx|www.www|\[.*\])([ _\,\.\[\]\-]|$)</regexp>
<regexp>(\[.*\])</regexp>
</cleanstrings>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== tvshowmatching ===
{{anchor|.3Ctvshowmatching.3E}}
Matches the season and episode numbers in file paths by using a list of ''[[Regular Expression (RegEx) Tutorial|Regular Expressions]]''

Defaults:
<syntaxhighlight lang="xml" enclose="div">
<tvshowmatching>
<regexp>[Ss]([0-9]+)[][ ._-]*[Ee]([0-9]+)([^\\/]*)$</regexp> 
<regexp>[\._ -]()[Ee][Pp]_?([0-9]+)([^\\/]*)$</regexp> 
<regexp>([0-9]{4})[\.-]([0-9]{2})[\.-]([0-9]{2})</regexp> 
<regexp>([0-9]{2})[\.-]([0-9]{2})[\.-]([0-9]{4})</regexp> 
<regexp>[\\/\._ \[\(-]([0-9]+)x([0-9]+)([^\\/]*)$</regexp> 
<regexp>[\\/\._ -]([0-9]+)([0-9][0-9])([\._ -][^\\/]*)$</regexp> 
<regexp>[\/._ -]p(?:ar)?t[_. -]()([ivx]+)([._ -][^\/]*)$</regexp> 
</tvshowmatching>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)
:* Expressions are converted to lower case before being evaluated. ''(XBMC v13.0 alpha4 and earlier only)''
:* Paths are converted to lower case before matching.
:* Examples of matching regexps for certain filenames can be found on the [[TV Shows (Video Library)|TV shows]] page.

:* For multi-episode matching to work, there needs to be a third set of parentheses '()' at the end, this part is fed back into the regexp engine.

:* A [http://forum.xbmc.org/showthread.php?t=51614 forum thread] has a discussion of pre-made regex lists to match common names. These drastically improve XMBC's ability to match TV show names, at the risk of some additional false positives.

==== Filenames without Season ====
There are two methods to add episodes without a season in their file path. Both ways will force the season to '1', so that you can use
the 'Use Absolute Ordering (Single Season)' setting from the TheTvDb.com scraper.

; Simple Method ''(XBMC v9.11 onwards)''
: Use only one pair of parentheses
<syntaxhighlight lang="xml" enclose="div"><regexp>[/\._ \-]([0-9]+)</regexp></syntaxhighlight>
; Advanced Method ''(XBMC v10.05 onwards)''
: Supports multi-episode files without season
: Use an empty pair of parentheses for the season
<syntaxhighlight lang="xml" enclose="div"><regexp>[/\._ \-]()([0-9]+)(-[0-9]+)?</regexp></syntaxhighlight>

=== tvmultipartmatching ===
{{anchor|.3Ctvmultipartmatching.3E}}
Matches a multipart episode number based on a previously identified episode file, using a list of ''[[Regular Expression (RegEx) Tutorial|Regular Expressions]]''

Defaults:
<syntaxhighlight lang="xml" enclose="div">
<tvmultipartmatching>^[-_EeXx]+([0-9]+)</tvmultipartmatching>
</syntaxhighlight>
:* Text matching is compared case-insensitive.

=== excludefromscan ===
{{anchor|.3Cexcludefromscan.3E}}
Matches filenames or folders which should be excluded from a library scan (except tvshows) using a list of ''[[Regular Expression (RegEx) Tutorial|Regular Expressions]]''. This can be for both Video or Audio sections of <tt>advancedsettings.xml</tt>.

Defaults:
<syntaxhighlight lang="xml" enclose="div">
<video>
<excludefromscan>
<regexp>-trailer</regexp>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludefromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== excludefromlisting ===
{{anchor|.3Cexcludefromlisting.3E}}
<syntaxhighlight lang="xml" enclose="div">
<video>
<excludefromlisting> 
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</excludefromlisting>
</video>
</syntaxhighlight>

=== excludetvshowsfromscan ===
{{anchor|.3Cexcludetvshowsfromscan.3E}}
Matches filenames or folders which should be excluded from a tvshow library scan using a list of ''[[Regular Expression (RegEx) Tutorial|Regular Expressions]]''

Defaults:
<syntaxhighlight lang="xml" enclose="div">
<video>
<excludetvshowsfromscan>
<regexp>[!-._ \\/]sample[-._ \\/]</regexp>
</excludetvshowsfromscan>
</video>
</syntaxhighlight>

:* Arguments <tt>action="append"</tt> or <tt>action="prepend"</tt> will insert user specified expressions after, or before, the defaults above. (Further details in [[Advancedsettings.xml#.3Cmoviestacking.3E|moviestacking]] section)

=== trailermatching ===
{{anchor|.3Ctrailermatching.3E}}
Contains "''[[Regular Expression (RegEx) Tutorial|Regular Expression]]''" syntax (commonly referred to as "''[[Regular Expression (RegEx) Tutorial|RegEx]]''" or "''[[Regular Expression (RegEx) Tutorial|RegExp]]''") to match the locally stored trailers to movies in the library.

<syntaxhighlight lang="xml" enclose="div">
<trailermatching>

<regexp>(.*?)(_Trailer)(\.[^.]+)$</regexp>
</trailermatching>
</syntaxhighlight>

=== videolibrary ===
{{anchor|.3Cvideolibrary.3E}}
Options specific to the Video Library

<syntaxhighlight lang="xml" enclose="div">
<videolibrary>
<allitemsonbottom>false</allitemsonbottom> 
<backgroundupdate>false</backgroundupdate> 

<cleanonupdate>false</cleanonupdate> 
<hideallitems>false</hideallitems> 
<hideemptyseries>false</hideemptyseries> 
<recentlyaddeditems>35</recentlyaddeditems> 
<itemseparator> / </itemseparator> 
<exportautothumbs>false</exportautothumbs> 
<importwatchedstate>false</importwatchedstate> 
<importresumepoint>false</importresumepoint> 
<mymovies> 
<categoriestogenres>false</categoriestogenres> 
</mymovies>
<dateadded>1</dateadded> 
</videolibrary>
</syntaxhighlight>

=== videoscanner ===
{{anchor|.3Cvideoscanner.3E}}
Options specific to the Video scanner
<syntaxhighlight lang="xml" enclose="div">
<videoscanner>
<ignoreerrors>true</ignoreerrors> 
</videoscanner>
</syntaxhighlight>

=== myth ===
{{anchor|.3Cmyth.3E}}
Not seeing all the recordings you expected in the Movies folder? If so, it's very likely that the electronic program guide (EPG) used by MythTV doesn't accurately distinguish between TV Shows and Movies all the time. The following setting allows the length of the recording to also be used to determine if a recording is a Movie.

<syntaxhighlight lang="xml" enclose="div">
<myth>

<movielength>0</movielength>
</myth>
</syntaxhighlight>

== Library artwork ==

=== imageres ===
{{anchor|.3Cimageres.3E}}
This tag is new for v12 (Frodo), replacing <thumbsize>.

<section begin="imageres description" />Specify the maximal resolution that art should be resized to in pixels. The width is automatically calculated as being 16/9*height. The image will be resized to fit within this size. e.g. an image that is 2000x500 will be cached at size 1280x320. An image that is 500x800 will be cached at size 450x720 using the default value of 720.<section end="imageres description" />

<syntaxhighlight lang="xml" enclose="div">
<imageres>720</imageres>
</syntaxhighlight>

=== fanartres ===
{{anchor|.3Cfanartres.3E}}
This tag is new for v12 (Frodo), replacing <fanartheight>.

<section begin="fanartres description" />Specify the resolution that cached fanart should be resized to in pixels. The width is automatically calculated as being 16/9*height. Only images that are exactly 16x9 and equal to or greater than this resolution will be cached at this size - all other images will be cached using <imageres>. The default value is 1080.<section end="fanartres description" />

<syntaxhighlight lang="xml" enclose="div">
<fanartres>1080</fanartres>
</syntaxhighlight>

=== fanart ===
{{anchor|.3Cfanart.3E}}
As of v12 (Frodo), this tag is only used for music and not video.

A list of additional files to try when searching for fanart images. (The defaults are fanart.jpg and fanart.png which can be removed.)

Example:
<syntaxhighlight lang="xml" enclose="div">
<fanart>
<remove>fanart.jpg</remove>
<add>backdrop.jpg</add>
</fanart>
</syntaxhighlight>

=== musicthumbs ===
{{anchor|.3Cmusicthumbs.3E}}
A list of additional files to try when searching for music thumbnail images. (The default is folder.jpg which can be removed.)

Example:
<syntaxhighlight lang="xml" enclose="div">
<musicthumbs>
<remove>folder.jpg</remove>
<add>thumb.jpg|cover.jpg</add>
</musicthumbs>
</syntaxhighlight>

=== useddsfanart ===
{{anchor|.3Cuseddsfanart.3E}}
This settings allows XBMC to use your GPU rendering fanart and some other images. This will make loading images considerably faster, especially on systems with slower processors (e.g. atom based systems). Do not use this option on ARM based systems (Apple TV2/iOS/RPi/many Android systems) as it is likely to degrade performance because DDS images are not supported.

<syntaxhighlight lang="xml" enclose="div">
<useddsfanart>true</useddsfanart>
</syntaxhighlight>

== Video and music library settings ==

=== playlistasfolders ===
{{anchor|.3Cplaylistasfolders.3E}}
In the recent releases, playlists are treated as folders. Selecting a playlist no longer plays it, but opens it, as if it were a folder.

Set to false to revert to the previous behaviour. When you select a playlist, its content is added to the list of elements to be played.

:{{note|This setting will not affect smart playlists, they will always show as folders.}}

;Example
<syntaxhighlight lang="xml" enclose="div">
<playlistasfolders>true</playlistasfolders>
</syntaxhighlight>

=== playlistretries ===
{{anchor|.3Cplaylistretries.3E}}
The number of retries attempted if a source is offline. With this control you can alter the number of consecutive failed items before a playlist fails.

Default:
<syntaxhighlight lang="xml" enclose="div">
<playlistretries>100</playlistretries>
</syntaxhighlight>

=== playlisttimeout ===
{{anchor|.3Cplaylisttimeout.3E}}
The timeout, in seconds, before item failure.

Default:
<syntaxhighlight lang="xml" enclose="div">
<playlisttimeout>20</playlisttimeout>
</syntaxhighlight>

=== musicdatabase/videodatabase ===
{{anchor|.3Cmusicdatabase.3E/.3Cvideodatabase.3E}}
{{see also|MySQL}}
<section begin="videodatabase" />
Allows advanced customization of the default database settings for both music and video.

:{{note| '''It is HIGHLY recommended that you not attempt to place an sqlite3 database outside of XBMC's path. sqlite3 contains no filesystem abstraction, so this will plain break on any non-local (as far as XBMC is concerned) paths. Use this for mysql only.'''}}
'''type'''

Can be either "sqlite3" or "mysql" (default: sqlite3)

'''host'''

sqlite3: defines the relative path to the database file (eg. /usr/local/xbmc/databases).

mysql: defines the host of the mysql socket (eg. localhost, 192.168.0.1, etc)

'''port'''

sqlite3: silently ignored

mysql: defines the port of the mysql socket (default: 3306)

'''name'''
:''Not needed by default, and some users report issues when defining the this tag. When not used "MyVideos"+DB number will be used.
sqlite3: defines the name of the database file to read from, excluding the ".db" extension.

mysql: defines the name of the database to use

'''user'''

sqlite3: silently ignored

mysql: defines the user with privileged access to the database

'''pass'''

sqlite3: silently ignored

mysql: defines the password for the user with privileged access to the database

'''Examples:'''

1) Configure a database for MySQL.
:{{note| ''The videodatabase and musicdatabase tags are interchangeable here.''}}
<syntaxhighlight lang="xml" enclose="div">
<videodatabase>
<type>mysql</type>
<host>192.168.0.10</host>
<name>xbmc_video</name>
<user>xbmc</user>
<pass>xbmc</pass>
</videodatabase>
</syntaxhighlight>

2) Configure a database for an sqlite database.
:{{note|''The videodatabase and musicdatabase tags are interchangeable here.''}}
<syntaxhighlight lang="xml" enclose="div">
<musicdatabase>
<type>sqlite3</type>
<host>/usr/local/share/xbmc/databases</host>
<name>xbmc_music</name>
</musicdatabase>
</syntaxhighlight>

{{note| ''If you use MySQL for the music database, but are finding that it slows down your music library significantly, execute the following query to create an index on the song table. This will significantly speed up queries using the songview views looking up by artist:'' }}

<syntaxhighlight lang="sql" enclose="div">
CREATE INDEX ixSongArtist
ON song(idArtist, idAlbum)
</syntaxhighlight>
<section end="videodatabase" />

=== externalplayer ===
{{anchor|.3Cexternalplayer.3E}}
{{see|External players}}

== Music settings ==

=== musicextensions ===
{{anchor|.3Cmusicextensions.3E}}
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Music windows.

Default extensions for MUSIC:
<pre>
.nsv .m4a .flac .aac .strm .pls .rm .mpa .wav .wma .ogg .mp3 .mp2 .m3u .mod .amf .669 .dmf .dsm .far .gdm
.imf .it .m15 .med .okt .s3m .stm .sfx .ult .uni .xm .sid .ac3 .dts .cue .aif .aiff .wpl .ape .mac .mpc
.mp+ .mpp .shn .zip .rar .wv .nsf .spc .gym .adplug .adx .dsp .adp .ymf .ast .afc .hps .xsp
</pre>

Examples:
<syntaxhighlight lang="xml" enclose="div">
<musicextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</musicextensions>
</syntaxhighlight>

=== cddbaddress ===
{{anchor|.3Ccddbaddress.3E}}
The address of the online CDDb database. You may set this to another freedb mirror if there is a more suitable one.

Default:
<syntaxhighlight lang="XML" enclose="div>
<cddbaddress>freedb.freedb.org</cddbaddress>
</syntaxhighlight>

=== songinfoduration ===
{{anchor|.3Csonginfoduration.3E}}
This controls how long the song information will remain onscreen when the song changes during visualisations. The valid range is "1" to "Indefinite (0)", in seconds. This does not include the duration of any transition effects.

Default:
<syntaxhighlight lang="xml" enclose="div">
<songinfoduration>10</songinfoduration>
</syntaxhighlight>

=== musicfilenamefilters ===
{{anchor|.3Cmusicfilenamefilters.3E}}
Contains filters to match music information (artist, title etc.) from a tag-less music filename. The first <filter> to match completely is used. Matched items include:

<pre>
%A - Artist
%T - Title
%B - Album
%N - Track number
%S - Part of set (disk number)
%D - Duration
%G - Genre
%Y - Year
%R - Rating
</pre>

Example:
<syntaxhighlight lang="xml" enclose="div">
<musicfilenamefilters>
<filter>%A - %T</filter>
</musicfilenamefilters>
</syntaxhighlight>

=== musiclibrary ===
{{anchor|.3Cmusiclibrary.3E}}
Options specific to the Music Library

<syntaxhighlight lang="xml" enclose="div">
<musiclibrary>
<hideallitems>true</hideallitems> 
<allitemsonbottom>true</allitemsonbottom> 
<backgroundupdate>true</backgroundupdate> 
<recentlyaddeditems>35</recentlyaddeditems> 
<albumssortbyartistthenyear>true</albumssortbyartistthenyear> 
<albumformat>%B - %Y</albumformat> 
<albumformatright>%A</albumformatright> 
<prioritiseapetags>true</prioritiseapetags> 
<itemseparator> / </itemseparator> 
</musiclibrary>
</syntaxhighlight>

=== karaoke ===
{{anchor|.3Ckaraoke.3E}}
{{Main|Karaoke}}<section begin="karaoke" />
<syntaxhighlight lang="xml" enclose="div">
<karaoke>

<syncdelaycdg>0.0</syncdelaycdg>

<syncdelaylrc>0.0</syncdelaylrc>

<alwaysreplacegenre>false</alwaysreplacegenre>

<storedelay>true</storedelay>

<autoassignstartfrom>1</autoassignstartfrom>

<nocdgbackground>true</nocdgbackground>

<defaultbackground type="video" path="special://masterprofile/karaokevideobg.avi"/>

<nextsongpopuptime>0.0</nextsongpopuptime>
</karaoke>
</syntaxhighlight>
<section end="karaoke" />

== Photos settings ==

=== pictureextensions ===
{{anchor|.3Cpictureextensions.3E}}
A list of additional file-extensions to allow ('''add''') or exclude ('''remove''') in the My Pictures window.

Default extensions for PICTURES:
<pre>
.png .jpg .jpeg .bmp .gif .ico .tif .tiff .tga .pcx .cbz .zip .cbr .rar .m3u
</pre>

Examples:
<syntaxhighlight lang="xml" enclose="div">
<pictureextensions>
<add>.ex1|.ex2</add>
<remove>.ex3|.ex4</remove>
</pictureextensions>
</syntaxhighlight>

=== pictureexcludes ===
{{anchor|.3Cpictureexcludes.3E}}
Matches filenames or folders which should be excluded from being displayed in My Pictures using a list of ''[[Regular Expression (RegEx) Tutorial|Regular Expressions]]''

<syntaxhighlight lang="xml" enclose="div">
<pictureexcludes> 
<regexp>small</regexp>
<regexp>[-\._ ](sample|trailer)[-\._ ]</regexp>
</pictureexcludes>
</syntaxhighlight>

=== slideshow ===
{{anchor|.3Cslideshow.3E}}
<syntaxhighlight lang="xml" enclose="div">
<slideshow>

<panamount>2.5</panamount>

<zoomamount>5.0</zoomamount>



<blackbarcompensation>20</blackbarcompensation>
</slideshow>
</syntaxhighlight>

== Network settings ==

=== samba ===
{{anchor|.3Csamba.3E}}
<syntaxhighlight lang="xml" enclose="div">
<samba>
<doscodepage></doscodepage> 
<clienttimeout>10</clienttimeout> 
<statfiles>true</statfiles> 
</samba>
</syntaxhighlight>

=== hosts ===
{{anchor|.3Cfhosts.3E}}
Static dns entries which take precedence over your dns server.
<syntaxhighlight lang="xml" enclose="div">
<hosts>
<entry name="HOSTNAME">IPADDRESS</entry>
</hosts>
</syntaxhighlight>

=== network ===
{{anchor|.3Cnetwork.3E}}
{{see also|HOW-TO:Modify the cache}}
<syntaxhighlight lang="xml" enclose="div">
<network>
<curlclienttimeout>10</curlclienttimeout> 
<curllowspeedtime>5</curllowspeedtime> 
<httpproxyusername></httpproxyusername> 
<httpproxypassword></httpproxypassword> 
<cachemembuffersize>20971520</cachemembuffersize> 
<buffermode>0</buffermode> 
<readbufferfactor>1.0</readbufferfactor> 
</network>
</syntaxhighlight>

=== tuxbox ===
{{anchor|.3Ctuxbox.3E}}
<syntaxhighlight lang="xml" enclose="div">
<tuxbox>

<audiochannelselection>false</audiochannelselection>

<submenuselection>false</submenuselection>

<defaultrootmenu>0</defaultrootmenu>

<defaultsubmenu>4</defaultsubmenu>

<pictureicon>true</pictureicon>

<epgrequesttime>10</epgrequesttime>

<zapwaittime>0</zapwaittime>
</tuxbox>
</syntaxhighlight>

=== enableairtunesdebuglog ===
{{anchor|.3Cenableairtunesdebuglog.3E}}<section begin="enableairtunesdebuglog" />
This enables the debug output of libshairport which is used for the AirTunes feature. Defaults to off - because its spamming badly.

Example:
<syntaxhighlight lang="xml" enclose="div">
<enableairtunesdebuglog>1</enableairtunesdebuglog>)
</syntaxhighlight>
<section end="enableairtunesdebuglog" />

=== airtunesport ===
{{anchor|.3Cairtunesport.3E}}<section begin="airtunesport" />
This overwrites the defalt listening port of the AirTunes server (announced via zeroconf).
<section end="airtunesport" />

=== airplayport ===
{{anchor|.3Cairplayport.3E}}<section begin="airplayport" />
This overwrites the default listening port of the AirPlay server (announced via zeroconf).
<section end="airplayport" />

== File system settings ==

=== packagefoldersize ===
<section begin="packagefoldersize" />
{{anchor|.3Cpackagefoldersize.3E}}
{{xml setting
| tag name = packagefoldersize
| option type = numerical
| option values =
| default values = 200
| platform = all
| XBMC version = 12
| description = The amount (in megabytes) of add-on zip packages saved from previous add-on installs. These packages are mainly used for the [[add-on]] rollback feature. Increasing the size should increase the amount of past versions saved.
| example = Example: <syntaxhighlight lang="xml" enclose="div"><packagefoldersize>200</packagefoldersize> </syntaxhighlight>
}}
<section end="packagefoldersize" />
=== detectasudf ===
{{anchor|.3Cdetectasudf.3E}}
Set to true if you wish to detect joint ISO9660/UDF disks as UDF.

Default: False

=== pathsubstitution ===
{{anchor|.3Cpathsubstitution.3E}}
'''[[Path substitution]]s''' are for use for redirecting file paths. These are processed in order, and are useful for substituting an absolute path on a PC with a path suitable for XBMC to handle.

Default: No path substitutions defined.

Example:
<syntaxhighlight lang="xml" enclose="div">
<pathsubstitution>
<substitute>
<from>G:\dvds\</from>
<to>smb://somecomputer/g-share/dvds/</to> 
</substitute>
</pathsubstitution>
</syntaxhighlight>

== Remote control settings ==

=== remotedelay ===
{{anchor|.3Cremotedelay.3E}}
The repeat delay for a LIRC remote control. A delay value between 1 and 20 before a remote button starts repeating on a long keypress (i.e. continuously sending button pushes while it's held down).

Default: 3
<syntaxhighlight lang="xml" enclose="div">
<remotedelay>10</remotedelay>
</syntaxhighlight>

=== remoterepeat ===
{{anchor|.3Cremoterepeat.3E}}
This used to adjust the amount of time in milliseconds between repeated keystrokes. Used to prevent key-bounce, in other words prevents xbmc (lirc?) seeing one key press as multiple key presses with certain remotes.

<syntaxhighlight lang="xml" enclose="div">
<remoterepeat>800</remoterepeat>
</syntaxhighlight>

=== controllerdeadzone ===
{{anchor|.3Ccontrollerdeadzone.3E}}
The controller deadzone is the region of movement around the center which is not recognized by the device. Because joysticks can have noise (report motion when still) and bias (report an offset when centered), spurious events can be reported even though the controller isn't being touched. If you notice these kinds of events, you most likely need to increase your controller's deadzone (both axes recommended). The values range from 0.0 (no deadzone, XBMC will see all input your controller is capable of registering) to 1.0 (XBMC will ignore all input inside of the device's physical limits).

<syntaxhighlight lang="xml" enclose="div">
<controllerdeadzone>0.2</controllerdeadzone>
</syntaxhighlight>

=== enablemultimediakeys ===
{{anchor|.3Cenablemultimediakeys.3E}}
This setting only has any effect on Windows versions of XBMC, and only applies to builds from 28th May 2011 onwards.
In Windows the multimedia keys generate a WM_APPCOMMAND message in addition the keypress. XBMC processes both keypresses and the WM_APPCOMMAND messages, and the end result would be that the command is executed twice. To avoid this, by default multimedia keypresses are disabled. Although it should rarely be necessary, the enablemultimediakeys setting allows you to enable the multimedia keys.

Example:
<syntaxhighlight lang="xml" enclose="div">
<enablemultimediakeys>true</enablemultimediakeys>
</syntaxhighlight>

== Other interface settings ==

=== window ===
{{anchor|.3Cwindow.3E}}
This allows you to manually set the default size of XBMC's windowed mode. If you resize the window, it will return to the set size when restarting.

WIDTH and HEIGHT are the values for each dimension, in pixels.

<syntaxhighlight lang="xml" enclose="div">
<window><width>WIDTH</width><height>HEIGHT</height></window>
</syntaxhighlight>

=== allowd3d9ex ===
{{anchor|.3Callowd3d9ex.3E}}
Applies only to Windows Vista and up. Values: true/false. Allows xbmc to use Direct3D 9Ex, which is a bit more stable and robust than Direct3D 9.

Default:
<syntaxhighlight lang="xml" enclose="div">
<allowd3d9ex>true</allowd3d9ex>
</syntaxhighlight>

=== restrictcapsmask ===
{{anchor|.3Crestrictcapsmask.3E}}
Windows only. A bitmask to prevent xbmc from using detected texture capabilities of the GPU. This helps work around buggy hardware/drivers.

1: prevent the use of compressed textures (DXT1, DXT3, DXT5)
2: prevent the use of non-power-of-two dimensions for textures
4: prevent the use of compressed textures with non-power-of-two dimensions.

<syntaxhighlight lang="xml" enclose="div">
<restrictcapsmask>0</restrictcapsmask>
</syntaxhighlight>

=== forced3d9ex ===
{{anchor|.3Cforced3d9ex.3E}}
Windows only: XBMC attempts to detect drivers released for a version earlier than Vista, to avoid using advanced features which are often not emulated correctly. The detection may be incorrect and this setting allows forcing the using of D3D9Ex.

<syntaxhighlight lang="xml" enclose="div">
<forced3d9ex>false</forced3d9ex>
</syntaxhighlight>

=== algorithmdirtyregions ===
{{anchor|.3Calgorithmdirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="algorithmdirtyregions" /> {{note|Some GPU/hardware configurations will have some minor issues (such as a visual "flicker"). For those situations try mode 2 or use the default (mode 3, which requires no advancedsetting). Almost all ARM-based devices (such as [[Android]]) willl likely have flickering issues.}}

Enable dirty-region processing. Dirty regions are any parts of the screen that have changed since the last frame. By not re-rendering what hasn't changed the GUI can be sped up. Because all GPUs work differently, only Mode 3, combined with nofliptimeout=0, is guaranteed to work for everyone without flickering issues. This mode will reduce CPU/GPU usage, but will not increase GUI speed.

{| class="prettytable"
! value !! result !! description
|-
! 0
| Off
| The entire viewport is always rendered.
|-
! 1
|Union
|All dirty regions are grouped into the smallest possible rectangle. This is typically the fastest mode for slower GPUs due to only making one pass.
|-
! 2
| {{nowrap|Cost reduction}}
| Each dirty region is presented separately, in as many passes as there are regions.
|-
! 3
| {{nowrap|Whole Screen}}
| The entire screen is rendered if there are any dirty regions. This, combined with nofliptimeout is a safe default for drivers that clear buffer contents (manifests as blinking or vibrating images). '''Default'''
|}<section end="algorithmdirtyregions" />

Example:
<syntaxhighlight lang="xml" enclose="div">
<gui>
<algorithmdirtyregions>1</algorithmdirtyregions>
</gui>
</syntaxhighlight>

=== nofliptimeout ===
{{anchor|.3Cnofliptimeout.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="nofliptimeout" />Specifies the timeout in milliseconds after which XBMC will not flip the graphics buffers anymore when nothing has been rendered, this lowers both CPU and GPU usage. Sometimes adjusting this value can help prevent flickering.

* -1: disabled
* 0 or higher: timeout in milliseconds '''(0 is default)'''
<section end="nofliptimeout" />
Example:
<syntaxhighlight lang="xml" enclose="div">
<gui>
<nofliptimeout>1000</nofliptimeout>
</gui>
</syntaxhighlight>

=== visualizedirtyregions ===
{{anchor|.3Cvisualizedirtyregions.3E}}
{{see also|HOW-TO:Modify dirty regions}}
<section begin="visualizedirtyregions" />Enable dirty-region visualization. Paints a rectangle over marked controls.

* true: on
* false: off '''(Default)'''

{{note|This is only a development mode and isn't of use to normal users.}}
<section end="visualizedirtyregions" />
Example:
<syntaxhighlight lang="xml" enclose="div">
<gui>
<visualizedirtyregions>true</visualizedirtyregions>
</gui>
</syntaxhighlight>

=== showexitbutton ===
{{anchor|.3Cshowexitbutton.3E}}
Setting to hide the exit button, useful for people running appliance based setup's where exit would only confuse/complicate the user. Modifiable via the advancedsettings.xml by setting showexitbutton to false, default is true (show)

Example:
<syntaxhighlight lang="xml" enclose="div">
<showexitbutton>true</showexitbutton>
</syntaxhighlight>

=== fullscreen ===
{{anchor|.3Cfullscreen.3E}}
Starts XBMC in full screen (check resolutions!).

<syntaxhighlight lang="xml" enclose="div">
<fullscreen>false</fullscreen>
</syntaxhighlight>

=== splash ===
{{anchor|.3Csplash.3E}}
Set to false if you wish to disable the startup splash image. Defaults to true.

<syntaxhighlight lang="xml" enclose="div">
<splash>true</splash>
</syntaxhighlight>

=== cputempcommand ===
{{anchor|.3Ccputempcommand.3E}}
Provide a shell command XBMC will use to get CPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia and Raspberry Pi</u>
<syntaxhighlight lang="xml" enclose="div">
<cputempcommand>sed -e 's/$[0-9]*$[0-9]\{3\}.*/\1 C/' /sys/class/thermal/thermal_zone0/temp</cputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang="xml" enclose="div">
<cputempcommand>echo "$(sensors -u | tail -n64 | grep temp1_input | awk '{print $2 }' |awk '{printf("%d\n",$1 + 0.5);}') C"</cputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang="xml" enclose="div">
<cputempcommand>sensors|sed -ne "s/temp1: \+[-+]$[0-9]\+$.*/\1 C/p"</cputempcommand>
</syntaxhighlight>

=== gputempcommand ===
{{anchor|.3Cgputempcommand.3E}}
Provide a shell command XBMC will use to get GPU temperature. It should print out only "[temp as integer] [scale as one of "CcFf"]".<br />
;<u>For Nvidia</u>
<syntaxhighlight lang="xml" enclose="div">
<gputempcommand>echo "$(nvidia-settings -tq gpuCoreTemp) C"</gputempcommand>
</syntaxhighlight>
or
<syntaxhighlight lang="xml" enclose="div">
<gputempcommand>echo "$(nvidia-smi -q -d TEMPERATURE | grep Gpu | cut -c35-36) C"</gputempcommand>
</syntaxhighlight>
;<u>For ATI/AMD</u>
<syntaxhighlight lang="xml" enclose="div">
<gputempcommand>/usr/bin/aticonfig --od-gettemperature | grep Temperature | cut -f 2 -d "-" | cut -f 1 -d "." | sed -e "s, ,," | sed 's/$/ C/'</gputempcommand>
</syntaxhighlight>

;<u>For Raspberry Pi</u>
<syntaxhighlight lang="xml" enclose="div">
<gputempcommand>/opt/vc/bin/vcgencmd measure_temp | sed -e "s/temp=//" -e "s/\..*'/ /"</gputempcommand>
</syntaxhighlight>

=== glrectanglehack ===
{{anchor|.3Cglrectanglehack.3E}}
Problems with ghosting or videos which are only played back in the left upper quarter? The following ATI hack may solve it.
<syntaxhighlight lang="xml" enclose="div">
<glrectanglehack>yes</glrectanglehack>
</syntaxhighlight>

=== alwaysontop ===
{{anchor|.3Calwaysontop.3E}}
Added in XBMC v9.11 (Windows OS only). Keeps XBMC always on top when windowed.
<syntaxhighlight lang="xml" enclose="div">
<alwaysontop>yes</alwaysontop>
</syntaxhighlight>

Alternate code.
<syntaxhighlight lang="xml" enclose="div">
<videoscreen>
<fakefullscreen>false</fakefullscreen>
</videoscreen>
</syntaxhighlight>

== Recently removed tags ==
*{{anchor|.3Cthumbsize.3E}} '''<thumbsize>''' - replaced by <[[#imageres|imageres]]> in v12 Frodo
*{{anchor|.3Cfanartheight.3E}} '''<fanartheight>''' - replaced by <[[#fanartres|fanartres]]> in v12 Frodo
*{{anchor|.3Cdvdthumbs.3E}} '''<dvdthumbs>''' - removed in v12 Frodo
*{{anchor|.3Cbginfoloadermaxthreads.3E}} '''<bginfoloadermaxthreads>''' - removed in v13 Gotham
* '''<showepginfoonselect>''' - replaced by a GUI setting in v13 Gotham
*{{anchor|.3Cbusydialogdelayms.3E}} '''<busydialogdelayms>''' - removed in v13 Gotham
* Various sub-tags for <audio> were removed in v13 Gotham and replaced by GUI settings or were no longer needed: <resample>, <forceDirectSound>, <audiophile>, <audiosinkbufferdurationmsec>, <allowtranscode44100>, <streamsilence>

{{Gotham updated}}
{{DISPLAYTITLE:advancedsettings.xml}}

[[Category:Settings]]
[[Category:XBMC Manual]]
[[Category:Advanced topics]]

Archive:Intel Linux Modifications for HD Audio

2014-06-12T19:31:37Z

Fritsch: /* Kernel */

{{mininav|[[Audio]]}}
== Kernel ==
{{redv|'''WARNING:'''| All those changes are not needed when you run a current linux distribution (e.g. xbmcbuntu v13)! Don't make those changes.}}
HD Audio on Intel SandyBridge & IvyBridge systems require a patch from Intel to be included within the kernel, Linux 3.7 and higher include this patch as standard.

For more on this patch refer to [http://comments.gmane.org/gmane.linux.alsa.devel/100746 Intel HDMI HBR patches for HD Audio]

If you install a kernel >= 3.10.x you are on the safe side and no additional changes are needed (not matter if you have a spdif or not).

=== Kernel upgrades ===
To upgrade the kernel you need to obtain 3 files either x86 or x86_64 depending on your architecture.

Download 3 debs to a directory from this site http://kernel.ubuntu.com/~kernel-ppa/mainline/ (at time of writing '''3.10.5''' is/was the stable version) or greater. We also update the linux-firmware as we are at it.

# linux-headers-<version numbers>-all.deb
# linux-headers-<version numbers>-amd64.deb
# linux-image-<version number>-amd64.deb

{{note|The examples above needs you to choose the correct architecture for your installation or else you render your system unbootable!!}}

=== Kernel Download ===

Choose 32 bit if your system is running i686 kernel or choose 64 bit if your system is x86_64.

64 bit:
<syntaxhighlight lang="bash" enclose="div">
cd ~/
wget http://kernel.ubuntu.com/~kernel-ppa/mainline/v3.10.5-saucy/linux-headers-3.10.5-031005-generic_3.10.5-031005.201308040618_amd64.deb
wget http://kernel.ubuntu.com/~kernel-ppa/mainline/v3.10.5-saucy/linux-headers-3.10.5-031005_3.10.5-031005.201308040618_all.deb
wget http://kernel.ubuntu.com/~kernel-ppa/mainline/v3.10.5-saucy/linux-image-3.10.5-031005-generic_3.10.5-031005.201308040618_amd64.deb
wget http://mirrors.us.kernel.org/ubuntu//pool/main/l/linux-firmware/linux-firmware_1.113_all.deb
</syntaxhighlight>

32 bit:
<syntaxhighlight lang="bash" enclose="div">
cd ~/
wget http://kernel.ubuntu.com/~kernel-ppa/mainline/v3.10.5-saucy/linux-headers-3.10.5-031005-generic_3.10.5-031005.201308040618_i386.deb
wget http://kernel.ubuntu.com/~kernel-ppa/mainline/v3.10.5-saucy/linux-image-3.10.5-031005-generic_3.10.5-031005.201308040618_i386.deb
wget http://kernel.ubuntu.com/~kernel-ppa/mainline/v3.10.5-saucy/linux-headers-3.10.5-031005_3.10.5-031005.201308040618_all.deb
wget http://mirrors.us.kernel.org/ubuntu//pool/main/l/linux-firmware/linux-firmware_1.113_all.deb
</syntaxhighlight>

=== Kernel Install ===
Install the debs with these commands:
<syntaxhighlight lang="bash" enclose="div">
cd ~/
sudo dpkg -i *.deb
</syntaxhighlight>

After a reboot bitstream passthrough should be working. You can check the xbmc.log if your AVR capabilities are correctly identified. If the correct codecs / speaker numbers are not found, check the following settings with your AVR. We are aware that intel is currently really picky with AVRs - on really rare cases we could not get a single sound out of the AVR.

<syntaxhighlight lang="bash" enclose="div">
Audio TV Out - Off
TV Control - Off
HDMI Control - Off
Audio Output - AMP
</syntaxhighlight>

= Old workarounds (not needed on kernels >= 3.9.x anymore) =

== Intel Systems with both SPDIF & HDMI ==

On old kernel versions (prior to 3.9.x) systems which have a Intel GPU feeding a HDMI out but also have a motherboard SPDIF out require a patched Linux 3.7 or higher kernel and additional system modification to get sound on the HDMI out. In these circumstances both SPDIF & HDMI share certain system file settings which cause a conflict resulting in the HDMI sound being blocked, to fix this there are two options available:

'''1. Easy -''' Blacklist the SPDIF so only HDMI is available for audio, this also has the advantage of surviving system upgrades.

'''2. Difficult -''' If both SPDIF & HDMI are required to be active then editing then '''HDA-Intel.conf''' is required so there is no conflict in the device settings, however this might have to be reapplied after a system upgrade.
<br />
=== Easy - Blacklisting SPDIF - Fix (WIP) ===
<syntaxhighlight lang="xml" enclose="div">
aplay -L | grep -i iec958
</syntaxhighlight>
If you find S/PDIF on the same card as your intel hdmi rmmod the module that drives your S/PDIF.
<br />

=== Difficult - HDA-Intel.conf - Fix ===

{{redv|'''WARNING:'''|Only carry this out if you 100% know what you are doing as a wrong step can totally break audio.}}

'''This is not needed if you run a kernel >= 3.10.x''' as this already increases the index internally

This fix requires modification to:

<syntaxhighlight lang="xml" enclose="div">
/usr/share/alsa/cards/HDA-Intel.conf
</syntaxhighlight>

Open the '''HDA-Intel.conf''' file with a editor and look for entries containing:

<syntaxhighlight lang="xml" enclose="div">
"CTLINDEX="
</syntaxhighlight>

The numerical value after the = sign need to be increased by 1 so for example '''"CTLINDEX=1"''' becomes '''"CTLINDEX=2"'''

Example of original '''''/usr/share/alsa/cards/HDA-Intel.conf''''' file

<syntaxhighlight lang="xml" enclose="div">
@@ -211,7 +211,7 @@ HDA-Intel.pcm.hdmi.0 {
"cards.HDA-Intel.pcm.hdmi.common:"
"CARD=" $CARD ","
"DEVICE=3,"
"CTLINDEX=0,"

"AES0=" $AES0 ","
"AES1=" $AES1 ","
"AES2=" $AES2 ","
@@ -234,7 +234,7 @@ HDA-Intel.pcm.hdmi.1 {
"cards.HDA-Intel.pcm.hdmi.common:"
"CARD=" $CARD ","
"DEVICE=7,"
"CTLINDEX=1,"

"AES0=" $AES0 ","
"AES1=" $AES1 ","
"AES2=" $AES2 ","
@@ -257,7 +257,7 @@ HDA-Intel.pcm.hdmi.2 {
"cards.HDA-Intel.pcm.hdmi.common:"
"CARD=" $CARD ","
"DEVICE=8,"
"CTLINDEX=2,"
"AES0=" $AES0 ","
"AES1=" $AES1 ","
"AES2=" $AES2 ","
@@ -280,7 +280,7 @@ HDA-Intel.pcm.hdmi.3 {
"cards.HDA-Intel.pcm.hdmi.common:"
"CARD=" $CARD ","
"DEVICE=9,"
"CTLINDEX=3,"
"AES0=" $AES0 ","
"AES1=" $AES1 ","
"AES2=" $AES2 ","
</syntaxhighlight>

Becomes

<syntaxhighlight lang="xml" enclose="div">
@@ -211,7 +211,7 @@ HDA-Intel.pcm.hdmi.0 {
"cards.HDA-Intel.pcm.hdmi.common:"
"CARD=" $CARD ","
"DEVICE=3,"
"CTLINDEX=1,"
"AES0=" $AES0 ","
"AES1=" $AES1 ","
"AES2=" $AES2 ","
@@ -234,7 +234,7 @@ HDA-Intel.pcm.hdmi.1 {
"cards.HDA-Intel.pcm.hdmi.common:"
"CARD=" $CARD ","
"DEVICE=7,"
"CTLINDEX=2,"
"AES0=" $AES0 ","
"AES1=" $AES1 ","
"AES2=" $AES2 ","
@@ -257,7 +257,7 @@ HDA-Intel.pcm.hdmi.2 {
"cards.HDA-Intel.pcm.hdmi.common:"
"CARD=" $CARD ","
"DEVICE=8,"
"CTLINDEX=3,"
"AES0=" $AES0 ","
"AES1=" $AES1 ","
"AES2=" $AES2 ","
@@ -280,7 +280,7 @@ HDA-Intel.pcm.hdmi.3 {
"cards.HDA-Intel.pcm.hdmi.common:"
"CARD=" $CARD ","
"DEVICE=9,"
"CTLINDEX=4,"
"AES0=" $AES0 ","
"AES1=" $AES1 ","
"AES2=" $AES2 ","
</syntaxhighlight>

{{forum link2|[[forum:136555|DTS-HD MA forum thread discussion]]}}

[[Category:How-to]]
[[Category:Audio]]
{{frodo updated}}

PulseAudio

2014-06-10T18:01:55Z

Fritsch: /* Combined Output aka dual audio */

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when XBMC is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows XBMC playback of video or audio to be paused in order to run a game, Skype or similar. XBMC is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within XBMC, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device XBMC required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in XBMC when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the XBMC implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode XBMC must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by XBMC to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by XBMC, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in xbmc ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| XBMC Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|XBMC Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

xbmc will then pickup the device, it is named '''combined'''.

{{orangev|'''Downside:'''| The dual audio sink will only output decoded audio, you cannot use it to have one slave doing AC3/DTS and the other PCM. If you use the combined sink for normal music and the direct passthrough output for your movies, you get probably best out of both worlds. }}

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside xbmc, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination xbmc will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your XBMC computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with XBMC.
* You use xbmc in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, xbmc audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use XBMC as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|But you know that doing so, it will cause problems!}}

Yes, you can - start xbmc from terminal with:
<pre>AE_SINK=ALSA xbmc</pre>
: Be warned as this might interfere with your Desktop sounds and PulseAudio!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in xbmc. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

=== References ===
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2014-05-11T16:40:03Z

Fritsch: /* Known issues */

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when XBMC is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows XBMC playback of video or audio to be paused in order to run a game, Skype or similar. XBMC is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within XBMC, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device XBMC required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in XBMC when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the XBMC implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode XBMC must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by XBMC to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by XBMC, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in xbmc ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| XBMC Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|XBMC Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

xbmc will then pickup the device, it is named '''combined'''.

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside xbmc, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination xbmc will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your XBMC computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with XBMC.
* You use xbmc in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, xbmc audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use XBMC as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|But you know that doing so, it will cause problems!}}

Yes, you can - start xbmc from terminal with:
<pre>AE_SINK=ALSA xbmc</pre>
: Be warned as this might interfere with your Desktop sounds and PulseAudio!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot or passthrough only produces noise, you might have a broken driver in use. If this is the case, try to add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in xbmc. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

=== References ===
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2014-05-11T16:39:08Z

Fritsch: /* Audiophile Pulse User */

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when XBMC is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows XBMC playback of video or audio to be paused in order to run a game, Skype or similar. XBMC is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within XBMC, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device XBMC required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in XBMC when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the XBMC implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode XBMC must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by XBMC to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by XBMC, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in xbmc ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| XBMC Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|XBMC Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

xbmc will then pickup the device, it is named '''combined'''.

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sink.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside xbmc, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination xbmc will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your XBMC computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with XBMC.
* You use xbmc in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, xbmc audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use XBMC as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|But you know that doing so, it will cause problems!}}

Yes, you can - start xbmc from terminal with:
<pre>AE_SINK=ALSA xbmc</pre>
: Be warned as this might interfere with your Desktop sounds and PulseAudio!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot, you might have a broken driver in use. If this is the case, add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in xbmc. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

=== References ===
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2014-05-11T11:58:29Z

Fritsch: Add Remark for audiophile users

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when XBMC is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows XBMC playback of video or audio to be paused in order to run a game, Skype or similar. XBMC is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within XBMC, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device XBMC required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in XBMC when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the XBMC implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode XBMC must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by XBMC to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by XBMC, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in xbmc ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| XBMC Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|XBMC Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

xbmc will then pickup the device, it is named '''combined'''.

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

Some remark: This will actively make '''passthrough non working''', as we need s16le format for adding ac3 / dts / etc. float to the sin.

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside xbmc, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination xbmc will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your XBMC computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with XBMC.
* You use xbmc in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, xbmc audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use XBMC as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|But you know that doing so, it will cause problems!}}

Yes, you can - start xbmc from terminal with:
<pre>AE_SINK=ALSA xbmc</pre>
: Be warned as this might interfere with your Desktop sounds and PulseAudio!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot, you might have a broken driver in use. If this is the case, add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in xbmc. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

=== References ===
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]

PulseAudio

2014-05-04T12:25:47Z

Fritsch: /* FAQ */

{{mininav|[[Audio]]|[[Linux audio]]}}
<section begin="intro" />This page goes into detail on using PulseAudio on Linux systems. PulseAudio is used when XBMC is installed in a desktop-environment rather than a dedicated/direct boot setup. PulseAudio allows normal video & audio playback in XBMC while at the same time allowing the user to get audio in their browser or other applications. It also allows XBMC playback of video or audio to be paused in order to run a game, Skype or similar. XBMC is set to only use PulseAudio if you have installed it and running.<section end="intro" />

== History ==
In the past users have experienced problems with audio not working within XBMC, because they were running a full-blown Ubuntu desktop environment with PulseAudio installed. This happened because PulseAudio blocked the device XBMC required, and audio playback only worked reliably when using the virtual Pulse device.

Our workaround for those users has been to uninstall PulseAudio which completely broke desktop audio.

For XBMC 13 'Gotham' and later we wanted this situation to change, so thanks to the new '''PulseAudio Sink''' users now can run a normal Ubuntu desktop.

== PulseAudio Output Configuration ==
PulseAudio will be automatically detected and selected in XBMC when it is running.

PulseAudio can be run in one of two modes these are:

<big>'''Passthrough Mode'''</big>
Used if you want to passthrough (bitstream) AC3, DTS, and EAC3 to an AVR or other device. In order to allow passthrough to work with PulseAudio then it '''MUST''' be set to use a 2.0 channel configuration, despite the 2.0 setting this will still allow 5.1 audio from AC3, DTS, and EAC3.

{{Note| PulseAudio does not currently allow TrueHD or DTS-MA passthrough, this is a PulseAudio limitation and not a limitation of the XBMC implementation.}}

<big>'''Multichannel Mode'''</big>

Used if you want Multichannel PCM out, in this mode you can configure PulseAudio for up to 7.1 channels. In this mode XBMC must decode all audio formats to PCM for passing onto the PulseAudio, this can have the advantage of improve audio/video sync.

{{Note| Audio decoded to PCM and sent through PulseAudio the audio will not likely be "bit perfect". Where a video has TrueHD 7.1 audio, this can be decoded by XBMC to PCM 7.1, however DTS-HD 7.1 audio can't be decoded by XBMC, only the embedded DTS Core 5.1 can be decoded to PCM 5.1 audio.}}

<br />

== Setting up pavucontrol ==

=== Passthrough Mode ===
{{bluev|'''IMPORTANT:'''|Passthrough is always exclusive mode. If you have another application hogging the device, e.g. google chrome or skype or something else, Passthrough won't work.}}
{{greenv|'''REMEMBER:'''| To use passthrough you need to be using '''2.0''' channel configuration via '''pavucontrol''' (e.g. Digital Stereo (HDMI)}}

In order to activate Passthrough Codecs, just setup pavucontrol, as in the following:

<gallery widths=500px heights=313px>
File:Passthrough2.png|<big>'''Step 1:'''</big> ''pavucontrol'' '''Output Settings.'''
File:Passthrough1.png|<big>'''Step 2:'''</big> ''pavucontrol'' '''Configuration.'''
</gallery>

If you like to do this from the command line, issue:
'''pactl set-sink-formats 0 "pcm; ac3-iec61937; dts-iec61937; eac3-iec61937"'''

Where '''0''' is the sink you want to alter.
You can print all sinks, by using:
'''pactl list sinks'''
You can leave out the codecs your AVR does not support, always keep pcm.

{{bluev|'''IMPORTANT:'''| If you have for example 5.1 flacs or other multichannel files, you can play them as AC3 streams, check the AC3 Transcoding setting.}}

=== Multichannel Mode ===
{{greenv|'''REMEMBER:'''| When configuring pulse to use '''Multichannel configuration''' passthrough will be disabled}}
To configure instead Multi channel mode, do the following settings.

<gallery widths=500px heights=313px>
File:Lpcm2.png|<big>'''Step 1:'''</big> ''To alternatively configure Multi channel, check this:''.
File:Lpcm1.png|<big>'''Step 2:'''</big> The ''Add-on manager'', displaying four/five options (explained below).
</gallery>

=== Example setup in xbmc ===
{{orangev|'''GOOD TO KNOW:'''| Limit sample rate can be set to Fixed - between 48kHz ~ 192kHz or as Optimized and even Best match.}}

<gallery widths=500px heights=313px>
File:Xbmclpcm.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpaa1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>

<gallery widths=500px heights=313px>
File:Xbmcpass2.png |<big>'''Step 1:'''</big> ''to be edited'' '''Output Settings.'''
File:Xbmcpass1.png |<big>'''Step 2:'''</big> ''to be edited'' '''Configuration.'''
</gallery>
{{-}}

=== Setup Guide ===
{{orangev|DEVICE ENUMERATION:| XBMC Enumerates Pulseaudio devices as SPDIF when you have '''Passthrough''' set. Otherwise its '''PCM Device'''.}}
{{bluev|GOOD TO KNOW:|SPDIF has 2 pcm channels but can do virtual 5.1 formats like dts, ac3, eac3.}}
{{greenv|'''NOTICE'''|The following is meant to act as a guide to get you started, thus you may want to adjust things to suit your own particular set of equipment.}}
{| class="prettytable" style="text-align: center; color: black;"
!
! PC Speakers<br />2.0
! PC Speakers<br />5.1
! TV SPDIF<br />2.0
! TV SPDIF<br />AC3 ('''1''')
! AVR SPDIF<br />AC3/DTS ('''2''')
! AVR HDMI<br />PCM ('''3''')
! AVR HDMI<br />No HD Audio ('''4''')
! AVR HDMI<br />Decode HD Audio ('''5''')
|-
! colspan="9"|'''PusleAudio Mode'''
|-
|
|Multichannel
|Multichannel
|Multichannel
|Passthrough
|Passthrough
|Multichannel
|Passthrough
|Multichannel
|-
! colspan="9"|'''Pavucontrol - Output Devices'''
|-
|align="left"|'''Port'''
|Speakers
|Speakers
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|Digital Output (S/PDIF)
|HDMI/Displayport
|HDMI/Displayport
|HDMI/Displayport
|-
|align="left"|'''AC3'''
|N/A
|N/A
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''EAC3'''
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS'''
|N/A
|N/A
|Disabled
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
! colspan="9"|'''Pavucontrol - Configuration'''
|-
|align="left"|'''Profile'''
|Analog Stereo Output
|Analog Surround 5.1 Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Stereo <br />(IEC958) Output
|Digital Surround 5.1 <br />(HDMI) Output
|Digital Stereo <br />(HDMI) Output
|Digital Surround 7.1 <br />(HDMI) Output
|-
!Colspan="9"|XBMC Settings
|-
|align="left"|'''Audio Output Device'''
|Speakers
|Speakers
|SPDIF
|SPDIF
|SPDIF
|HDMI
|HDMI
|HDMI
|-
|align="left"|'''Number of channels'''
|2.0
|5.1
|N/A
|N/A
|N/A
|5.1
|2.0
|7.1
|-
|align="left"|'''Enabled passthrough'''
|Disabled
|Disabled
|Disabled
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Passthrough output device'''
|N/A
|N/A
|N/A
|SPDIF
|SPDIF
|N/A
|HDMI
|N/A
|-
|align="left"|'''Dolby Digital (AC3) capable receiver'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''Enabled Dolby Digital transcoding'''
|N/A
|N/A
|N/A
|Enabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''DTS capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Enabled
|Disabled
|Enabled
|Disabled
|-
|align="left"|'''TrueHD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Disabled
|-
|align="left"|'''DTS-HD capable receiver'''
|N/A
|N/A
|N/A
|Disabled
|Disabled
|Disabled
|Disabled
|Dsiabled
|}

'''(1)''' Where TV can decode 5.1 AC3.

'''(2)''' Where AVR only has SPDIF which will support 5.1 AC3 & DTS.

'''(3)''' Where AVR can do 5.1 PCM.

'''(4)''' Where AVR has HDMI inputs but can't decode TrueHD or DTS-HD but does support 5.1 Ac3 or DTS.

'''(5)''' Where AVR has full decode capabilities including 7.1 PCM.

{{orangev|'''IMPORTANT:'''| You can only have '''AC3''', '''DTS''', '''EAC3''' passthrough '''if your Receiver supports it'''. Most '''TV's''' only support '''AC3'''. If you have a '''HDMI''' connection to your TV and '''from this TV''' a '''SPDIF/Optical''' connection to an '''AVR''', passthrough might not work at all.}}

== Combined Output aka dual audio==
If you want to output to all your attached devices in parallel, e.g. HDMI out, analog out and USB sound card, it is enough to do as below:

'''Step 1:''' Edit <code>/etc/pulse/default.pa</code>

<pre>load-module module-combine-sink sink_name=combined</pre>
'''Step 2: '''Restart pulseaudio.
<pre>killall pulseaudio</pre>

xbmc will then pickup the device, it is named '''combined'''.

== Audiophile Pulse User ==
Pulseaudio resamples everything that does not match the underlaying sink, so if you are an audiophile user, you perhaps want to hear your 96 / 192 khz and 24 bit recordings as exact as possible. Therefore you need to tell pulseaudio to use a better resampler in general and second change the default sample rate to 96 or 192 khz. Pulseaudio does not resample audio, that is already in the correct samplerate. Furthermore you need to take care, that your sink has a wide enough output format.

To do this configuration systemwide (96 khz in that example), change /etc/pulse/daemon.conf to include (please replace already existing lines and also remove the commenting):

<pre>
default-sample-format = s32le
default-sample-rate = 96000
resample-method = speex-float-5
</pre>

The last setting will increase the resample quality from pulse and therefore the CPU load quite a lot. Again: Resampling is only done, when the sink output does not match the data you throw onto it. But as most normal mp3s are in 44.1 khz, you need to take great care when upsampling them. The overwriting of the resample-method is for this use case.

{{orangev|'''Alternatively:'''| If you don't want any resampling outside xbmc, e.g. no resampling done extra by pulse, you need to configure the sink as told above and set Audio Engine to '''Fixed''' with the number of channels you configured pulseaudio via pavucontrol and samplerate of '''96 khz''' with resample quality high. In that combination xbmc will take care that files are resampled (e.g. 44.1 khz or 48 khz media) in the best possible quality. Already 96 khz files are not touched at all. }}

== FAQ ==

{| width="100%"
{{FAQ|1=When_would_I_want_Pulseaudio
| BGcolor=whitesmoke
| Question=When would I want PulseAudio?
| Answer=
You should use '''PulseAudio''' when:

* You use your XBMC computer mainly as your Desktop when you don't run XBMC.
* You want other applications audio like Skype, youtube, browser mail notification in parallel with XBMC.
* You use xbmc in windowed mode as Desktop player
* You use Pulseaudio as a network sink to stream Audio to other devices in your living room.
* Passthrough is nice to have for you, but to be honest - you don't really need it.
* Whenever you plugin your Bluetooth headset, xbmc audio will continue over this new device (when Default 'PULSE' device is chosen)
}}

{{FAQ|1=When_would_I_want_ALSA
| BGcolor=
| Question=When would I want ALSA?
| Answer=
You should use '''ALSA''' when:

* You use XBMC as your standalone media center.
* You are highly interested in bitperfect exclusive audio output.
* DTS-HD, TrueHD is something you use daily and is of high importance.
* You don't need other applications that would access audio in parallel.
}}

{{FAQ|1=Why_cant_I_have_both?
| BGcolor=whitesmoke
| Question=Why can't I have both?
| Answer=
* '''PulseAudio''' might hog your Audio device and you cannot open the '''ALSA''' device exclusively, therefore we decided for one or the other.
}}

{{FAQ|1=Forcing_alsa
| BGcolor=
| Question=Can I force ALSA even with PulseAudio installed?
| Answer=
{{note|But you know that doing so, it will cause problems!}}

Yes, you can - start xbmc from terminal with:
<pre>AE_SINK=ALSA xbmc</pre>
: Be warned as this might interfere with your Desktop sounds and PulseAudio!
}}
|}
=== Known issues ===
When your audio is much too fast or crackles a lot, you might have a broken driver in use. If this is the case, add ''tsched=0'' to the udev loading section in /etc/pulse/default.pa to read like:

''load-module module-udev-detect tsched=0''

When Pulseaudio is configured to be multi-channel output, e.g. 5.1 profile from within pavucontrol, 2.0 streams are automatically upmixed, no matter what setting you have chosen in xbmc. This is default pulseaudio server behaviour. You can workaround that by disabling ''enable-remixing'' in /etc/pulse/daemon.conf

''enable-remixing = no''

=== References ===
{{forum link2|[[forum:183436|Linux - Pulseaudio Sink]] Discussion and further information.}}<br />

[[Category:How-to]]
[[Category:Audio]]