View source for External players

{{cleanup}}
<section begin="intro" />While the built in video and audio players 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.<section end="intro" />

== 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.<br />

Let's start with an example playercorefactory.xml file:
<syntaxhighlight lang=xml enclose="div">
 <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>
      <hidexbmc>false</hidexbmc>
      <hideconsole>false</hideconsole>
      <warpcursor>none</warpcursor>
    </player>
  </players>
  <rules action="prepend">
    <rule filetypes="mkv" filename=".*720p.*" player="MPC-HC"/>
  </rules>
 </playercorefactory>
</syntaxhighlight>

The <code><players/></code> node (i.e. <code><players>...<players/></code>) defines all the different players that you wish to add to Kodi. Inside you can have any number of <code><player/></code> 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 <code>name</code> attribute can be anything you like and will appear in the [[Media:Playusing.png|"Play using..." menu]], accessible from the [[Basic_controls#Context_Menu|context menu]].
For an external player the <code>type</code> 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 <code>audio</code> and <code>video</code> (boolean; true/false) attributes when <code>true</code> 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 <code>video="true"</code> 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 <code>type</code> ''ExternalPlayer'' is the <code><filename/></code> node, this should contain the path of the external player executable. The other, optional, nodes are


{| class="prettytable"
|-
! Name
! Value
! Use
|-
! args
|
| Arguments to pass to the external player executable.<br />
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).<br />A '''{1}''' token is also replaced with the URI of the item to be played, but with the following differences<br />
* 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)<br />
* 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.'''<br />
If none of these tokens are present then it's equivalent to having '''"{1}''' at the end.
|-
! hidexbmc
| style="white-space:nowrap" | '''false''' ''(default)''<br />'''true'''
| whether to hide the Kodi window whilst the external player is active
|-
! hideconsole
| style="white-space:nowrap" | '''false''' ''(default)''<br />'''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
| style="white-space:nowrap" | '''none''' ''(default)''<br />'''topleft'''<br />'''topright'''<br />'''bottomleft'''<br />'''bottomright'''
| ''Win32 only'' - whether and where to move the cursor to before the external player is launched
|-
! playcountminimumtime
| style="white-space:nowrap" | ''number of seconds''
| the time the extplayer process needs to run for before the item's playcount will be incremented (i.e. it will be marked as watched)
|-
! playonestackitem
| style="white-space:nowrap" | '''false''' ''(default)''<br />'''true'''
| whether playback should stop after playing one item that's part of a stack
|}

Once a user has defined one or more external player, they have the option of adding ''rules'' to customize ''which files'' are handled by ''which players''. The above example, for instance, defines the MPC-HC external player as the default player for MKV files with "720p" in their filename. <code>.*</code> before and after "720p" is a [http://en.wikipedia.org/wiki/Regular_expression#Standards regular expression] (regex).
* <code>.</code> "Matches any single character."
* <code>*</code> "Matches the preceding element zero or more times."<br />
Together they mean "Matches any single character (.) zero or more times (*)".

A <code><rules/></code> node contains a set of rules. An (optional) <code>action</code> attribute can have a value of <code>prepend</code>, <code>append</code> or <code>overwrite</code> which specifies whether the rules should be prepended, appended (the default if no action is specified) or replace all existing rules. Appended rules will take precedence over default players (i.e. DVDPlayer for video and PAPlayer for audio) but not over Kodis builtin rules. '''[needs better/more complete explanation]'''

A <code><rule/></code> node compares its attributes against the attributes of a media item and if everything matches then the player names in the player attribute is the default player for the media item (you can still select another using the "Play using..." menu). The attributes are listed below. Order of <code><rule/></code>s is significant '''[needs clarification]''', the first match defines the player so order them from more-to-less specific.


<code><rule/></code>s can be nested with inner rules inheriting attributes from outer rules, with inner rules being checked before outer rules. For example:

<syntaxhighlight lang=xml enclose="div">
 <rules action="prepend">
  <rule video="true" player="wmplayer">
    <rule dvd="true" player="dvdplayer"/>
    <rule filetypes="mkv" player="VLC">
      <rule filename=".*720.*|.*1080.*" player="MPC-HC"/>
    </rule>
  </rule>
 </rules>
</syntaxhighlight>

says that all video should be played by wmplayer, except DVDs, that are played with (the builtin) dvdplayer, and .mkv files that are played with VLC, however .mkv files with "720{{"}} or "1080" in  their names are played with MPC-HC (all assuming wmplayer, VLC and MPC-HC players are defined in the players section).

The following attributes can be used to build rules:
{| class="prettytable"
|-
! Attribute
! Type
! Value
|-
| name || string
| name of the rule
|-
| internetstream || boolean
| when '''true''' the rule applies to internet streams
|-
| remote || boolean
| when '''true''' the rule applies to remote-only (non-local) media
|-
| audio || boolean
| when '''true''' the rule applies to audio-only media
|-
| video || boolean
| when '''true''' the rule applies to video media
|-
| dvd || boolean
| when '''true''' the rule applies to DVDs
|-
| dvdimage || boolean
| when '''true''' the rule applies to DVD images (iso)
|-
| dvdfile || boolean
| when '''true''' the rule applies to DVD folder structures
|-
| protocols || regexp
| when defined the rule applies to items whose (URI) protocol matches; as well as "real" protocols like daap, rtv, rtsp Kodi also uses the URI protocol for things like zip, rar etc.
|-
| filetypes || regexp
| when defined the rule applies to items whose file extension matches
|-
| mimetypes || regexp
| when defined the rule applies to items whose mime-type matches
|-
| filename || regexp
| when defined the rule applies to items whose filename matches
|-
| player || string
| the name of the player defined in the <players> section this rule invokes
|}
For the regexp attributes you can specify alike with a |-separator, e.g. '''mkv|avi|divx''' ("The choice operator matches either the expression before or the expression after the operator").

The following attributes are also available for video items with metadata (a.k.a. flagging):
{| class="prettytable"
|-
! Attribute
! Type
! Value
|-
| videocodec || regexp
| matched against the video codec so, a rule could used '''<nowiki>xvid|divx|div3|div4|div5</nowiki>'''
|-
| videoresolution || regexp
| matched against the video resolution, which will be one of '''480''', '''540''', '''720''' or '''1080'''
|-
| videoaspect || boolean
| matched against the video aspect ratio, which will be one of '''1.33''', '''1.66''', '''1.78''', '''1.85''', '''2.20''' or '''2.35'''
|-
| hdrtype || regexp
| matched against the video hdr type, which could be one of '''none''' (=sdr video), '''hdr10''', '''hlg''' or '''dolbyvision''' - ''v22 and above''
|-
| audiocodec || regexp
| matched against the audio codec, e.g. '''ac3<nowiki>|</nowiki>dts'''
|-
| audiochannels || regexp
| matched against the number of channels in the audio which will be an integer (i.e. '''6''' rather than '''5.1''')
|}

{{divbox|orange||'''Note:''' There's currently no way to get a resume point if an external player is in use. After a specific duration (which can be modified via the [[Advancedsettings.xml|advancedsettings.xml]]) the specific video will be marked as watched. But Kodi will not set a resume point for it.}}

== Examples ==
On Kodi for Android running on TI OMAP pandaboard I was able to take advantage of hw acceleration by changing /data/data/org.xbmc.kodi/cache/apk/assets/system/playercorefactory.xml to launch Gallery on mp4 files as follows:

=== Android ===
<syntaxhighlight lang=xml enclose="div">
 <playercorefactory>
  <players>
    <!-- These are compiled-in as re-ordering them would break scripts
    The following aliases may also be used:
      audiodefaultplayer, videodefaultplayer, videodefaultdvdplayer
    <player name="DVDPlayer" audio="true" video="true" />
    <player name="DVDPlayer" /> placeholder for MPlayer
    <player name="PAPlayer" audio="true" />
    -->
    <player name="Gallery" type="ExternalPlayer" audio="true" video="true">
       <filename>am</filename>
       <args>start -n com.android.gallery3d/.app.MovieActivity -d {1}</args>
       <hidexbmc>true</hidexbmc>
       <hideconsole>true</hideconsole>
    </player>
    <player name="DVDPlayer" audio="true" video="true" />
  </players>
  <rules name="system rules">
    <rule name="rtv" protocols="rtv" player="DVDPlayer" />
    <rule name="hdhomerun/myth/mms/udp" protocols="hdhomerun|myth|cmyth|mms|mmsh|udp" player="DVDPlayer" />
    <rule name="lastfm/shout" protocols="lastfm|shout" player="PAPlayer" />
    <!-- dvdplayer can play standard rtsp streams -->
    <rule name="rtsp" protocols="rtsp" filetypes="!(rm|ra)"  player="PAPlayer" />
    <!-- Internet streams -->
    <rule name="streams" internetstream="true">
      <rule name="aacp/sdp" mimetypes="audio/aacp|application/sdp" player="DVDPlayer" />
      <rule name="mp2" mimetypes="application/octet-stream" filetypes="mp2" player="PAPlayer" />
    </rule>
    <!-- DVDs -->
    <rule name="dvd" dvd="true" player="DVDPlayer" />
    <rule name="dvdimage" dvdimage="true" player="DVDPlayer" />
    <!-- Only dvdplayer can handle these normally -->
    <rule name="sdp/asf" filetypes="sdp|asf" player="DVDPlayer" />
    <!-- Pass these to dvdplayer as we do not know if they are audio or video -->
    <rule name="nsv" filetypes="nsv" player="DVDPlayer" />
    <rule name="dgb" filetypes="*.mp4" player="Gallery"/>
    <!-- pvr radio channels should be played by dvdplayer because they need buffering -->
    <rule name="radio" filetypes="pvr" filename=".*/radio/.*" player="DVDPlayer" />
  </rules>
 </playercorefactory>
</syntaxhighlight>


I tested this only very lightly but it improved playback smoothness and obviously reduced cpu load. ymmv.

=== Ubuntu ===

{{divbox|orange||'''Note:''' The Ubuntu OS has a long-lasting NFS bug which prevents Kodi from playing files directly via its own internal NFS sources using an external video player. You will have to set up NFS mounts directly via the Ubuntu OS to have this work correctly.}}

In GNU/Linux the location of the file should be: <code>~/.kodi/userdata/playercorefactory.xml</code>

There are cross-platform standalone video players which are supported by Kodi. Hereunder are two of them. The Full-screen option has been added, otherwise you will have a windowed video player.

==== VLC ====
<syntaxhighlight lang=xml enclose="div">
<playercorefactory>
  <players>
    <player name="VLC" type="ExternalPlayer" audio="false" video="true">
      <filename>/usr/bin/vlc</filename>
      <args>--fullscreen "{1}"</args>
      <hidexbmc>false</hidexbmc>
    </player>
  </players>
  <rules action="prepend">
    <rule video="true" player="VLC"/>
  </rules>
</playercorefactory>
</syntaxhighlight>

==== MPV ====
<syntaxhighlight lang=xml enclose="div">
<playercorefactory>
  <players>
    <player name="MPV" type="ExternalPlayer" audio="false" video="true">
      <filename>/usr/bin/mpv</filename>
      <args>--fs=yes "{1}"</args>
      <hidexbmc>false</hidexbmc>
    </player>
  </players>
  <rules action="prepend">
    <rule video="true" player="MPV"/>
  </rules>
</playercorefactory>
</syntaxhighlight>

== See also ==
;Windows
* [[forum:43511|Forums:External Player Support Thread on the Kodi forums]]
* [[forum:116724|Forums:Working External Player Solution]]

;Android
* [[HOW-TO:Use external players on Android]]

{{updated|18}}
[[Category:Players]]
[[Category:Manual]]
[[Category:Advanced topics]]