path: root/doc/noatun/index.docbook

<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
  <!ENTITY kappname "&noatun;">
  <!ENTITY package "kdemultimedia">
  <!ENTITY % English "INCLUDE" > <!-- change language only here -->
  <!ENTITY % addindex "IGNORE">
]>

<book lang="&language;">
<bookinfo>
<title>The &noatun; Handbook</title>

<authorgroup>
<author>
<firstname>Charles</firstname>
<surname>Samuels</surname>
<affiliation>
<address><email>charles@kde.org</email></address>
</affiliation>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
<year>2001</year><year>2002</year>
<holder>Charles Samuels</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>

<date>2002-03-01</date>
<releaseinfo>2.00.00</releaseinfo> <!-- Use App version here -->

<abstract>
<para>&noatun; is a fully-featured plugin-based media player for &kde;.</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>Noatun</keyword>
<keyword>kdemultimedia</keyword>
<keyword>mp3</keyword>
<keyword>music</keyword>
<keyword>media</keyword>
</keywordset>
</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>&noatun; is a fully-featured plugin-based media player for &kde;.</para>

<sect1 id="features">
<title>Features</title>

<para>&noatun; is an elaborate front-end to &arts; &mdash; the Analog
Real-Time Synthesizer.  To add additional playobjects, go to <ulink
url="http://noatun.kde.org/plugins/">
http://noatun.kde.org/plugins.phtml</ulink>, or <ulink
url="http://mpeglib.sf.net">http://mpeglib.sf.net</ulink>.  By
default &arts; supports MP3 and MPEG-1.  Vorbis is also supported if the Vorbis
libraries were available during the compilation of &kde;.  </para>

</sect1>
</chapter>

<chapter id="using-noatun">
<title>Using &noatun;</title>

<para>&noatun;, by  default, starts with the Excellent user interface
plugin.  This plugin was chosen  as it bears the most similarity to
other &kde; applications.</para>

<para>&noatun; is unique in that no two installations are the same,
and there is no standard interface, although there is a default
one. You're free to mix-and-match your selection of plugins, and
customize &noatun; until it is your ideal media player!
</para>

<sect1 id="title-format">
<title>Title Format</title>
<para>
The &noatun; Preferences Window has an odd <guilabel>Title Format</guilabel> text box.  You can enter a format string to customize how titles appear.
</para>

<itemizedlist>
<listitem><para>Any text appears normally, unless it is within a <literal>$( )</literal>.</para></listitem>
<listitem><para>The text within <literal>$( )</literal> will read the &noatun; property
for the given item, and replace the text with it.</para></listitem>
<listitem><para>If, within the <literal>$( )</literal> are quotes, the text within the quotes
will be displayed normally, but only if the property of the name exists.</para></listitem>
<listitem><para>The quotes may be either at the beginning of the <literal>$( )</literal>, at the end of 
it, or at both the end or the beginning</para></listitem>
</itemizedlist>

<para>
	For example, <literal>$(bitrate)</literal> is replaced by the		bitrate of the file, as loaded
	by the Metatag plugin.  However, if you insert quotes into that field,
	the text within the quotes will be displayed:
<literal>$(bitrate"kbps")</literal> for
	example will display the bitrate of the file, followed by the characters 	<literal>&quot;kbps&quot;</literal>.  Neither will be displayed if the property <quote>bitrate</quote> does not exist.
</para>	
</sect1>

</chapter>

<chapter id="using-noatun-plugins">
<title>Using &noatun; Plugins</title>

<para>You can select different plugins by going to the
<guimenuitem>Settings</guimenuitem> menu, and selecting
<guimenuitem>Configure &noatun;...</guimenuitem>.  Move to the
<guilabel>Plugins</guilabel> page by selecting the appropriate list item.
Then you can enable enable plugins by selecting the checkbox near their name.
&noatun; requires at least one User-Interface plugin, and requires exactly
one Playlist plugin.
</para>

<sect1 id="milk-chocolate">
<title>Milk Chocolate</title>

<para>Milk Chocolate is a small, simple User Interface. The buttons
behave mostly like a CD-player, and the <guiicon>eject</guiicon>
button opens the playlist.  The <guiicon>sheet with a cross</guiicon>
button removes the current playlist item, but does not delete the file
from disk, and the <guiicon>arrow</guiicon> button sets the looping
mode.  A menu is available by &RMB; clicking anywhere in the
window.</para>

</sect1>

<sect1 id="young-hickory">

<title>Young Hickory</title>

<para>Young hickory is a plugin for the &kde; System Tray, the area near the
clock, by default.</para>

<para>&RMB; clicking on the icon will show a small menu, and &LMB; clicking
will toggle the visibility of your &noatun; user-interface windows.  Note that
playlists, for example, are not considered user-interfaces.</para>

</sect1>

<sect1 id="html-exporter">
<title><acronym>HTML</acronym> Playlist Export</title>

<para>This plugin will place your playlist in a nice
<acronym>HTML</acronym> table.  Its preferences page will allow you to
set colors, background image, and enable the Hover mode, for changing
colors when the cursor is over a link.</para>

<para>After setting options, the <guimenu>Actions</guimenu> menu's
<guimenuitem>Export Playlist...</guimenuitem> will open a file dialog
for you to select where to save the output. </para>

</sect1>

<sect1 id="kjofol-skin">
<title><application>K-Jöfol</application> Skins</title>

<para>The &noatun; <application>K-Jöfol</application> skin loader is a
reimplementation of a &Windows; program under the same name.</para>

<para>&noatun;'s implementation has a few limitations,
unfortunately. For instance the skins must be uncompressed on disk in
order to load them.</para>

<para>To install a skin (in the &Windows; ZIP format) you can use
the skin-installer that can be found in the preferences-dialog of
&noatun;.</para>

<para>Because some skins are not packaged correctly and the skin-installer
can not guess everything you can still follow these commands if installation
of a certain skin failed:</para>

<screen><prompt>%</prompt> <userinput><command>cd</command> <filename class="directory">$KDEHOME/share/apps/noatun</filename></userinput>
<prompt>%</prompt> <userinput><command>mkdir</command> <option>kjskins</option></userinput> (if needed)
<prompt>%</prompt> <userinput><command>cd</command> <option>kjskins</option></userinput>
<prompt>%</prompt> <userinput><command>mkdir</command> <option>new_skin</option> ; <command>cd</command> <replaceable>new_skin</replaceable></userinput>
<prompt>%</prompt> <userinput><command>unzip</command> <replaceable>/path/to/new_skin.zip</replaceable></userinput></screen>

<para>You can also make your own skins with the tutorial at <ulink
url="http://www.angelfire.com/mo/nequiem/tutorial.html">http://www.angelfire.com/mo/nequiem/tutorial.html</ulink>.
</para>

</sect1>

<sect1 id="splitplaylist">
<title>The Split Playlist</title>

<para> The Split Playlist had a simple, classic-style design.  Double
clicking on an entry will play it (as will selecting it and pressing
<keycap>Enter</keycap>).  You can drag files and
&URL;s in as well.  </para>

<para>
As of &kde; 3.0, the Split Playlist (<acronym>SPL</acronym>) stores its
data in an &XML; format, but will automatically
import the <acronym>m3u</acronym> list if the &XML; file
does not exist.  This means that you can write to the m3u file, and delete
the &XML; file, to automatically generate playlists.
</para>

<para>
The name Split Playlist is a bit of a misnomer, as the list is not actually split.
It results from the original design (back in the early &noatun; days) actually
having it split.
</para>
</sect1>

<sect1 id="winampskin">
<title>Winamp Skins</title>
<para>
If you're actually using the <trademark>Winamp</trademark> skin,
it should seem familiar to you.  Clicking on the timer will
toggle it between count-down and count-up mode.  Selecting
the Scope region under it will enable and disable the scope.  You
can also double click on the titlebar to toggle Windowshade mode.
<mousebutton>Right</mousebutton> clicking (or clicking on the top-left icon will show the
standard &noatun; toolbar.
</para>
<para>
You can install new skins by, in 
<filename class="directory">$KDEHOME/share/apps/noatun/skins/winamp</filename>,
creating a folder for them, and then unzipping the skin in there.  <trademark>Winamp</trademark>
skin files with the extension <literal role="extension">.wsz</literal> can be treated
as normal zip files.  You may have to rename them first, however, to be
able to unzip them.
</para>
</sect1>

<sect1 id="metatag">
<title>Metatag</title>
<para>
Metatag is a plugin that loads information about a file through the use
of KFile, the same mechanism that provides &konqueror; with those tooltips
when you hover a mouse over files.  Aside from loading the information,
it supports editing it via the <guimenu>Actions'</guimenu> menu subitem 
<guimenu>Tag Editing</guimenu>.  It supports editing of <acronym>ID3</acronym>
tags, as well as OggVorbis tags.  It also reads the bitrate from files.
</para>
</sect1>

<sect1 id="keyz">
<title>Keyz</title>
<para>
Carsten Pfeiffer decided to break with the long lived &noatun; tradition
of naming a plugin in the most inaccurate way possible, as proven by both
Milk-Chocolate, Young Hickory, and countless others.  What's the value
in just converting an S to a Z?  Sounds like something American-English speakers would do!
</para>
<para>
However, just because the name is unoriginal doesn't mean this is any
less of a plugin.  Indeed, this one lets you assign keystrokes to some
&noatun; actions.  The real beauty is that these keystrokes work from
anywhere, not just from &noatun;.  So this may finally make those
<quote>Multimedia Keyboards</quote> worthwhile.
</para>
</sect1>

<sect1 id="ir-control">
<title>Infrared Control</title>
<para>
If you have a remote control for your computer (such as those found
on television cards with <trademark class="registered">Brooktree</trademark>
tuners), and your infrared remote control is supported by
<ulink url="http://www.lirc.org">LIRC</ulink>, this should work.  Like Keyz,
the name is unexciting, but the plugin allows you to assign actions to
button presses.
</para>
<para>
To assign an action to a keypress, load the plugin, go to the Infrared Control
page in the &noatun; configuration window.  Select the keypress in the 
list, and then choose the action to perform with the combo box below.  If, in
an action like Volume control, you want the action to be performed repeatedly,
check the box and select the interval between actions.
</para>
<para>
If you have a <acronym>TV</acronym> card, a convenient trick is to 
assign the <guibutton>Mute</guibutton> button to Pause, thereby allowing you to mute your
<acronym>TV</acronym> display application while unpausing &noatun;,
and vice-versa, particularly useful in the case of commercials.
</para>
</sect1>
</chapter>

<chapter id="questions-answers-and-tips">

<title>Questions, Answers, and Tips</title>

<qandaset id="faq">
<title>Frequently-asked questions</title>
<qandaentry>
<question>
<para>The music skips a lot when moving windows.</para>
</question>
<answer>
<para> 
You can have &arts; buffer more as follows: 
</para> 

<itemizedlist> 
<listitem><para>Start &kcontrol;</para></listitem>
<listitem><para>Move to the <guilabel>Sound</guilabel>
group</para></listitem> 
<listitem><para>Move to the <guilabel>Sound
Server</guilabel> section</para></listitem> 
<listitem><para>Increase the response time&mdash;384ms is
usually sufficient 
for most computers.</para></listitem> 
</itemizedlist> 

<para> 
You may also consider running the soundserver with real-time priority 
if setting the response time doesn't help. Be aware that this can 
cause your system to lock-up. 
</para> 

</answer>
</qandaentry>
<qandaentry>
<question>
<para>I can't remove a playlist or user-interface from the plugins list.</para>
</question>
<answer>
<para>
Since &noatun; requires at least one user-interface loaded, and exactly
one playlist, you have to add a new user-interface plugin before
removing the old one.  Adding a new playlist will automatically
remove the old one.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Where can I get more plugins?</para>
</question>
<answer>
<para>
Third-party developers can submit their own plugins to the
<ulink url="http://noatun.kde.org/plugins/">&noatun; web-site</ulink>, where they
can be downloaded by you, the users.
</para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>How do I write a &noatun; plugin?</para>
</question>
<answer>
<para>
Documentation, an <acronym>API</acronym> reference, and example source code is
available at the <ulink url="http://noatun.kde.org">&noatun; web-site</ulink>.
Also, in the spirit of Open Source software the source code to
&noatun; and all default plugins is available.
</para>
</answer>
</qandaentry>
</qandaset>
</chapter>

<chapter id="credits-and-licenses">
<title>Credits and Licenses</title>

<para>Program copyright 2000-2002 Charles Samuels
<email>charles@kde.org</email></para>

<para>Documentation copyright 2002 Charles Samuels
<email>charles@kde.org</email></para>

<para>&noatun; has been brought to you by the following people:</para>

<itemizedlist>
<listitem>
<para>Charles Samuels <email>charles@kde.org</email></para>
</listitem>
<listitem>
<para>Neil Stevens <email>multivac@fcmail.com</email></para>
</listitem>
<listitem>
<para>Stefan Westerfeld <email>stefan@space.twc.de</email></para>
</listitem>
<listitem>
<para>Martin Vogt <email>mvogt@rhrk.uni-kl.de</email></para>
</listitem>
<listitem>
<para>Malte Starostik <email>malte.starostik@t-online.de</email></para>
</listitem>
<listitem>
<para>Nikolas Zimmermann <email>wildfox@kde.org</email></para>
</listitem>
<listitem>
<para>Stefan Schimanski <email>1Stein@gmx.de</email></para>
</listitem>
</itemizedlist>
<!-- TRANS:CREDIT_FOR_TRANSLATORS -->

&underFDL;
&underBSDLicense;

</chapter>

<appendix id="installation">
<title>Installation</title>

<sect1 id="how-to-obtain-Noatun">
<title>How to obtain &noatun;</title>

&install.intro.documentation;

</sect1>

<sect1 id="requirements">
<title>Requirements</title>

<para>&noatun; requires at least a Pentium 200 with &Linux;, a PowerPC with
&Linux; 2.4.1 or later, or several other platforms.  Support for more platforms
will be available in later versions.</para>

<para>For a platform to be supported easily, it must have pthread support, and
the <acronym>OSS</acronym> sound output system, however <acronym>ALSA</acronym>
is supported under &Linux;.</para>

</sect1>

<sect1 id="compilation-and-installation">
<title>Compilation and Installation</title>

&install.compile.documentation;

<para>Should you run into any problems, please report them to
the author at <email>charles@kde.org</email>.</para>

<para>If you have this documentation, you've probably already compiled
&noatun;</para>

</sect1>

</appendix>

<glossary id="glossary">
<title>Glossary</title>

<glossentry id="gloss-mc">
<glossterm>Milk Chocolate</glossterm><glossdef>
<para>
	Milk Chocolate is a simple, minimalist user interface plugin
</para></glossdef></glossentry>

<glossentry id="gloss-arts">
<glossterm>&arts;</glossterm><glossdef>
<para>
	&arts; is the Analog Real-time Synthesizer.  A powerful
	media framework used by &noatun;
</para></glossdef></glossentry>
<glossentry id="gloss-kj">
<glossterm>K-Jöfol</glossterm><glossdef>
<para>
	This plugin loads skins originally used under a &Windows;
	media player under the same name.
</para></glossdef></glossentry>

<glossentry id="gloss-keyz">
<glossterm>Keyz</glossterm><glossdef>
<para>
	Keyz allows you to assign keystrokes to actions in &noatun;
</para></glossdef></glossentry>
<glossentry id="gloss-young-hickory">
<glossterm>Young Hickory</glossterm><glossdef>
<para>
	Young Hickory is a system tray plugin.
</para></glossdef></glossentry>
<glossentry id="gloss-kaiman">
<glossterm>Noatun</glossterm><glossdef>
<para>
	Kaiman is a plugin that loads skins from the media player
	GQMPEG.  Kaiman is also &noatun;'s predecessor, and was
	distributed with &kde; for &kde; 2.0. When
	&noatun; was introduced in &kde; 2.1, Kaiman's skin loader
	became a &noatun; plugin.
</para></glossdef></glossentry>

</glossary>

&documentation.index;
</book>