<?xml version="1.0" encoding="UTF-8"?>

<!-- arch-tag: The user guide for the English Rhythmbox DocBook documentation
  -->

<sect1 id="rb-window">
<title>&application; Window</title>
	<sect2 id="rb-window-intro">
	<title>Overview</title>

	<para>The &application; window enables you to display and play your favorite music. Figure 1 shows the &application; window displaying the library.</para>
	<figure id="fig-rb-window">
	<title>The Library in the &application; Window</title>
	<screenshot>
	<mediaobject>
  		<imageobject>
    		<imagedata fileref="figures/rb-window.png" format="PNG"/>
  		</imageobject>
  		<textobject>
		<phrase>Show the &application; window showing Library.
		Callouts: Menubar, Player area, View pane, Side pane, 
		Statusbar.
		</phrase>
  		</textobject>
	</mediaobject>
	</screenshot>
	</figure>
	<para>Table 1 describes the components of &application; window.</para>

	<table frame="topbot" id="table-rb-window">
	<title>&application; Window Components</title>
	<tgroup cols="2" colsep="0" rowsep="0"><colspec colname="COLSPEC0" colwidth="29.39*"/>
	<colspec colname="COLSPEC1" colwidth="70.61*"/>
	<thead>
		<row rowsep="1">
			<entry valign="top">Component</entry>
			<entry valign="top">Description</entry>
		</row>
	</thead>
	<tbody>
		<row>
			<entry valign="top">Menubar</entry>
			<entry valign="top">Contains menus that you use to perform
			tasks in &application;.</entry>
		</row>
		<row>
			<entry valign="top">Side pane</entry>
			<entry valign="top">Enable you to switch between Library and &playlist;.</entry>
		</row>
		<row>
			<entry valign="top">Player area</entry>
			<entry valign="top">Provides access to details about the
			currently playing track and, in Library, enable you to
			search for a particular word or phrase.</entry>
		</row>
		<row>
			<entry valign="top">View pane</entry>
			<entry valign="top">Displays a list of available 
			tracks from:<itemizedlist>
			<listitem><para>Library</para></listitem>
			<listitem><para>Music groups</para></listitem>
<!--			<listitem><para>Audio CDs</para></listitem> -->		
			<listitem><para>Internet radio</para></listitem> 
			</itemizedlist>	
			</entry>
		</row>
		<row>
			<entry valign="top">Statusbar</entry>
			<entry valign="top">Displays global informations about 
			tracks in View Pane.</entry>
		</row>

	</tbody>
	</tgroup>
	</table>
	</sect2>

<sect2 id="intro-sidebar">
<title>The Side Pane</title>
	<screenshot>
	<mediaobject>
		<imageobject>
			<imagedata fileref="figures/rb-sidebar.png"
			format="PNG"/>
		</imageobject>
		<textobject>
		<phrase>Shows side pane with library and &playlist; icons.
		</phrase>
		</textobject>
	</mediaobject>
	</screenshot>
	<para>The side pane is where you can access your music library internet radio and
	your &playlist;  <!-- and CDs -->.The side pane can contain	
	the following icons:</para>
	<itemizedlist>
		<listitem><para>The &application; library, where all of the
	  imported songs will appear.</para>
		</listitem>
		<listitem><para>Any &playlist;  that have been created from imported songs.</para>
		</listitem> 
 		<listitem><para>Listen to Internet Radio stations.</para></listitem> 
		<!--
		<listitem>Audio CD's inserted into the computer's CD
		drives.
		</listitem> 
		-->
	</itemizedlist>
	<para>
	The display of the side pane can be toggled on or off by selecting <menuchoice><guimenu>View</guimenu><guimenuitem>Source List</guimenuitem></menuchoice>
	</para>
</sect2>

<sect2 id="player-area">
<title>The Player Area</title>
	<screenshot>
	<mediaobject>
		<imageobject>
			<imagedata fileref="figures/rb-player.png"
			format="PNG"/>
		</imageobject>
		<textobject>
		<phrase>Shows player area</phrase>
		</textobject>
	</mediaobject>
	</screenshot>
	<para>The 'player' area provides access to details about the
	currently playing track. When a track is not being played, this
	area shows no information. When 'Play' is selected, the track name
	is displayed, and underneath, the artist and the album names.
	</para>
	<para>A tracker is also displays, showing the progress of the
	playing. When tracker has focus, the arrow keys can be used to
	Fast-Forward or Rewind the playing track.
	</para>
	<tip><para>Clicking on the artist or album name (where they are
	underlined) will load the appropriate 'allmusic.com' page.</para>
	</tip>
	<tip><para>If you are using a mouse with a scroll wheel, you can 
	adjust the volume by scrolling up or down while the mouse pointer 
	is over the volume button.</para>
	</tip>
</sect2>
<sect2 id="status-area">
<title>The Statusbar</title>
	<screenshot>
	<mediaobject>
		<imageobject>
			<imagedata fileref="figures/rb-statusbar.png"
			format="PNG"/>
		</imageobject>
		<textobject>
		<phrase>Shows statusbar</phrase>
		</textobject>
	</mediaobject>
	</screenshot>
	<para>The statusbar contains additional information about the songs in the library or the &playlist;. In the left corner are two buttons for shuffling or repeating the songs. The display of the statusbar can be toggled on or off by selecting <menuchoice><guimenu>View</guimenu><guimenuitem>Statusbar</guimenuitem></menuchoice></para>
</sect2>

<sect2 id="rb-window-small">
<title>&application; Minimized Window</title>

	<para>By using <menuchoice><guimenu>View</guimenu><guimenuitem>Small Display</guimenuitem></menuchoice> the &application; window will be minimized displaying only the play area.</para>
	<screenshot>
	<mediaobject>
		<imageobject>
			<imagedata fileref="figures/rb-window-small.png"
			format="PNG"/>
		</imageobject>
		<textobject>
		<phrase>Shows player area in small display mode</phrase>
		</textobject>
	</mediaobject>
	</screenshot>

</sect2>
</sect1>

<sect1 id="Usage">
<title>Using &application;</title>

	<sect2 id="Playing">
	<title>Playing Music</title>

		<para>To play a track, either select the track and press the
		<guibutton>Play</guibutton> button on the toolbar, or simply
		double-click on the track to start playing.
		</para>
		<para>When track ends, &application; jump to play next track 
		in the list showed in view pane.
		</para>
		<para>In Library you can play all song from an artist or a
		single album simply select <guilabel>Album</guilabel>
		or <guilabel>Artist</guilabel> entry in 
		<link linkend="browser">library browser</link>.
		</para>
		
		<sect3 id="shuffle">
		<title>Shuffle</title>
			<screenshot>
			<mediaobject>
				<imageobject>
				<imagedata fileref="figures/rb-shuffle.png"
				format="PNG"/>
				</imageobject>
				<textobject>
				<phrase>Shows shuffle button in statusbar.
				</phrase>
				</textobject>
			</mediaobject>
			</screenshot>
			<para>When this option is selected, the tracks in the
			browser are played in 'random' order.
			</para>
		</sect3>

		<sect3 id="repeat">
		<title>Repeat</title>
			<screenshot>
			<mediaobject>
				<imageobject>
				<imagedata fileref="figures/rb-repeat.png"
				format="PNG"/>
				</imageobject>
				<textobject>
				<phrase>Shows repeat button in statusbar.
				</phrase>
				</textobject>
			</mediaobject>
			</screenshot>
		<para>When this option is selected, when the last track in the
		browser is played, the list is repeated from the beginning.
		</para>
		</sect3>

		<sect3 id="next-previous">
		<title>Next/Play/Previous</title>
			<screenshot>
			<mediaobject>
				<imageobject>
				<imagedata fileref="figures/rb-nextprev.png"
				format="PNG"/>
				</imageobject>
				<textobject>
				<phrase>Shows repeat button in toolbar.
				</phrase>
				</textobject>
			</mediaobject>
			</screenshot>
			<para>The Next and Previous buttons can be used to skip between tracks
 			whilst playing. If a song is currently playing, the previous button will restart the
 			song. Clicking on the Play button will start &application; playing the current track. Whilst playing this 				will change to a Pause icon.
			</para>

		</sect3>

		<sect3 id="volume">
		<title>Volume Control</title>
			<screenshot>
			<mediaobject>
				<imageobject>
				<imagedata fileref="figures/rb-volume-changer.png"
				format="PNG"/>
				</imageobject>
				<textobject>
				<phrase>Shows volume slider in toolbar.
				</phrase>
				</textobject>
			</mediaobject>
			</screenshot>
			<para>volume control in the right hand of the player area. Clicking on the loudspeaker icon will show 				the volume slider. Sliding this up and down will increase and decrease the volume. The loudspeaker 				icon will change to reflect the relative volume. 
			</para>
		</sect3>

	</sect2>


	<sect2 id="library">
	<title>The Library</title>

		<para>The &application; Library is an organized view of
		your music files. You can browse the Library by artist or
		by album. Once you have added a song to your Library you
		can play it directly or add it to a &playlist; to be played as
		part of a playlist.
		</para>
		<para>Choose <menuchoice><guimenu>Organize</guimenu><guimenuitem>Add to Library...
		</guimenuitem></menuchoice> to add music files to &application; Library. If you select a folder,
		all music file in all subfolders will be added to Library.
		</para>
		<warning>
		<para>The library is located in the <filename
		class="directory">.gnome2/rhythmbox</filename> directory
		in your home directory. It is unique for each user on
		your system. 
		</para>
		<para>If you delete or move this directory a new, empty
		library will be created when the application is next
		opened.</para>
		</warning>

		<sect3 id="adding">
		<title>Adding Songs</title>
			<para>A song can be added to the library in a few
			ways, as shown below;
			<itemizedlist>
				<listitem><para>
					Choose <menuchoice><guimenu>Music</guimenu>             <guimenuitem>Import Folder</guimenuitem></menuchoice> to add a single file or a whole folder to the library.</para>
				</listitem>
				<listitem><para>
				Drag and drop from other applications.
				eg. Nautilus</para>
				</listitem>
				<listitem><para>
				Opening a song/directory from Nautilus 
				with &application;, using the context menu. 
	 			<screenshot>
 					<mediaobject>
		 				<imageobject>
		 				<imagedata fileref="figures/rb-context-menu.png"
		 				format="PNG"/>
		 				</imageobject>
		 				<textobject>
		 				<phrase>The &application; context menu in Nautilus.</phrase>
		 				</textobject>
	 				</mediaobject>
	 			</screenshot></para>
				</listitem>
			</itemizedlist>
			</para>
		</sect3>

		<sect3 id="delete">
		<title>Deleting Songs</title>
			<para>To delete songs from the library, simply select
			the song then choose <menuchoice><guimenu>Edit</guimenu><guimenuitem>Delete</guimenuitem></menuchoice> item or press the
		<keycap>Delete</keycap> key.
			</para>
			<para>Once the last entry of an album (or artist) is
			deleted, the appropriate entry is also deleted from	
			Library browser.
			</para>
		</sect3>

		<sect3 id="browser">
		<title>Using the Browser</title>
			<para>The Browser allows the library to be easily
			browsed, showing the artist, then album of the current
			track. It is not shown when viewing a &playlist;<!-- or
			audio CD-->. Choose <menuchoice><guimenu>View</guimenu><guimenuitem>Browser</guimenuitem></menuchoice> to change browser visibility.
			</para>
			<screenshot>
				<mediaobject>
				<imageobject>
				<imagedata fileref="figures/rb-browser.png"
				format="PNG"/>
				</imageobject>
				<textobject>
				<phrase>The &application; browser</phrase>
				</textobject>
				</mediaobject>
			</screenshot>
			<para>When started, the browser defaults to viewing all
			artists, and all tracks. Selecting an individual artist
			will change the Album list to show all albums by this
			artist, and the track list changes to show all tracks
			for these albums. Selecting an album will change the
			track list to show only the contents of this album.
			</para>  
		</sect3>

<sect3 id="properties">
<title>Properties</title>
<para>
Choose <menuchoice><guimenu>Edit</guimenu><guimenuitem>Properties</guimenuitem></menuchoice> to view the properties of a particular track .
</para>
<para>
The <guilabel>Basic</guilabel> tab shows the details of the song, as Title, Artist, Date.
	<screenshot>
	<mediaobject>
		<imageobject>
			<imagedata fileref="figures/rb-basic.png"
			format="PNG"/>
		</imageobject>
		<textobject>
		<phrase>Basic song properties</phrase>
		</textobject>
	</mediaobject>
	</screenshot>
</para>

<para>
The <guilabel>Details</guilabel> tab of the dialog shows more detailed information about the file itself and its encoding. It also shows the <xref linkend="statistics"/> associated with the file.
	<screenshot>
	<mediaobject>
		<imageobject>
			<imagedata fileref="figures/rb-adv.png"
			format="PNG"/>
		</imageobject>
		<textobject>
		<phrase>Details song properties</phrase>
		</textobject>
	</mediaobject>
	</screenshot>

</para>


</sect3>

<sect3 id="search">
<title>Searching</title>
<para>To search the &application; library for a particular word or phrase, type into the search field, and the view will show all the entries that have the search criteria will be shown the in the tracks list.</para>
<figure id="fig-search">
<title>Search name entry</title>
<screenshot>
<graphic format="PNG" fileref="figures/rb-search.png" />
</screenshot>
</figure>
</sect3>
</sect2>

<sect2 id="statistics">
<title>Statistics</title>

<para>&application; can maintain statistics on the use of the library. &application; automatically records the number of plays, the last played date and allows you to rating each track. You can access this information through <guilabel>Additional</guilabel> tab in <xref linkend="properties"/> dialog for each song or directly in the View Pane for all songs displayed in Library or &playlist;; you can add proper columns via the <xref linkend="prefs"/> dialog.</para>
<figure id="fig-rb-stats">
<title>application; statistic in View Pane</title>
<screenshot>
<mediaobject>
  <imageobject>
    <imagedata fileref="figures/rb-stats.png" format="PNG"/>
  </imageobject>
  <textobject>
	<phrase>Show all statistic FIXME</phrase>
  </textobject>
</mediaobject>
</screenshot>
</figure>
<sect3 id="statistics-rating">
<title>Ratings</title>
<para>This allows each song in the library to be rated on a scale of 1 to 5 stars. To rate a song:
	<itemizedlist>
	<listitem><para>Select the song, choose <menuchoice><guimenu>Edit</guimenu><guimenuitem>Properties</guimenuitem></menuchoice>, select <guilabel>Details</guilabel> tab, click in different part of <guilabel>Rating</guilabel> entry to set required rating</para></listitem>
	<listitem><para>Click in different parts of the <guilabel>Rating</guilabel> column in View Pane to set the required rating.</para></listitem>
	</itemizedlist>
</para>
</sect3>
<sect3 id="statistics-plays">
<title>Number of plays</title>
<para>Each time a track has completed playing, its play count is incremented by 1. This will allow the most popular songs in the library to be easily identified.</para>
</sect3>
<sect3 id="statistics-last">
<title>Last played time</title>
<para>When the play count is incremented, the last played time is also recorded.</para>
</sect3>

</sect2>

<sect2 id="groups">
<title>Playlists</title>

<para>A &playlist; is an ad hoc list that has been created from songs in &application; library, to have a different sorting method from artist/album library default. It might consist of a list of songs of a particular 'genre', a specific group of artists, or even songs that are of a particular 'mood', or whatever you want.</para>

<para>To display the contents of a &playlist;, simply click on the required icon in side pane, and the view pane will change to show the contents.</para>

<sect3 id="groups-create">
<title>Creating &playlist;s</title>
 
  <para>To create a &playlist; use one of the following methods:</para>

  <itemizedlist>
    <listitem><para>
    Choose <menuchoice><guimenu>Music</guimenu><guimenuitem>Playlist</guimenuitem><guimenuitem>New Playlist...</guimenuitem></menuchoice>. The new &playlist; will appear in the side pane and ask you for the name of the new &playlist;. Enter your desired name into the empty textbox.

    	<figure id="fig-groups-create">
	<title>Dialog to create a new &playlist;</title>
	<screenshot>
	<graphic format="PNG" fileref="figures/rb-group-create.png" />
	</screenshot>
	</figure></para>
    </listitem>
    <listitem><para>    
    Choose <menuchoice><guimenu>Music</guimenu><guimenuitem>Playlist</guimenuitem><guimenuitem>New Automatic Playlist...</guimenuitem></menuchoice>. A dialog is displayed prompting for your desired inclusion or exclusion criterias. You may add more filters by clicking the <menuchoice><guimenu>Add</guimenu></menuchoice> button. Once you are done a new &playlist; will be created basing on your selctions in the side pane. Enter in the empty texbox your desired name for the Automatic &playlist;.
    	<figure id="fig-groups-auto">
	<title>Dialog to create a new automatic &playlist; </title>
	<screenshot>
	<graphic format="PNG" fileref="figures/rb-group-auto.png" />
	</screenshot>
	</figure></para>
    </listitem>
    <listitem><para>
    Choose <menuchoice><guimenu>Music</guimenu><guimenuitem>Playlist</guimenuitem><guimenuitem>Load Playlist...</guimenuitem></menuchoice> to load a previously saved &playlist; into &application;.</para>
    </listitem>
  </itemizedlist>



</sect3>

<sect3 id="groups-add">
<title>Adding Songs</title> 
  <para>To add songs, album or artist to an already existing group just drag and drop it from the library to the &playlist;''s icon in the side pane.</para>
</sect3>

<sect3 id="groups-delete">
<title>Deleting Songs</title>
<para>To delete songs from a &playlist;, simply select the song then choose <menuchoice><guimenu>Edit</guimenu><guimenuitem>Delete</guimenuitem></menuchoice><guimenu>Edit</guimenu> or simply press the  <keycap>Delete</keycap> key.</para>
</sect3>

<sect3 id="groups-remove">
	<title>Remove a &playlist;</title>
	<para>Right click on group icon in Side Pane to display the <guimenu>group menu</guimenu>. This will allow the deletion of the &playlist;. Selecting the <guimenuitem>Delete</guimenuitem> will delete the &playlist; (note that the 'content' of the &playlist; is not removed from the library, just the 'playlist'. An alternative way to do this is <menuchoice><guimenu>Music</guimenu><guimenuitem>Playlist</guimenuitem><guimenuitem>Remove...</guimenuitem></menuchoice>.</para>
</sect3>

<sect3 id="groups-arrange">
	<title>Changing the order of the &playlist;s in the side pane</title>
	<para>To change the position of the &playlist; in the side pane simply drag it on the position you want to have it. The library and the radio playlist will remain always on top.</para>
</sect3>

<sect3 id="groups-modify">
	<title>Modify an automatic &playlist;</title>
	<para>Right click on group icon in Side Pane to display the <guimenu>group menu</guimenu>. Selecting the <guimenuitem>Edit</guimenuitem> will allow you to modify the filters of the &playlist;.</para>
</sect3>

</sect2>

<!--
<sect2 id="cd">
<title>Audio CDs</title>
<sect3 id="cd-playing">
<title>Playing</title>
<para>When a CD is inserted to the CD drive, it will appear in the side pane, and the songs on it can be displayed in &application;''s main window.</para>
<para>To play and pause playback, or to skip forward or backwards, use the same controls as used for playing from the library.</para>
</sect3>
<sect3 id="cd-ripping">
<title>Ripping</title>
<para>...</para>
</sect3>
<sect3 id="cd-buring">
<title>Burning</title>
<para>...</para>
</sect3>

</sect2>
-->

<sect2 id="internet-radio">
<title>Internet Radio</title>
<sect3 id="radio-overview">
<title>Listening via Internet</title>
<para>The Internet Radio tuner can be used to listen to streamed audio files.</para>

<figure id="fig-iradio">
<title>Internet Radio in &application;</title>
<screenshot>
<graphic format="PNG" fileref="figures/rb-iradio.png"/>
</screenshot>
</figure>

</sect3>

<sect3 id="iradio-adding">
<title>Adding a station</title>
<para>New stations can be added to the Internet Radio tuner, using the <menuchoice><guimenu>Music</guimenu><guimenuitem>Add New Internet Radio Station</guimenuitem></menuchoice> menuoption.</para>
<figure id="fig-add-station">
<title>Adding a new station to &application;</title>
<screenshot>
<graphic format="PNG" fileref="figures/rb-iradio-add.png"/>
</screenshot>
</figure>
</sect3>

<sect3 id="iradio-modify">
<title>Changing the settings of a station</title>
<para>The settings of the Internet Radio stations can be changed, using the <menuchoice><guimenu>Music</guimenu><guimenuitem>Preferences</guimenuitem></menuchoice> menuoption.</para>
</sect3>

<sect3 id="iradio-delete">
<title>Removing a station</title>
<para>Internet Radio stations can be removed from the tuner list. Right click on the station and
select <guimenuitem>Delete</guimenuitem> to remove the station from the list.</para>
</sect3>

</sect2>


<sect2 id="notification-area">
<title>Panel Applet</title>

<para>The Notification Area is a Gnome feature that allows applications to add a small icon to the panel
while the program is running. &application; adds it''s icon to the notification area and this allows you to control &application; from your tray.</para>

<para>Using the &application; icon in the notification area, the following commands can be sent to the application: 
</para>
<para>
<itemizedlist>
<listitem><para>
Play | Pause &mdash; Play or Pause the currently selected song. This item changes depending on whether a song is playing or not.</para>
</listitem>
<listitem><para>
Previous &mdash; Skip to previous song in playlist.</para>
</listitem>
<listitem><para>
Next &mdash; Skip to next song in playlist.</para>
</listitem>
<listitem><para>
Show Window &mdash; choose whether or not the &application; window is visible or not.</para>
</listitem>

</itemizedlist>
<tip><para>If you are using a mouse with a scroll wheel, you can adjust the volume by scrolling up or down while the mouse pointer is over the panel applet.</para>
</tip>
</para>

<figure id="fig-notification">
<title>&application; in the Gnome Notification Area</title>
<screenshot>
<graphic format="PNG" fileref="figures/rb-notification-area.png"/>
</screenshot>
</figure>

<figure id="fig-notification-menu">
<title>Notification Area (showing menu)</title>
<screenshot>
<graphic format="PNG" fileref="figures/rb-notification-area-menu.png"/>
</screenshot>
</figure>
</sect2>
</sect1>

<sect1 id="customize">
<title>Customizing &application;</title>

	<para>
	You can customize &application; to suit your requirements and
	preferences. This section describes how to customize &application;.
	</para>

	<sect2 id="prefs">
	<title>Preferences</title>

		<para>Using the <guilabel>Preferences</guilabel> dialog you can
		customize how you want &application; to look. To display the
		<guilabel>Preferences</guilabel> dialog, choose <menuchoice><guimenu>Edit</guimenu><guimenuitem>Preferences
</guimenuitem></menuchoice>.
		</para>

 		<sect3 id="prefs-view">
 		<title>Columns</title>
 			<para>This section of the dialog allows you to select
 			which columns will be displayed.
 			</para>
 		<figure id="fig-general-preferences">
 		<title>General Preferences</title>
		<screenshot>
			<mediaobject>
			<imageobject>
			<imagedata fileref="figures/rb-prefs-general.png" 
			format="PNG"/>
			</imageobject>
			<textobject>
			<phrase>Show the general &application; preferences dialog.</phrase>
			</textobject>
			</mediaobject>
		</screenshot>
		</figure>
		</sect3>

		<sect3 id="prefs-library">
		<title>Browser preferences</title>
			<para>This section of the dialog allows you to select
			how the browser will be displayed.
			</para>
		<figure id="lib-preferences">
 		<title>Library Preferences</title>
		<screenshot>
 			<mediaobject>
 			<imageobject>
 			<imagedata fileref="figures/rb-prefs-library.png" 
 			format="PNG"/>
 			</imageobject>
 			<textobject>
 			<phrase>Show the library preferences dialog.
 			</phrase>
 			</textobject>
 			</mediaobject>
		</screenshot>
		</figure>
		</sect3>

		<sect3 id="prefs-ipod">
		<title>iPod preferences</title>
			<para>This section of the dialog allows you to select
			how the iPod browser will be displayed.
			</para>
		<figure id="fig-preferences">
 		<title>Library Preferences</title>
 			<mediaobject>
 			<imageobject>
 			<imagedata fileref="figures/rb-prefs-ipod.png" 
 			format="PNG"/>
 			</imageobject>
 			<textobject>
 			<phrase>Show the iPod preferences dialog.
 			</phrase>
 			</textobject>
 			</mediaobject>
		</figure>
      <para>Changing the preferences here will also change
	the settings of the library.
			</para>
		</sect3>
	</sect2>
</sect1>
