External players: Difference between revisions

From Official Kodi Wiki
Jump to navigation Jump to search
No edit summary
>NedBot
m (User-controlled Bot: table syntax updated)
Line 35: Line 35:
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
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


<table border="1" cellpadding="2" cellspacing="0">
<tr><th>Name</th><th>Value</th><th>Use</th></tr>


<tr><th>args</th>
{| border="1" cellpadding="2" cellspacing="0"
<td></td>
|-
<td>Arguments to pass to the external player executable.<br />
! 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, XBMC-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 />
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, XBMC-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
* 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
Line 46: Line 50:
'''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 />
'''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.
If none of these tokens are present then it's equivalent to having '''"{1}''' at the end.
</td></tr>
|-
 
! hidexbmc
<tr><th>hidexbmc</th>
| style="white-space:nowrap" | '''false''' ''(default)''<br />'''true'''
<td style="white-space:nowrap">'''false''' ''(default)''<br />'''true'''</td>
| whether to hide the XBMC window whilst the external player is active
<td>whether to hide the XBMC window whilst the external player is active </td></tr>
|-
 
! hideconsole
<tr><th>hideconsole</th>
| style="white-space:nowrap" | '''false''' ''(default)''<br />'''true'''
<td style="white-space:nowrap">'''false''' ''(default)''<br />'''true'''</td>
| ''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)
<td>''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)</td></tr>
|-
 
! warpcursor
<tr><th>warpcursor</th>
| style="white-space:nowrap" | '''none''' ''(default)''<br />'''topleft'''<br />'''topright'''<br />'''bottomleft'''<br />'''bottomright'''
<td style="white-space:nowrap">'''none''' ''(default)''<br />'''topleft'''<br />'''topright'''<br />'''bottomleft'''<br />'''bottomright'''</td>
| ''Win32 only'' - whether and where to move the cursor to before the external player is launched
<td>''Win32 only'' - whether and where to move the cursor to before the external player is launched</td></tr>
|-
 
! playcountminimumtime
<tr><th>playcountminimumtime</th>
| style="white-space:nowrap" | ''number of seconds''
<td style="white-space:nowrap">''number of seconds''</td>
| 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)
<td>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)</td></tr>
|-
 
! playonestackitem
<tr><th>playonestackitem</th>
| style="white-space:nowrap" | '''false''' ''(default)''<br />'''true'''
<td style="white-space:nowrap">'''false''' ''(default)''<br />'''true'''</td>
| whether playback should stop after playing one item that's part of a stack
<td>whether playback should stop after playing one item that's part of a stack </td></tr>
|}
</table>


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 a suffix of 720p in their filename.
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 a suffix of 720p in their filename.
Line 89: Line 92:
The following attributes can be used to build rules:
The following attributes can be used to build rules:


<table border="1" cellpadding="2" cellspacing="0">
<tr><th>Attribute</th><th>Type</th><th>Value</th></tr>
<tr><td>internetstream</td>
<td>boolean</td>
<td>when '''true''' the rule applies to internet streams</td></tr>


<tr><td>audio</td>
{| border="1" cellpadding="2" cellspacing="0"
<td>boolean</td>
|-
<td>when '''true''' the rule applies to audio-only media</td></tr>
! Attribute
 
! Type
<tr><td>video</td>
! Value
<td>boolean</td>
|-
<td>when '''true''' the rule applies to video media</td></tr>
| internetstream || boolean
 
| when '''true''' the rule applies to internet streams
<tr><td>dvd</td>
|-
<td>boolean</td>
| audio || boolean
<td>when '''true''' the rule applies to DVDs</td></tr>
| when '''true''' the rule applies to audio-only media
 
|-
<tr><td>dvdimage</td>
| video || boolean
<td>boolean</td>
| when '''true''' the rule applies to video media
<td>when '''true''' the rule applies to DVD images (iso)</td></tr>
|-
 
| dvd || boolean
<tr><td>dvdfile</td>
| when '''true''' the rule applies to DVDs
<td>boolean</td>
|-
<td>when '''true''' the rule applies to DVD folder structures</td></tr>
| dvdimage || boolean
 
| when '''true''' the rule applies to DVD images (iso)
<tr><td>protocols</td>
|-
<td>regexp</td>
| dvdfile || boolean
<td>when defined the rule applies to items whose (URI) protocol matches;
| when '''true''' the rule applies to DVD folder structures
as well as "real" protocols like daap, rtv, rtsp XBMC also uses the URI protocol for things like zip, rar etc.</td></tr>
|-
 
| protocols || regexp
<tr><td>filetypes</td>
| when defined the rule applies to items whose (URI) protocol matches;
<td>regexp</td>
as well as "real" protocols like daap, rtv, rtsp XBMC also uses the URI protocol for things like zip, rar etc.
<td>when defined the rule applies to items whose file extension matches</td></tr>
|-
 
| filetypes || regexp
<tr><td>mimetypes</td>
| when defined the rule applies to items whose file extension matches
<td>regexp</td>
|-
<td>when defined the rule applies to items whose mime-type matches</td></tr>
| mimetypes || regexp
 
| when defined the rule applies to items whose mime-type matches
<tr><td>filename</td>
|-
<td>regexp</td>
| filename || regexp
<td>when defined the rule applies to items whose filename matches</td></tr>
| when defined the rule applies to items whose filename matches
 
|-
<tr><td>player</td>
| player || string
<td>string</td>
| the name of the player defined in the <players> section this rule invokes
<td>the name of the player defined in the <players> section this rule invokes</td></tr>
|}
</table>
For the regexp attributes you can specify a like with a |-separator, e.g. '''mkv|avi|divx'''
For the regexp attributes you can specify a like with a |-separator, e.g. '''mkv|avi|divx'''


As of r23190, the following attributes are also available for video items with metadata (a.k.a. flagging)
As of r23190, the following attributes are also available for video items with metadata (a.k.a. flagging)


<table border="1" cellpadding="2" cellspacing="0">
<tr><th>Attribute</th><th>Type</th><th>Value</th></tr>
<tr><td>videocodec</td>
<td>regexp</td>
<td>matched against the video codec so, a rule could used '''xvid|divx|div3|div4|div5''' </td></tr>
<tr><td>videoresolution</td>
<td>regexp</td>
<td>matched against the video resolution, which will be one of '''480''', '''540''', '''720''' or '''1080'''</td></tr>
<tr><td>videoaspect</td>
<td>boolean</td>
<td>matched against the video aspect ratio, which will be one of '''1.33''', '''1.66''', '''1.78''', '''1.85''', '''2.20''' or '''2.35'''</td></tr>
<tr><td>audiocodec</td>
<td>regexp</td>
<td>matched against the audio codec, e.g. '''ac3|dts'''</td></tr>


<tr><td>audiochannels</td>
{| border="1" cellpadding="2" cellspacing="0"
<td>regexp</td>
|-
<td>matched against the number of channels in the audio which will be an integer (i.e. '''6''' rather than '''5.1''')</td></tr>
! Attribute
</table>
! Type
! Value
|-
| videocodec || regexp
| matched against the video codec so, a rule could used '''xvid|divx|div3|div4|div5'''
|-
| 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'''
|-
| audiocodec || regexp
| matched against the audio codec, e.g. '''ac3|dts'''
|-
| audiochannels || regexp
| matched against the number of channels in the audio which will be an integer (i.e. '''6''' rather than '''5.1''')
|}

Revision as of 23:48, 4 October 2011

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.

There are currently two different ways of accessing this functionality. The current method involves the configuration of a playercorefactory.xml file, while people with an older release (9.04 or below) need to edit advancedsettings.xml. The newer method grants more control over the default player for different sources (videos, music, DVDs, etc.) and can add as many external players as needed.

XBMC 9.11 and above

XBMC, since 9.11 (specifically, revision -r20983), 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:

<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>

The <players/> node defines all the different players that you wish to add to XBMC. 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 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.

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, XBMC-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)

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.

hidexbmc false (default)
true
whether to hide the XBMC 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
playcountminimumtime 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 false (default)
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 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. Appended rules will take precedence over default players (i.e. DVDPlayer for video and PAPlayer for audio) but not over XBMCs builtin 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 significant, 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:

<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>

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:


Attribute Type Value
internetstream boolean when true the rule applies to internet streams
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 XBMC 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 a like with a |-separator, e.g. mkv|avi|divx

As of r23190, the following attributes are also available for video items with metadata (a.k.a. flagging)


Attribute Type Value
videocodec regexp divx|div3|div4|div5
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
audiocodec regexp dts
audiochannels regexp matched against the number of channels in the audio which will be an integer (i.e. 6 rather than 5.1)