summaryrefslogtreecommitdiffstats
path: root/doc/noatun/index.docbook
blob: 7a6bd2b7d73b11bf8a8d62cba06b43f0619f883a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
<?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>