airLCD

Example Configurations

The airLCD Config File

Hopefully I shall get a LCD display designer written soon, which will write the config files. Until then the following information describes how a config file is made up. A commented airlcd.xml file is included in the distribution.

General

These are system wide settings.

• Version - The version of airLCD that this XML file belongs to. airLCD will only read files that match its version.
• Sleep - How long to pause for each cycle to read LIRC commands. Time in micro seconds. 1000 = 0.001s. Vary this for how responsive you want airLCD to be. Best to get it as low as possible. Timings will vary depending on your hardware. My setting is 100.

<Version>0.1</Version>
<Sleep>1000</Sleep>

Amarok

The following two options are very useful when you start amarok outside of KDE and it takes a little while to get all the KDE hooks up and running. They give us a bit of breathing space before quitting.

• DCOPAttempts - How many times to try attaching to the DCOP server (the messaging system Amarok uses to talk to us)
• DCOPTimeout - How long in seconds to wait between attempts

<DCOPAttempts>3</DCOPAttempts>
<DCOPTimeout>10</DCOPTimeout>

LIRC

• ConfigFile - The location of the lirc->airLCD command file (example one included)

<ConfigFile>/etc/lircrc.conf</ConfigFile>

LCDproc

This is the main user configurable section. Here you can set up your display to show the information that you want.

• Server - The server name (most likely the machine you are running airLCD on)
• Port - The LCDproc port
• Width - Width of the display
• Height - Height of the display
• ClientName - The name of the client (must be unique)
• Screen - A screen section. You can have as many of these as you want. They will cycle after the specified interval

<Server>localhost</Server>
<Port>13666</Port>
<Width>40</Width>
<Height>4</Height>
<ClientName>airlcd</ClientName>
<Screen></Screen>

Screen

The Screen sections appear under the LCDproc section. Screens contain widgets (see below) which display any information you want. You can have as many screens as you want and they can display the same information if required. They rotate with a specified duration, and will cycle in the order they appear in the configuration file.

• Name - Each screen must have a unique name
• Width - The width of the screen
• Height - The height of the screen
• Priority - The priority of the screen. foreground it normal. info is also valid, but will not show if there are other foreground screens. So don't change unless you need to.
• Duration - How long screen should be visible for (only valid if more than 1 screen). Time is in 8th of a second, so 80 = 10s
• Heartbeat - Do you want the annoying LCDproc heartbeat in the upper right?
• Widget - A widget for your screen. These come in the following flavours: string, scroller, horizontal, vertical and combo bars

<Name>main</Name>
<Width>40</Width>
<Height>4</Height>
<Priority>foreground</Priority>
<Duration>80</Duration>
<Heartbeat>off</Heartbeat>
<Widget></Widget>

Widget

The Widget sections occur under Screen sections in the LCDproc section. Widgets come in five flavours: string, scroller, horizontal, vertical and combo bars. Some widget names are reserved for the use of displaying information from Amarok. These names are listed below. If you try and set a widget with a parameter it doesn't take it will be ignored, also if you miss off a parameter that is required it will use a default value.

A String Widget

String widgets display a single line text string. It will be aligned as specified unless the text it too long, then it will be left aligned and cropped on the right.

• Name - The unique name of the widget.
• Type (string)- The type of widget
• X - The location of it's left side
• Y - The location of its top line
• Width - How wide it is
• Align (left, right, center) - How should the text be aligned?
• Text - Any text you want displayed in this widget. It will get overwritten if it is a reserved name by responses from Amarok.

<Name>currentTime</Name>
<Type>string</Type>
<X>10</X>
<Y>2</Y>
<Width>6</Width>
<Align>right</Align>
<Text>00:00</Text>

A Scroller Widget

Scroller Widgets will display text strings aligned as specified, but if the string is longer than the width of the text will scroll in the specified manner. A user defined separator string will be inserted at the end to distinguish the beginning and the end.

• Name - The unique name of the widget (unique to the screen at least).
• Type (scroller) - The type of widget
• X - The location of it's left side
• Y - The location of its top line
• Width - How wide it is
• Height - How many lines it should span (1 is normal, unless you know you will have multi-line text
• Align (left, right, center) - How should the text on each line be aligned?
• Move (horizontal, vertical, marquee)- The movement type of the scroller. horizontal or vertical bounce or (loop around).
• Speed - How fast. Increase for slower movement
• ScrollSeparator - If using marquee what characters do you want to separate the end from the beginning?
• Text - Any text you want displayed in this widget. It will get overwritten if it is a reserved name by responses from Amarok.

<Name>artist</Name>
<Type>scroller</Type>
<X>1</X>
<Y>1</Y>
<Width>34</Width>
<Height>1</Height>
<Align>center</Align>
<Move>marquee</Move>
<Speed>5</Speed>
<ScrollSeparator>--</ScrollSeparator>
<Text>Welcome to airLCD</Text>

A Vertical Bar Widget

A vertical bar widget. These start from the bottom and increase in size upwards.

• Name - The unique name of the widget.
• Type (vbar)- The type of widget
• X - The location along the width of the LCD
• Y - The bottom of the bar
• Height - The max height of the bar (how many lines will it go over)
• Percent (0-100) - What percentage of the bar do you want filled initially?

<Name>score</Name>
<Type>vbar</Type>
<X>40</X>
<Y>4</Y>
<Height>4</Height>
<Percent>0</Percent>

A Horizontal Bar Widget

These start from the left and grow to the right.

• Name - The unique name of the widget.
• Type (hbar)- The type of widget
• X - The location of it's left side
• Y - The line the bar will be on
• Width - How long the bar will be.
• Percent (0-100) - What percentage of the bar do you want filled initially?

  <Name>myhbar</Name>
  <Type>hbar</Type>
  <X>2</X>
  <Y>3</Y>
  <Width>25</Width>
  <Percent>100</Percent>

A Combo Bar Widget

A combo bar widget. These are a hybrid of a horizontal bar and a string widget. This means that with one widget you can do this: vol:=====.

• Name - The unique name of the widget.
• Type (combobar)- The type of widget
• X - The location of it's left side
• Y - The location of its top line
• Width - The width is the total length of the text and the max length of the hbar. In this case there are hbar can occupy 7 chars as the text takes 4 chars.
• Text - Text to display on the left side of your hbar.
• Percent (0-100) - What percentage of the bar do you want filled initially?

<Name>volume</Name>
<Type>combobar</Type>
<X>11</X>
<Y>4</Y>
<Width>11</Width>
<Text>vol:</Text>
<Percent>0</Percent>

StatusText

What words or characters do you want displayed for the different modes

• Play - Playing text
• Pause - Paused text
• Stop - Stopped text
• Repeat - Repeat Track text
• RepeatPL - Repeat playlist text
• Random - Random mode enabled text
• Mute - Muted text
• Dynamic - Dynamic mode text

<StatusText>
<Play>Play</Play>
<Pause>Pause</Pause>
<Stop>Stop</Stop>
<Repeat>Rpt</Repeat>
<RepeatPL>Rpt+</RepeatPL>
<Random>Shfl</Random>
<Mute>Muted</Mute>
<Dynamic>Dyn</Dynamic>
</StatusText>

Reserved Widget Names

The list of reserved widget names is as follows. If you use these they will get updated by airLCD from Amarok. These reserved widgets are not fixed to any type, but it makes sense to use certain types for some of them. For example artist should be a string or a scroller. It makes no sense for it to be a hbar, vbar or combobar. Volume however can be any type. if a string the volume will be displayed as a number. If it is one of the bars the percentage will be shown by their length.

You can make up your own widgets. If you want some permanent text on the screen such as a % sign or a vertical bar to partition off part of the screen.

• artist - The name of the current artist
• album - The name of the current album
• title - The name of the current track
• genre - The genre of the current track
• bitrate - The bitrate of the current track
• year - The year of the current track
• currentTime - The elapsed time of the current track (e.g. 00:10)
• totalTime - The length of the current track (e.g. 03:47)
• comment - The comment field of the current track
• trackNumber - The current track position in the playlist
• totalTracks - The total number of track in the playlist
• score - The rating of the current track
• nowPlaying - A combination of artist and title. Ideal for small displays (e.g.Artist - Title)
• volume - The current volume
• mute - The mute status. Will display the mute text if Amarok is muted
• random - The random status. Will display the random text if Amarok is in random mode
• dynamic - The dynamic status. Will display the dynamic text if Amarok is in dynamic mode
• repeat - The repeat track status. Will display the repeat track text if enabled
• repeatPL - The repeat playlist status. Will display the playlist track text if enabled
• status - The current playing status. Will display the play, pause or stop text depending on which of those Amarok is doing.

Browser

Here you can configure your search parameter and how the brwoser behaves.

• CursorLocation - What line should be the active line
• ShowTrackNumber - When viewing an album, show the track numbers or not
• ScrollType - How to scroll the active line - takes the same options as a scroller (vertical, horizontal, marquee)
• ScrollSpeed - How fast to scroll the active line
• ScrollSeparator - If using marquee then what separator to use
• StartOnTrack - when viewing tracks start on the first track or on "Add All Tracks"
• Group - What filters do you want to use? You need as least one to be able to search your database. These work in the same way as the Collection filters in Amarok. The possible filter options are: Genre, Year, Artist, Album. They must be separted with a forward slash and with no spaces. You can have any combination or number or them as you like. Any depth from 1 to 4 is valid.

<CursorLocation>2</CursorLocation>
<ShowTrackNumber>true</ShowTrackNumber>
<ScrollType>vertical</ScrollType>
<ScrollSpeed>7</ScrollSpeed>
<ScrollSeparator>--</ScrollSeparator>
<StartOnTrack>true</StartOnTrack>
<Group>Genre/Year/Artist/Album</Group>

The LIRC Config file

This is another important file if you want to use a remote control to control airLCD and Amarok. An example one is included here: lircrc.conf. To see how to configure this file to suit your needs please see the help pages at the LIRC homepage. A typical key block will look like this though:

begin
prog = airlcd
button = PLAY
config = amarok playPause
end

• All key blocks are contained within a begin and end statement.
• The prog defines which program to send the command to when the button is pressed.
• button specifies which button on the remote the command is attached to.
• The command that gets sent to airLCD is specified on the config line.

The Amarok Command List

• amarok playPause - Toggle between playing and pausing
• amarok play - Start playing the current track
• amarok pause - Pause the current track
• amarok stop - Stop playing
• amarok seek 2 - Seek through the track. Positive numbers fast forward. Negative numbers rewind. The number is the number of seconds to seek by.
• amarok next - Skip forward to the next track
• amarok prev - Skip back to the previous track
• amarok volumeUp - Increase the volume
• amarok volumeDown - Decrease the volume
• amarok mute - Mute toggle
• amarok random - Random mode toggle
• amarok dynamic - Dynamic mode toggle
• amarok repeat - Repeat the current track toggle
• amarok repeatPlaylist - Repeat the current playlist toggle
• amarok clearPlaylist - clear the playlist
• amarok removeCurrent - remove the current track from the playlist
• amarok shufflePlaylist - shuffle the playlist order

The Browser Command List

• browser toggle - Toggle the visibility of the Browser
• browser show - Shows the Browser
• browser hide - Hides the Browser
• browser up 4 - Scroll up the current menu (only works when browser is visible). The number is optional. If none is supplied then the menu scrolls up by 1, otherwise it scrolls by the number specified.
• browser down 4 - Scroll down the current menu (only works when browser is visible). The number is optional. If none is supplied then the menu scrolls down by 1, otherwise it scrolls by the number specified.
• browser forward - Enter a sub menu (only works when browser is visible)
• browser back - Up to parent menu (only works when browser is visible)
• browser select - Add track(s) to playlist or execute the current menu option (only works when browser is visible)
• browser shutdown - Shutdown Amarok and the computer
• browser reboot - Shutdown Amarok and reboot the computer