Skip to content
a3728be Mar 30, 2011
392 lines (336 sloc) 18 KB
This document will try and describe how to construct channel files for the channel plugin
to PMS.
Bundled with the plugin there are some channels already but the .ch files are perhaps not that
human friendly to read so a quick guide to the structure of the files will be given here.
General note!
* The parser is extremely forgiving for unknown and misspelled keywords. At best it will inform
you that there is something wrong by logging it, but most of the time it will probably just
ignore the faulty word and continue.
* The files are line based. It is not possible to split long configurations on more lines then
one since the parser reads one line at a time.
* If a line starts (after removing leading whitespace chars like space and tab) is #
that line is removed. This is used for comments. NOTE! That you can only have complete lines
as comments. You can't have the # at the end or in the middle of a line, if a # is placed
anywhere else then first on the line it is considered to be part of the line.
* Empty lines are simply ignored
Textual conventions
The following textual conventions are used in this document.
* <xxx> is an indication that some user defined text should be placed there. The <> should not
be part of the string (unless you want them to be part of it).
* [xxx] is an indication that the text is optional, again the [] should be removed.
*[<xxx>] is thus an indication an optional user defined text.
* xxx|yyy means that either xxx or yyy is allowed, other values are ignored.
* Text without <> are keywords and must be written exactly as in this document.
* Keywords are not case sensitive (all other text is).
* The words keyword and tag will be used in this document to represent the same thing.
High level file structure
The channels that the plugin will display are placed in "channel files" (or .ch files).
The plugin is configured with a path where it will read (and parse) all .ch files it finds in
that directory. This allows you do separate the channels in to smaller files which are easier
to debug and read. There is however nothing that prevents you from have more than one channel
per .ch file.
The .ch file should follow the following structure:
[version=<ver tag>]
channel <channelname> {
<channel block>
macrodef <macroname> {
<macro block>
scriptdef <scriptname> {
<script block>
At the top level there are four (4) configuration elements (version,macrodef,scriptdef,channel).
These elements does not need to come in any specific order and there are no limit to how many
times they can be present within a file. However, a channel and a macro can only be defined one
time (that is the channelname and macroname can only be used once) and if it is defined again
it will update the old definition. A script can only be defiened once and it is redefined the second
definition will be ignored.
Version tag
Each .ch file can contain a version tag. The version tag is a string that is used by the plugin
to be displayed in the PMS log when the .ch file is parsed. It is not used by the plugin in any
other way and should be used as a debug aid for the user to see that it is the correct version
of the file that has been loaded. A good practice is to set the version at the top of the file.
Channel definition
A channel is the top most entity you can configure that will be seen on the XMB (under the
"Channels" folder). The channel definition structure:
channel <name> {
[img=<url to image>]
<block def, see below>
The channel name MUST be unique. If the same channel is configured more than once the "last"
configuration will be the one that is the one that is used.
The channel has two (2) properties that can be set.
* format is the format of the data that this channel contains. Can be "audio" or "video",
the default value is video.
* The img tag is an URL to a nice image that represents the channel. This will be distributed
by the PMS as thumbnail for the channel.
* There must be at least on block definition (or macro usage) in the channel.
Macro definition
Macros are configuration that you probably need to use more than once in your file and you don't
want to copy it to much. A macro is just there to make the .ch file become more readable. A macro
could be defined anywhere in the file and used anywhere in the file. The macros are however bound
to one .ch file. This means that as soon as on .ch file has been completely processed all macros
that were defined in it will be forgotten. Thus, if a macro should be used for more then one channel
the channels and the macro must be placed in the same .ch file.
The macro definition structure:
macrodef <name> {
<block def, see below>
Script definition
Script is used when you need to have more advanced parsing of the pages to find the media stream.
Scripts are globally defined and not bound to a specific .ch file. This gives you the possibility
to have your scripts in separate file(s). As soon as a script with a name has been defined that
name is occupied and if you use the same name in another script definition that definition will
be ignored.
The script block is a NIPL src with some limitations.
The script definition structure:
scriptdef <name> {
<NIPL src, see below>
Block definition
The block definition defines the folder structure for the channel. That is how the channel
is divided in folders and where it finds the media etc. All blocks follow the same skeleton
structure that can be stated as:
block keyword {
block parameters
more blocks
The block parameters don't have to come first in the block but it is a good practice to place them
first. There is no order between the parameters.
There are three type of blocks defined:
folder,item and media.
Folder definition
A folder is well a folder. It contains other folders and/or media. The folder definition:
folder {
[name=<name string>]
[matcher=<match expression>]
[url=<url to fetch page from>]
[order=<see order def, below>]
[macro=<name of macro>]
[folder {}]
[item {}]
[media {}]
The parameters for a folder are:
* name - a descriptive name of the folder. Not needed for normal folder since the name should
come from the matching.
* matcher - a regular expression matching out entries from the channel. See the matching section
below for details.
* order - the order of how things are matched. See the matching section.
* url - the base url of the folder.
* type - type of folder. Defaults to normal.
* ATZ gives folders named A-Z and then sorts all matches on the page according to starting
* ATZLink similar to ATZ but with the difference that the A-Z objects are
not found on a single page but already sorted. The plugin will append
the letters A-Z to the URL. For example if
url= then the plugin will search for data
under, etc.
* empty - the folder is just a placeholder for retrieving the next url.
* recurse - A recursive folder which uses the parent folders matches again.
This is the way to parse pages that are splitted.
* normal - a normal folder.
* navix - a NaviX folder see NaviX on wiki
* prop - special properties for the folder. See the properties section.
* macro - use the macro with the specified name. This means that the macro definition
in reality is pasted in place of the macro line.
Item definition
Items are objects which holds media. Normally they are simple palceholders but they can
hold substantial data as well.
The item definition:
item {
[name=<name string>]
[matcher=<match expression>]
[url=<url to fetch page from>]
[order=<see order def, below>]
[macro=<name of macro>]
[media {}]
NOTE! That an item can only hold media and not other items or folder.
The parameters of items have the same meaning as those of folders.
Media definition
Media is the end result of the channel. This is the actual media stream that will be played.
The media definition
media {
[name=<name string>]
matcher=<match expression>
url=<url to fetch page from>
[order=<see order def, below>]
[macro=<name of macro>]
[script=<script name>]
[nscript=<script url>]
[escript=<script path>]
The parameters of media has the same meaning as those of item and folder. The type parameter can
be set to asx to indicate that the media stream found is an asx file which needs some special
treatment by the plugin.
NOTE!! It is possible to define static media. In this case either url or matcher should be specified.
If the matcher is defined it is used.
* script - uses the script to retrive the actual media url. Only one script can be configured
per media.
* nscript - uses the remote script (which should be an NIPL processor) to retrive the actual
media url.
* escript - external script that is executed from within the plugin. The script is called with two (2)
arguments the url and the format. The script should write the new scraped url on stdout and then exit.
* format - overrides the channels defined format
The whole purpose of the plugin is to present the web based channels (like SVTPlay) and allow
you browse the programs and finally play the media. This is done via some matching on the various
web pages that the play channel provides. This matching is done using regexps. If you need
to brush up your regexp skills go to google and do some searching.
The matcher parameter contains the regexp used to match out the relevant data for a particular
object (folder,item,media). The matching can produce three types of information to the plugin:
url,name and thumbnail. At a minimum a url must be produced, the name and the thumbnail picture
can be excluded. A name is normally also needed since it is hard to find the show you want
if all have no name. This production of data is used regexp "groups" (="()"). Which group in
a match expression that is the url,name or thumb is controlled by the order parameter.
The order is a comma separated list with the names name,url,thumb (for rtmp streams the keywords
playpath and sfwVfy can also be matched)in the correct order and
combination. A keyword can occur more than once and if that is the case it will be concatenated
with the rest of the same sort.
The matched url is then concatenated with the url parameter to produce a url which corresponds
to the next page where new matches will be made.
matcher=<a href=\"([^\"]+)\">([^<]+)</a>
This is a very normal matcher. It matches expressions of form <a href="xxxx">yyyy</a>. It
produces two results the first (=xxxx) will be the url part and the second (=yyyy) is the
name. The matched url (=xxxx) will then be appended to the url parameter and the resulting url
(= will be used for the next object as start page. A folder
(or item or media) will be visible on the XMB with the name yyyy.
If the last object in the order list ends with a "+" sign (for example name+) it means that all
the remaining matched groups are of that type.
matcher=<a href=\"([^\"]+)\">([^<]+)</a>\<\"([^\"]+)\"
If the url parameter is left out the matched url part (=xxxx in the example) is considered to
be a full url.
Each object (=folder,item or media) can have some extra properties set to them. The properties
are added (just like order) as a comma separated list. Some properties have a value which
is then specified as <proerty name>=<property value>. The value part is left out for many
properties. The list of properties:
* url_separator
These three properties all take a value (that is =<value>) and this controls what should be used
when concatenating multiple matched parts of theat type. For example name_separator=: means
that if we have two matched groups for name, say a and b, the resulting name will be a:b.
* auto_media: The item equivalent of an empty folder. This means that the item will autamtically
fetch the next page which the should contain the media.
* prepend_url
If a value is given the value will be prepended to the matched data (url,name or thumb).
* append_url
If a value is given the value will be appended to the matched data (url,name or thumb).
* concat_name: If the value is "rear" append the name to the matched name. If "front" prepend the name
to the matched name.
* ignore_name: If a name parameter is given it will be used in stead of the matched one. This
will also be the case when no name match is found.
* use_conf_thumb: If a thumb url is configured it will be used instead of a matched one.
* other_string: Used for ATZLink to set the "other" folder string. By default this is "#".
* continue_url
A regular expression that if it matches the object (name or url) instructs the plugin to
automatically "opens" the folder that should have been displayed.
* continue_limit:
The number of folders that can be opened by the continue_name or continue_url.
* only_first:
Stop matching after the first match has been found on a page.
* prepend_parenturl:
Prepends the URL of the parent to the match.
* peek:
Only valid on folders. If set th plugin will peek into the subfolders and if the subfolders is
empty it will not be added.
NIPL src
The NIPL src of the script block follows with the following
* report and report_val are not used. It is possible to add a report statement to the script
but it will be used the same way as a play.
* Only v2 scripts are allowed.
RTMP stash
Some rtmp streams needs to be played by rtmpdump by the use of the -y(=playpath) or -W(=sfwVfy) option.
To solve this issue use the keyword put=<key>=<val>, where key is playpath or sfwCfy respectively and
val is the string needed.
Sample file
1. version=0.1
2. channel SVTPlay {
3. img=
4. folder {
5. name=A-Z
6. type=ATZ
7. url=
8. folder {
9. matcher=<a href=\"(/t/.*)\">(.*)</a>
10. order=url,name
11. url=
12. item {
13. url=
14. matcher=<a href=\"(/v/.*)\?.*\" title=\"(.*)\" .*?>[^<]*<img class=\"thumbnail\" src=\"([^\"]+)\"
15. order=url,name,thumb
16. prop=auto_media
17. media {
18. matcher=url:(rtmp.*),bitrate:2400
19. }
20. }
21. }
22. }
23. }
The number on the left hand side should not be there and are just ther to make it simple to
walktrough the file in this explanation.
Line 1. A simple version line, the version is 0.1 here.
Line 2. We start defining a channel with the name SVTPlay.
Line 3. We set an img URL which shows some nice picture.
(Note that no format is set so it will be video by default)
Line 4. Start defineing a folder, this will be on the top level.
Line 5. The folder name is A-Z
Line 6. This is an A to Z folder and the plugin will insert the A-Z folders and sort
the matched dat in the correct folder.
Line 7. The URL where this folder should fetch it's pag from is set here.
Line 8-20. Defines a subfolder.
Line 9-10. We matches an url and a name. If this is found on the page:
<a href="/t/102532/a-ekonomi">A-ekonomi</a>
Then the matched url is /t/102532/a-ekonomi and the matched name is A-ekonomi.
Line 11. The url part for the match is set here. When combined with the matched url the
resulting URL will be
Line 13-20. Define an item.
Line 14. A matcher that produces an url a name and a thumbnail. The matched url will be of
form /v/xxxx and a resulting URL will be
Line 16. The proerty auto_media is used to indicate that this item is just placeholder were
the real media stream url is found.
Line 17-19. Defines a media.
Line 18. This will produce a full rtmp:// url. Since SVTPly has more then one rtmp-stream
per program we add some matching to only select on (the one with the best bitrate).
Line 19-23. Just end }
Hopefully you can now make your own .ch files (or modify the existing once). If you do there
are most likely other people that wants to view that channel as well so please publish your
channel files on the PMS forum.
Something went wrong with that request. Please try again.