= Sound Themes =

== Installing ==
The theme.xml file, all sound files (along with any image preview) should be placed in `$PURPLEHOME/themes/$THEMENAME/purple/sound/`, where $PURPLEHOME by default is ~/.purple on Linux.
Alternatively, in Linux the files can be put in /usr/share/themes/$THEMENAME/purple/sound/, or into $XDG_DATA_HOME/themes/$THEMENAME/purple/sound/, where $XDG_DATA_HOME defaults to ~/.local if not set.

== Creating ==
A theme consists of a XML file called theme.xml, all of the sound files used by the theme, and an optional image preview/logo file.  

The root node of the XML file contains all information about the theme including the name, author, type of theme (sound), as well as the name of a image file to display as a preview of the theme.  The theme file should also contain a description element which gives a short description of the theme.

Under the root node, the theme should contain a list of event elements.  Each event element should contain a name and a file attribute.  The name attribute corresponds to the event for which the sound should be played, while the file attribute is the name of the file to play.  A file can be used for multiple events and events can be left off so a sound is not played for a particular event. The event names are:
 * login - Buddy logs in
 * logout - Buddy logs out
 * im_recv - Message received
 * first_im_recv - Message received begins conversation
 * send_im - Message sent
 * join_chat - Person enters chat
 * left_chat - Person leaves chat
 * send_chat_msg - You talk in chat
 * chat_msg_recv - Others talk in chat
 * pounce_default - A Buddy Pounce is triggered
 * nick_said - Someone says your username in chat
 * got_attention - Attention received

An example theme would look like:

{{{
<?xml version="1.0" encoding="UTF-8"?>
<theme type="sound" name="Example sound theme" author="Your name" image="logo.png">
	<description>This is an example theme.</description>
	<event name="login" file="contact_logged_on.mp3"/>
	<event name="logout" file="contact_logged_off.mp3"/>
	<event name="im_recv" file="im_received.mp3"/>
	<event name="first_im_recv" file="new_im_received.mp3"/>
	<event name="send_im" file="im_sent.mp3"/>
	<event name="join_chat" file="contact_logged_on.mp3"/>
	<event name="left_chat" file="contact_logged_off.mp3"/>
	<event name="send_chat_msg" file="chat_message_sent.mp3"/>
	<event name="chat_msg_recv" file="chat_message_received.mp3"/>
	<event name="pounce_default" file="pounce_default.mp3"/>
	<event name="got_attention" file="got_attention.mp3"/>
        <!-- event "nick_said" is not set-->
</theme>
}}}
The full list of events can be found in the [http://developer.pidgin.im/viewmtn/revision/file/075c2902b90abb6349a6b689e26fa0ecf720ca04/finch/gntsound.c source code].

Note: Sound files must be in a format compatible with the sound playing method used (for example, only Wave files may be used on Windows)

== Example Themes ==
   * [attachment:wiki:SoundThemes:Synthetic_Frost.zip  Synthetic Frost] port of the [http://www.adiumxtras.com/index.php?a=xtras&xtra_id=4346 Adium sound theme] by [http://www.adiumxtras.com/index.php?a=users&do=profile&user_id=11794 SyntheticFrost]
   * [attachment:wiki:SoundThemes:Synthetic_Frost_in_WAV.zip  Synthetic Frost in WAV-format] conversion of the above Adium sound theme by [http://portable-pidgin.de Dirtsa] 
   * [attachment:wiki:SoundThemes:Glados.tar.gz GLaDOS Sound theme for Pidgin] by [http://difuzyon.net/hsa2/ H.Gökhan SARI]


