External players

While the built in DVDplayer and PAPlayer 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. Reasons might include improved postprocessing abilities, GPU accelerated video decoding and other special features not (yet) offered by the internal players. Thanks to several brave developers we have a powerful tool at our disposal: the external player option. By simply configuring the playercorefactory.xml file, we can alter the default player for different sources (videos, music, DVDs, etc.).

playercorefactory.xml

XBMC comes with a default playercorefactory.xml, located under the XBMC\System folder (where XBMC 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: <xml> <playercorefactory>

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

</playercorefactory> </xml>

The <players/> node defines all the different players that you wish to add to XBMC. Inside you can have a potentially infinite 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 aready exist and don't accept any configuration). The audio and video (boolean) 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 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.

<filename/> - should contain the path of the external player executable

<args/> - should contain arguments to pass to the external player executable.

<hidexbmc/> - win32 only - should contain true or false (default), when true the XBMC window is hidden whist the external player is active

<hideconsole/> - win32 only - should contain true or false (default), when true the external player process is started with the initial window hidden (useful for hiding the console when the external player is a batch file)

<hidecursor/> - win32 only - should contain true or false (default), when true the cursor is moved to the bottom-right of the screen before the external player is launched

<forceontop/> its purpose is to remove the XBMC window's ONTOP attribute when the external-player is playing and put it back afterwards.

Once a user has defined one or more external player, he has 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 a suffix of 720p in their filename.

A <rules/> node contains a set of rules. An (optional) action attribute can have a value of prepend, append or overwrite which specifies whether the rules should be prepended, appended (the default if no action is specified) or replace all existing rules.

A <rule/> 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 <rule/>s is significat, the first match defines the player so order then from more-to-less specific.

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

 <rule video="true" player="wmplayer">
   <rule dvd="true" player="dvdplayer">
   <rule filetype="mkv" player="VLC">
     <rule filename=".*720.*|.*1080.*" player="MPC-HC"/>
   </rule>
 </rule>

</rules> </xml>

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:

internetstream

   boolean - true matches an internet stream

audio

   boolean - true matches audio-only media

video

   boolean - true matches video media

dvd

   boolean - true matches a DVD

dvdimage

   boolean - true matches a DVD image (iso)

dvdfile

   boolean - true matches a DVD folder structure

protocols

   regexp - matched against the (URI) protocol, as well as "real" protocols like
   daap, rtv, rtsp XBMC also uses the URI protocol for things like zip, rar etc.

filetypes

   regexp - matched against the file extension, again

mimetypes

   regexp - matched against the mime-type of the media

filename

   regexp - matched against the filename

player

   string - the name of the player defined in the <players> section

For the regexp attributes you can specify a like with a |-separator, e.g. mkv|avi|divx