External players

This page or section may require cleanup, updating, spellchecking, reformatting and/or updated images. Please improve this page if you can. The discussion page may contain suggestions.

While the built in DVDPlayer (video) and PAPlayer (audio) are capable, out of the box, to handle a huge variety of content, users might find themselves in need of using a different playback software but still using Kodi for scraping and organizing content. Reasons might include improved post-processing abilities, DRM restricted media that requires a specific player (such as encrypted Blu-ray discs), special player-specific features, etc. Kodi has a powerful tool to achieve this, the external player. The current method involves the configuration of a playercorefactory.xml file.

Set up

Kodi comes with a default playercorefactory.xml file, located under the Kodi/System folder (where Kodi is the chosen installation folder).

To customize playback behaviour, users need to create an extra playercorefactory.xml file inside their userdata folder. Please consult the plaform specific FAQ for the appropriate location.

Let's start with an example playercorefactory.xml file:

<playercorefactory>
 <players>
   <player name="MPC-HC" type="ExternalPlayer" audio="false" video="true">
     <filename>C:\Program Files\MPC-HC\mplayerc.exe</filename>
     <args>"{1}" /fullscreen /close</args>
     <hideKodi>false</hideKodi>
     <hideconsole>false</hideconsole>
     <warpcursor>none</warpcursor>
   </player>
 </players>
 <rules action="prepend">
   <rule filetypes="mkv" filename=".*720p.*" player="MPC-HC"/>
 </rules>
</playercorefactory>

The <players/> node (i.e. <players>...<players/>) defines all the different players that you wish to add to Kodi. Inside you can have any number of <player/> nodes, defining as many external players as you wish (the builtin ones being dvdplayer and paplayer, you can also use the aliases audiodefaultplayer, videodefaultplayer, videodefaultdvdplayer).

The player name attribute can be anything you like and will appear in the "Play using..." menu, accessible from the context menu. For an external player the type attribute must be ExternalPlayer. The other possible values being dvdplayer and paplayer, although there's no point defining one of those as they already exist and don't accept any configuration. The audio and video (boolean; true/false) attributes when true will cause the player to always appear in the "Play using..." menu even if you don't define any rules for the player, or no rules match the currently selected media item (e.g. video file) for the player. You could, for instance, define a player with video="true" and then not tie it to any specific rule, thus creating some sort of "safety net", always available in the context menu, should you ever need it.

The only required node for a player with type ExternalPlayer is the <filename/> node, this should contain the path of the external player executable. The other, optional, nodes are

Name	Value	Use
args		Arguments to pass to the external player executable. If this contains the token {0} then this is replaced with the full URI of the item to be played (note that this is, in many cases, Kodi-specific and your external player won't understand it). A {1} token is also replaced with the URI of the item to be played, but with the following differences For rar and zip files {1} is the path of the archive and {2} will be the relative path to the file in the archive On win32 smb-URIs (smb://host/path) are converted into UNCs (\\host\path) For LiveTV streams/files the pvr:// type url is not translated and {1} still returns the Kodi-specific URI which will not be interpretable by the external player NOTE you should surround these tokens with double-quotes (e.g. "{1}") unless you know what you're doing and have a good reason not to, as they may contain spaces. If none of these tokens are present then it's equivalent to having "{1} at the end.
hideKodi	false (default) true	whether to hide the Kodi window whilst the external player is active
hideconsole	false (default) true	Win32 only - whether the external player process is started with the initial window hidden (useful for hiding the console when the external player is a batch file)
warpcursor	none (default) topleft topright bottomleft bottomright	Win32 only - whether and where to move the cursor to before the external player is launched