Existing users who are familiar with SqueezeIR configuration should check the change log in case they need to modify their file to work with the latest version. New users should obtain a copy of the sample file for reference and read on...
SqueezeIR uses an xml configuration file that currently has to be hand-written. The file is unimaginatively called SqueezeIR.xml. Hand-writing xml can seem a little daunting at first but it's quite easy once you get the hang of it. The configuration file follows normal xml syntax which is case sensitive but SqueezeIR only understands the basic xml constructs that it needs so don't try to use CDATA or DTD constructs for example. Comments are supported.
Whenever you modify your SqueezeIR configuration I recommend that:
You use an xml-aware text editor rather than notepad. This will help you spot syntax errors more easily amongst other things.
Use a schema validating service (eg http://www.xmlvalidation.com) to check your xml for errors.
Activate your changes by going to Settings>SqueezeIR>Advanced>Update Configuration.
After activating your changes go to Settings>SqueezeIR>About and check the Configuration Status is 3 (Success).
If you have problems you can install SqueezeIR onto desktop Squeezeplay and look at the log files for a hint at what the problem might be.
The file consists of four sections and a header. The header contains elements that are required by the xml specification and a few other optional elements.
<hotkey> This defines a key combination you can use to quickly enable (by pressing) or disable (by holding) SqueezeIR's handling of the Controller's keys from anywhere in the Controller's menu structure. This is useful for example if you have mapped the volume buttons to control your amplifier but need to change the player's volume now and then. You can disable the hotkey feature simply by removing the line from the file but I strongly recommend leaving it in (you may of course change which key combination is used though).
<minPopupTime> This defines the minimum length of time that SqueezeIR should display its popup screens for in milliseconds. If this item is missing then a default value of 500 ms is used. We'll talk more about popups when we get to <events>.
<homeCaption> This defines the caption to be displayed on the Controller's Extras menu. If this element is missing the active profile's <menu> is used. If the active profile has no <menu> element then SqueezeIR is displayed.
<remotes> This section holds the ir codes that you want to use with SqueezeIR. See below for details.
<profiles> This section maps ir codes in the <remotes> section to the Controller's buttons. See below for details.
<menus> This section allows you to create a menu of ir codes. See below for details.
<IRoIP> This section allows you to define a set of IR codes that may be triggered via a web browser. See below for details.
<players> This section allows you to define a set of IR codes that may be triggered via a change in player state (eg when the player powers on or off). See below for details.
The basic outline of SqueezeIR.xml is shown below:
<?xml version="1.0" encoding="utf-8"?> <!-- DO NOT TOUCH THIS LINE -->
<!--
SqueezeIR Data File
Original filename "SqueezeIR.xml"
For more information see:
http://www.woodbine.me.uk/squeezebox/squeezeir/configure
-->
<!-- DO NOT TOUCH THIS LINE -->
<SqueezeIR version="2.00"
xmlns="http://www.woodbine.me.uk/ns/squeezeir"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.woodbine.me.uk/ns/squeezeir
http://www.woodbine.me.uk/squeezebox/squeezeir/files/SqueezeIR.xsd">
<!--
Hotkey allows you to quickly enable (by pressing) or disable (by holding) SqueezeIR's handling of the Controller's keys
-->
<hotkey>HOTKEY</hotkey>
<!--
show all popups for at least 0.5s (longer if necessary depending on event duration)
-->
<minPopupTime>500</minPopupTime>
<!--
Key combinations can be named for easier reference later in the file
-->
<keyNames>
<keyName ID="GO">1</keyName>
<keyName ID="HOME">64</keyName>
<keyName ID="FWD">2048</keyName>
<keyName ID="REW">1024</keyName>
<keyName ID="BACK">2</keyName>
<keyName ID="PLAY">128</keyName>
<keyName ID="PAUSE">512</keyName>
<keyName ID="VOLUME_UP">4096</keyName>
<keyName ID="VOLUME_DOWN">8192</keyName>
<keyName ID="ADD">256</keyName>
<keyName ID="VOLUME_MUTE">12288</keyName> <!-- VOLUMEUP | VOLUMEDOWN -->
<keyName ID="PREVIOUS">1536</keyName> <!-- PAUSE | REW -->
<keyName ID="NEXT">2560</keyName> <!-- PAUSE | FWD -->
<keyName ID="STOP">3072</keyName> <!-- REW | FWD -->
<keyName ID="HOTKEY">384</keyName> <!-- PLAY | ADD -->
<keyName ID="LAUNCH">66</keyName> <!-- HOME | BACK -->
</keyNames>
<!--
IR commands are defined here and can be protocol parameters or references to lirc files.
Commands are mapped to friendly names for easier reference later on.
-->
<remotes>
<!-- Your data here. -->
</remotes>
<!--
profiles map the Controller's physical keys to the remote commands and also indicate which SqueezeIR menu is shown first.
The active profile is the one linked to the currently active menu, active player, or the default profile.
-->
<profiles>
<profile ID="{none}"/> <!-- empty profile to be set as the default so that SqueezeIR is disabled when not connected to any players -->
<!-- Your data here. -->
</profiles>
<menus>
<menu ID="_SETTINGS"/> <!-- Reserved menu for SqueezeIR settings. -->
<!-- Your data here. -->
</menus>
<players>
<player ID="MY_PLAYER"/> <!-- the name of your player. -->
<playerEvents>
<playerEvent ID="power=true"> <!-- respond when the player is turned on. -->
<!-- actions go here -->
</playerEvent>
<playerEvent ID="mode=play"> <!-- respond when the player starts playing. -->
<!-- actions go here -->
</playerEvent>
</playerEvents>
</player>
</players>
<!--
IRoIP IPevents are triggered from a web browser and are similar to normal events
except the the event ID is a descriptive name (rather then PRESS, HOLD or ALL as with regular events
and that some elements are meaningless (eg override, target, count)
-->
<IRoIP>
<port>8174</port> <!-- 8174 is the default port so this line is optional -->
<IPevents>
<!-- Your data here. -->
</IPevents>
</IRoIP>
</SqueezeIR> <!-- DO NOT TOUCH THIS LINE -->
This section allows you to give useful names to the various Squeezebox keycode constants which you can then use later on in other parts of SqueezeIR.xml to make it easier to read. The section contains one or more <keyName> elements that have an ID attribute (your chosen name) and a value (the SqueezeIR keycode). See the Appendix for a list of the KeyCodes.
NB: Punctuation characters cannot be used in keyName ID's.
<keyNames>
<keyName ID="BACK">2</keyName>
</keyNames>
This section contains one or more <remote> sections that define the actual ir codes that you want to use with SqueezeIR. You can have as many <remote> sections as you like but each must have a unique ID attribute. The exact structure of a <remote> section depends on the protocol that your equipment uses to encode its ir codes for transmission but it typically contains the following elements:
<protocol> This tells SqueezeIR how the codes should be encoded and transmitted. This element is manditory. The protocols page has details about each of the protocols that are supported by SqueezeIR.
<parameters> Containing one or more <parameter> elements. These contain the parts of the ir codes that are constant accross all commands for the remote. The number and ID of the <parameter> elements vary depending on the value of <protocol>.
<commands> Containing one or more <command> sections. Each <command> section must have a unique ID attribute and must also have a <value> element that contains the variable part of each ir code. A <command> section may also include its own <parameters> section that is merged with the one in the remote. This is useful if you have the odd command that is slightly different from the others in the <remote>.
The globally unique combination of <remote ID> and <command ID> is how the ir codes are referenced by <action> elements in the rest of the file. An annotated example of a <remotes> section using NEC protocol is shown below:
<remotes>
<remote ID="sample remote">
<protocol>NEC</protocol> <parameters>
<parameter ID="DEVICE">150</parameter>
<parameter ID="SUBDEVICE">105</parameter>
</parameters>
<commands>
<!-- below are two "normal" commands that inherit all their parameters from the remote. -->
<command ID="VOLUME_UP"><value>14</value></command>
<command ID="VOLUME_DOWN"><value>15</value></command>
<!-- this one modifies SUBDEVICE and adds TYPE. The remote's DEVICE parameter still applies. -->
<command ID="POWER">
<parameters>
<parameter ID="SUBDEVICE">200</parameter>
<parameter ID="TYPE">X</parameter>
</parameters>
<value>15</value>
</command>
</commands>
</remote>
<remote ID="another sample remote">
<!-- and so on... -->
</remote>
</remotes>
<actions> Contain one or more <action> elements. Each <action> represents a single ir code (as defined in the <remotes> section) that is sent by SqueezeIR as well as a few other elements that modify the code's behaviour. They have a numeric order attribute that SqueezeIR uses to ensure the contents of <actions> is sent in the correct sequence. An <action> contains:
<remote> This is manditory and must have a value that matches the ID of one of your <remote> structures in the <remotes> section.
<command> This is manditory and must have a value that matches the ID of one of your <command> structures in the <remote>, or a command name in the remote's LIRC file.
<pause> Optional numeric value to instruct SqueezeIR to wait before sending the <command>. Each unit represents about 200 milliseconds (so 5 = 1 second). This is useful, for example, if you want to turn your amp on and set it to the correct input in one go but need to put a delay into the procedure to allow time for your amp to wake up. The default is 0.
<count> Optional numeric value to instruct SqueezeIR to repeat the <action> (including the <pause>) before moving onto the next one. The defalut is 0.
Here's an example (using the above <remotes> section) that turns the device on, waits about one second, and then turns the volume up by five notches:
<actions>
<action order="1">
<remote>sample remote</remote>
<command>power</command>
</action>
<!-- we only want the pause to happen once so we have to split the volume change into two actions -->
<action order="2">
<remote>sample remote</remote>
<command>volume_up</command>
<pause>5</pause>
</action>
<action order="3">
<remote>sample remote</remote>
<command>volume_up</command>
<count>4</count>
</action>
</actions>
<events> Contain a maximum of two <event> structures. An <event> is the basic unit of functionality within SqueezeIR. Each <event> section has an ID attribute which determines when it is executed and may be either PRESS, HOLD, or ALL. The ID corresponds to how the physical buttons of the Controller are pressed; ALL is a shortcut to apply the same <event> to both PRESS and HOLD. This is useful for the volume buttons where you would normally want them to do the same thing no matter how they are pressed. You cannot use ALL with any other <event> in the same <events> section. An <event> contains your <actions> as well as some other elements that modify how the <actions> section is executed:
<actions> This contains the list of <action> elements that are to be executed by the <event>.
<modifier> Optional element that can take the values ONCE, ALL, or LAST. For an <event> that is executed by holding a button on the Controller, this determines whether the <event> is repeated continuously until the key is released (either in its entirity (ALL), or only the final action (LAST)), or whether it is only sent once (ONCE). This element is ignored for events triggered by pressing a button on the Controller. The default is ALL.
<sound> Optional boolean that determines whether SqueezeIR should make a noise when the <event> is executed. This is sometimes useful for HOLD events with the ONCE <modifier>. The default is FALSE.
<count> Optional numeric value to instruct SqueezeIR to repeat the <event> in its entirity. This is sometimes useful for HOLD events with the ONCE <modifier>. The default is 0.
<override> Optional boolean. If this is FALSE then SqueezeIR will execute the <event> as well as the Controller's normal function. If it is TRUE then the normal Controller function is disabled and only the SquuezeIR event is triggered. The default is FALSE. This element is not needed for an <event> inside a menu's <item> section.
<playerActions> This contains a list of <playerAction> elements which, like an <action>, have a numeric order attribute. A <playerAction> has a SqueezePlay command as it's value and can be used to perform non-SqueezeIR related tasks upon completion of the <actions>. A list of the available SqueezePlay commands that can be used as values for <playerAction> is in the appendix although not all of them will be useful. SqueezeIR passes the <playerAction> values to SqueezePlay without any validation so they must be typed exactly as documented.
<target> Optional string that instructs SqueezeIR to enter one of your menus after executing the <event>. The menu is opened after the <actions> and <playerAction> commands have been processed. If <target> is missing then no <menu> is opened. There is a special value (_SETTINGS) that can be used to open the SqueezeIR settings page. We'll talk about how to define menus in SqueezeIR later.
<wait> Optional boolean that determines whether SqueezeIR should wait until all the <actions> are completed before executing the <playerAction> and <target> elements of the <event>. If set to TRUE (the default), SqueezeIR will wait, if set to FALSE then the <playerActions> and <target> will be processed upon releasing the Controller's button which may be before all of the <actions> have been completed.
<popup> Optional string to allow you to display messages when an event is activated. This is useful for events that take a long time to be processed as the popup menu will be shown until the event is finished. The popup will be shown for <minPopupTime> or until the event is finished, whichever is the longer. Tab characters are stripped from the popup text before it is displayed so you can keep your xml looking neat and tidy. Don't make your popup text too long or it won't fit on the screen!
<minPopupTime> Optional element to override the global setting in the header part of SqueezeIR.xml on a per event basis.
NB: The combination of <popup> and <override>FALSE</override> should not be used with the Controller's volume buttons as they have their own popup screen.
Let's take a look at some <events> (with the individual <action> elements omitted for brevity):
<!-- we can use the PRESS and/or HOLD event IDs -->
<events>
<!-- when the key is pressed the ir codes are sent instead of the default function -->
<event ID="PRESS">
<override>TRUE</override>
<actions>
<!-- the action elements go here -->
</actions>
</event>
<!-- when held the controller plays a sound and moves to the "my menu" SqueezeIR menu -->
<!-- the connected player is stopped and powered off -->
<event ID="HOLD">
<modifier>ONCE</modifier>
<sound>TRUE</sound>
<target>my menu</target>
<minPopupTime>5000</minPopupTime> <!-- show the popup for at least 5s -->
<popup>
this is a
long popup
with line breaks
</popup>
<playerActions>
<playerAction order="1">stop</playerAction>
<playerAction order="2">power</playerAction>
</playerActions>
</event>
</events>
<!-- OR we can use the HOLD event ID -->
<events>
<!-- the ir codes are sent (once if pressed, repeatedly if held) instead of the default function -->
<event ID="ALL">
<override>TRUE</override>
<actions>
<!-- the action elements go here -->
</actions>
</event>
</events>
The <profiles> section can contain any number of <profile> sections which define what the physical keys on the Controller do. Like a <remote>, each <profile> has a unique ID attribue. You can switch between your profiles using the SqueezeIR settings screen or, if you give them the same ID as your players' names and enable the Use Player Profiles setting, they will automatically be activated when you connect the Controller to that player. This is useful if you have one Controller but several players because as you move between your players SqueezeIR will select the correct <profile> for you. A <profile> contains:
<keys> This section contains any number of <key> sections. The <key> sections define what happens when you press a button on the Controller. Each <key> section has an ID attribute which is either a numeric SqueezePlay KeyCode, or a SqueezeIR KeyName). A <key> contains an <events> section that defines what action should be taken.
<menuEvent> This section defines what the Controller should do when you select SqueezeIR from your Extra's screen. The <menuEvent> is a special case of an <event> structure, the difference being that a <menuEvent> does not have an ID attribute whereas a regular <event> does.
<homeCaption> Optional element to override the global setting in the header part of SqueezeIR.xml when the profile is active.
Let's have a look at an example of how to build a <profiles> section (with the events omitted for brevity):
<profiles>
<profile ID="sample profile">
<homeCaption>My Stereo</homeCaption> <!-- Displayed on Extras menu when profile is active -->
<menuEvent> <!-- ...and fire this event -->
<!-- event defining what to do when navigating to Extras..SqueezeIR -->
</menuEvent>
<keys>
<key ID="volume_up">
<events>
<event ID="press">
<!-- event defining what to do when volume up is pressed -->
</event>
<event ID="hold">
<!-- event defining what to do when volume up is held -->
</event>
</events>
</key>
<key ID="volume_down">
<events>
<event ID="all">
<!-- event defining what to do when volume down is pressed or held -->
</event>
</events>
</key>
</keys>
</profile>
<profile ID="another sample profile">
<!-- and so on... -->
</profile>
</profiles>
The <menus> section allows you to create your own heirarchies of menu screens that you can use to send ir codes from. They are very useful for accessing codes that don't naturally fit on any of the Controller's physical buttons or if you have more codes than there are buttons. The <menus> section contains any number of <menu> structures which represent an individual on-screen menu. Each <menu> has a unique ID attribute and can contain:
<profile> Optional element that determines which profile is in effect when in the menu. If omitted then the currently active profile remains unchanged.
<screensaver> Optional boolean element that determines whether the Controller's screen-saver is enabled when in the menu. The default is TRUE.
<keys> This optional section takes the same form as the <keys> section in a <profile>. It's contents are merged with the <keys> of the active profile which can be useful if you want to change what the buttons do on a per-menu basis.
<items> This section contains one or more <item> sections that represent the options on the menu. An <item> has a numeric order attribute that governs the position of the item in the menu, and a <caption> element that defines the on-screen text. An <item> also contains an <events> section that is executed when the menu item is highlighted and Go is pressed or held. The <override> element of an <event> inside an <item> section is not needed as the menu is the default Controller action.
Here's an example <menus> section that defines one menu with two entries (with the events omitted for brevity):
<menus>
<menu ID="sample menu">
<profile>sample profile</profile>
<screensaver>FALSE</screensaver>
<keys>
<key ID="home">
<!-- as for a key in a profile -->
</key>
</keys>
<items>
<item order="1">
<caption>send an ir code</caption>
<events>
<!-- event items defining what to do when this option is selected -->
</events>
</item>
<item order="2">
<caption>send another ir code</caption>
<events>
<!-- event items defining what to do when this option is selected -->
</events>
</item>
</items>
</menu>
<menu ID="another sample menu">
<!-- and so on... -->
</menu>
</menus>
The <players> section allows you to define a set of <playerEvents> for one or more players that are triggered when the player does something. A <playerEvent> has the same structure as a "normal" <event> (we've already covered those!) with the exception that the ID is a descriptive name of the event rather than simply PRESS, HOLD, or ALL. Supported actions to use as the ID are "power=true", "power=false", "mode=play", "mode=stop", "mode=pause".
The <IRoIP> section allows you to define a set of <IPevents> that can be triggered from a web browser. An <IPevent> has the same structure as a "normal" <event> (we've already covered those!) with the exception that the ID is a descriptive name of the event rather than simply PRESS, HOLD, or ALL. This section also has an optional <port> element that defines which IP port SqueezeIR is listening on. If the <port> element is missing the the default port of 8174 is used. Let's look at how that works in practice:
<IRoIP>
<port>1234</port>
<IPevents>
<IPevent ID="event 1">
<!-- actions go here as for normal events -->
</IPevent>
<IPevent ID="event 2">
<!-- ...and so on -->
</IPevent>
</IPevents>
</IRoIP>
Now that you've done all the hard work, just go to Settings>SqueezeIR>Advanced>Update Configuration to load your changes into SqueezeIR and then go to Settings>SqueezeIR>IR-o-IP and ensure the Enabled option is selected (IR-o-IP is disabled by default as it does place a bit of a strain on the Controller's modest computing power). Also, while in the IR-o-IP screen make a note of the IP address & port and of your PIN. Now, if you go to a web browser and type in http://<IP address>:<port>/menu?pin=<pin> (eg http://127.0.0.1:8174/menu?pin=1234) you should see a simple web page listing your IPevents. Click on them and SqueezeIR should send the IR codes. The numbers to the right of the IP event names allow you to send a command multiple times (useful for volume control).
HINT: You will probably want to create a DHCP reservation on your router for your controller so that the Controller's IP address does not change. You will also want to create a bookmark for the IR-over-IP menu.
That's all the theory out of the way so let's put it all together. The following simple example controls an imaginary amplifier that uses the NECX protocol. It has a profile that uses the volume buttons to change the amplifier's volume instead of the player's and maps holding the Home button to turn the amplifier on and off. It also creates a menu for input selection:
<?xml version="1.0" encoding="utf-8"?> <!-- DO NOT TOUCH THIS LINE -->
<SqueezeIR version="2.00"
xmlns="http://www.woodbine.me.uk/ns/squeezeir"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.woodbine.me.uk/ns/squeezeir
http://www.woodbine.me.uk/squeezebox/squeezeir/files/SqueezeIR.xsd">
<!-- Hotkey allows you to quickly enable (by pressing) or disable (by holding SqueezeIR's handling of the Controller's keys -->
<hotkey>HOTKEY</hotkey>
<!-- show all popups for at least 0.5s (longer if necessary depending on event duration) -->
<minPopupTime>500</minPopupTime>
<!-- Key combinations can be named for easier reference later in the file -->
<keyNames>
<keyName ID="GO">1</keyName>
<keyName ID="HOME">64</keyName>
<keyName ID="FWD">2048</keyName>
<keyName ID="REW">1024</keyName>
<keyName ID="BACK">2</keyName>
<keyName ID="PLAY">128</keyName>
<keyName ID="PAUSE">512</keyName>
<keyName ID="VOLUME_UP">4096</keyName>
<keyName ID="VOLUME_DOWN">8192</keyName>
<keyName ID="ADD">256</keyName>
<keyName ID="VOLUME_MUTE">12288</keyName> <!-- VOLUMEUP | VOLUMEDOWN -->
<keyName ID="PREVIOUS">1536</keyName> <!-- PAUSE | REW -->
<keyName ID="NEXT">2560</keyName> <!-- PAUSE | FWD -->
<keyName ID="STOP">3072</keyName> <!-- REW | FWD -->
<keyName ID="HOTKEY">384</keyName> <!-- PLAY | ADD -->
<keyName ID="LAUNCH">66</keyName> <!-- HOME | BACK -->
</keyNames>
<remotes>
<remote ID="AMP">
<protocol>NEC</protocol>
<parameters>
<parameter ID="device">12</parameter>
<parameter ID="type">X</parameter>
</parameters>
<commands>
<command ID="VOL_UP">
<value>1</value>
</command>
<command ID="VOL_DOWN">
<value>2</value>
</command>
<command ID="POWER">
<value>3</value>
</command>
<command ID="INPUT_CD">
<value>18</value>
</command>
<command ID="INPUT_TAPE">
<value>19</value>
</command>
</commands>
</remote>
</remotes>
<profiles>
<profile ID="Lounge">
<menuEvent>
<target>Input Select</target>
</menuEvent>
<keys>
<key ID="VOLUME_UP">
<events>
<event ID="ALL">
<override>TRUE</override>
<actions>
<action order="1">
<remote>AMP</remote>
<command>VOL_UP</command>
</action>
</actions>
</event>
</events>
</key>
<key ID="VOLUME_DOWN">
<events>
<event ID="ALL">
<override>TRUE</override>
<actions>
<action order="1">
<remote>AMP</remote>
<command>VOL_DOWN</command>
</action>
</actions>
</event>
</events>
</key>
<key ID="HOME">
<events>
<event ID="HOLD">
<override>TRUE</override>
<actions>
<action order="1">
<remote>AMP</remote>
<command>POWER</command>
</action>
</actions>
</event>
</events>
</key>
</keys>
</profile>
</profiles>
<menus>
<menu ID="Input Select">
<items>
<item order="1">
<caption>Tape</caption>
<events>
<event ID="PRESS">
<actions>
<action order="1">
<remote>AMP</remote>
<command>INPUT_TAPE</command>
</action>
</actions>
<playerActions>
<playerAction order="1">back</playerAction>
</playerActions>
</event>
</events>
</item>
<item order="2">
<caption>CD Player</caption>
<events>
<event ID="PRESS">
<actions>
<action order="1">
<remote>AMP</remote>
<command>INPUT_CD</command>
</action>
</actions>
<playerActions>
<playerAction order="1">back</playerAction>
</playerActions>
</event>
</events>
</item>
</items>
</menu>
</menus>
</SqueezeIR> <!-- DO NOT TUCH THIS LINE -->